Frequently asked questions#

What’s wrong with LaTeX + PDF?#

There’s nothing inherently wrong with writing scientific manuscripts in LaTeX and publishing them in PDF format. However, the LaTeX ecosystem was designed at a time where the main medium of scientific publication was physically printed books and magazines. Today, this is far from the truth as more and more scientists read (and write) papers online. The PDF format and many of LaTeX’s features are designed to output documents that will be physically printed, and this is not necessarily the best option when reading a digital document. These are some of the problems that arise when reading PDFs on a digital device:

  1. A PDF file has a fixed geometry (page size, margins, etc), while digital devices (laptops, tablets, mobile phones) have a variety of screen sizes and shapes. The same PDF file may be read easily in, for example, a laptop screen, but not in a tablet or mobile screen.

  2. A PDF file has a fixed layout (the relative positions of text, headers, figures, tables, etc). In contrast, in the last decade, digital documents and especially web pages are moving toward being responsive, that is, their layout adapts to the features of the devices they are being read on.

  3. A PDF file has a fixed typography (font family, weight, size, color, etc). For accessibility reasons, a reader may prefer different typographic choices. For example, some font families are designed to be read more easily by people with dyslexia, while high-contrast color schemes are preferred by people with certain sight conditions. PDF files cannot adapt to the preferences of the user without using external tools.

  4. While there are ways to configure LaTeX to output files in a format different than PDF (e.g. EPS, DVI), most of the above critiques still hold true.

  5. While there are ways to transform the output of LaTeX to a web-ready format (i.e. HTML), this is always an extra step that must be done outside of the LaTeX ecosystem. As a result, not all of the LaTeX features translate transparently to the final output and some post-processing is sometimes necessary.

What’s wrong with Markdown?#

There’s nothing inherently wrong with writing a scientific manuscript in Markdown and then using some tool to render it into a fully-featured web page. In fact, some modern tools such as Quarto are based on (extensions of) the Markdown language. However, ReStructured Manuscripts uses its own language for a number of reasons.

  1. One of the main features of RSM is being able to reference any place of the manuscript, even single words, and automatically showing tooltips to the referenced content. Markdown does not allow the user to reference arbitrary text in the manuscript, and would require non-trivial extensions to do so.

  2. Rather than implement RSM’s core features as mere language extensions, RSM is a language that supports these features as first-class citizens.

  3. One of the main benefits of Markdown is its minimal syntax. There are very few special characters and the language basically gets out of the way as much as possible. If RSM had been written as a Markdown extension, it would have been unavoidable to add new syntax and more special characters to Markdown. In so doing, we would have countered one of the main benefits of the language. Instead of making “Markdown but not Markdown”, we decided to implement our own language.

What’s wrong with ReST?#

ReStructured Text (ReST) is another popular markup language used primarily by the Sphinx documentation builder and static site generator. The first version of RSM was in fact implemented as an extension to ReST, and used Sphinx in the back end. However, this quickly became unsustainable as having the core features of the language be implemented as Sphinx extensions made development, testing, and overall developer experience awful. Furthermore, those extensions were already going beyond what is reasonable to implement as a language extension. Instead, we decided to create a new language, taking the best of both Markdown and ReST. The name ReStructured Manuscripts is a nod to its roots in ReStructured Text, as well as a nod to structured proofs, the way that RSM handles mathematical writing in manuscripts.

Is CSS better than Tex?#

Usually, scientific manuscripts use the TeX engine for page layout (at least those manuscripts written with LaTeX and related tools). Instead, RSM being a web-native format, uses CSS as layout engine. TeX is widely regarded as some of the best and most robust and bug-free software ever produced, and is without a doubt better than CSS at laying out a page of fixed geometry. But therein lies the difference: the purpose of RSM is to produce manuscripts that are responsive to device, screen size, and user preferences, and TeX cannot achieve this since it was never designed to do so. The standard engine for laying out applications with such requirements is CSS, and it is undoubtedly the best and most widely available software for doing so.