rsm-markup 0.2.4

ReStructured Manuscript (RSM) markup language

RSM: (R)e-(S)tructured (M)anuscripts

RSM is a suite of tools that aims to change the format of scientific publications using modern web technology. Currently, most scientific publications are made with LaTeX and published in PDF format. While the capabilities of LaTeX and related software are undeniable, there are many pitfalls. RSM aims to cover this gap.

What RSM does differently

One of the main aims of the RSM suite is to provide scientists with tools to author scientific manuscripts in a format that is web-ready in a transparent, native way that is both easy to use and easy to learn. In particular, RSM is a suite of tools that allow the user to write a plain text file (in a special .rsm format) and convert the file into a web page (i.e. a set of .html, .css, and .js files). These files can then be opened natively by any web browser on any device. In the rest of this README, and in the documentation, the files output by RSM are referred to as the document, or the output document.

Features

RSM's output document has the following features:

1. Responsive: its geometry and layout adapt to the device it is being read on.

2. Accessible: the user is free to change the geometry, layout, typography and other settings of a RSM document.

3. Separation of concerns: internally, the structure and content of an RSM document are separate from the style and look-and-feel. The former are stored in HTML format, while the latter are treated with CSS and Javascript.

4. Interactive: RSM documents support context-relevant tooltips, embedded video or animations, enhanced document navigation, smart search, content folding, smart context menus, and many other opportunities for interaction.

5. Extensible: potential to extend using the entire ecosystem of modern web technologies

Components

The RSM framework is comprised of several components, each of which can be used in isolation, though using them in unison yields best results.

1. The RSM file format, .rsm is a format that allows writers to produce technical documents that get rendered directly into web-ready formats. RSM is a plain text format so you can edit a .rsm file with your favorite text editor. Fundamentally, the .rsm file format is essentially an extension of the .rst file format.

2. The RSM project is simply a folder that contains a .rsm file and its .html output. When sharing your RSM document, you should always share the entire RSM folder, not just one file.

3. rsm-edit, the RSM text editor, is a text editor specifically designed to edit .rsm files. Besides having basic text editing features, rsm-edit has features specific to producing .rsm files. Currently work in progress.

4. rsm-view, the RSM reader, is a file viewer specifically designed to show .rsm files. It is essentially a web browser, though it has some extra features. Currently work in progress.

5. rsm-make, the RSM command line utility, is for now the main way to execute all the core functionality of the RSM framework.

Basic usage

One of the objectives of the RSM project is to make it possible to produce and share documents that can be viewed easily at any time anywhere, without restriction of device, software, software versions, operating system, internet connection, etc. Therefore, the only required component is a .rsm file. An basic .rsm file can be produced with any text editor, and it can be viewed on any modern web browser, even without internet connection.

Advanced usage

Additionally to the basic features, the RSM project also provides advanced features that do require the adoption of some of the other components. For example, writers using the .rsm format may find it useul to use rsm-edit. Accordingly, some of the features of rsm-edit can only be fully enjoyed by readers via rsm-view.

Adopting the rsm-edit and rsm-view is not necessarily the most accessible thing. However, the project is currently in proof-of-concept stage. If it proves to be a useful tool and the community starts adopting it, then care will be placed to guarantee that adopting the rsm-view and rsm-edit tools is as easy and accessible as possible. Specifically, there should be cloud versions of both tools where all that's necessary is an internet connection.

Related projects

This is a list of other projects or ideas that have inspired RSM or are somehow related.

• https://lamport.azurewebsites.net/pubs/proof.pdf
• https://github.com/Mathpix/mathpix-markdown-it
• distill.pub