CLI Commands#

RSM provides three command line utilities when installed locally:

  1. rsm-make Takes a file containing RSM source and outputs a fully functioning website.2

. rsm-render Takes a file containing RSM source and translates it to HTML. It does

not make a working website, it only computes the HTML body and prints it to screen.

  1. rsm-lint Takes a file containing RSM source and runs consistency and sanity checks. It outputs a set of warnings and suggestions to screen. It does not write any HTML, and it does not overwrite the source file.

These three commands correspond one-to-one to the functions in the main package: rsm.make(), rsm.render(), and rsm.lint().

Most users will spend most of their time running rsm-make. The purpose of rsm-lint is to be integrated to text editors in the future. rsm-render is mostly useful for development, testing, and rapid iteration at the CLI or python REPL.

Tip

Emacs users can already make use of rsm-lint automatically by enabling flycheck and installing rsm-mode.

Arguments and flags#

We focus on the CLI flags accepted by rsm-make. The other two commands have very similar flags. For a complete and updated list of arguments, run rsm-make -h at your terminal. Here we provide some common examples.

Suppose you have a file called manuscript.rsm containing RSM source code. The simplest way of building your web manuscript is via:

$ rsm-make manuscript.rsm

This will output a index.html file in the current directory, as well as a static/ folder containing all necessary assets.

Input#

By default, rsm-make interprets its first argument as a path to a file. You may also provide RSM source directly at the terminal via the -c flag:

$ rsm-make ":manuscript: Hello. ::" -c

Automatic builds#

Using the --serve flag you may specify a path to rsm-make and instruct it to watch the file for any modifications. rsm-make will rebuild the entire manuscript whenever there is a change in the file, without you having to manually relaunch the command.

$ rsm-make manuscript.rsm --serve
[server] Serving on http://127.0.0.1:5500
[handlers]Start watching changes
[handlers]Start detecting changes
...

You may now open your browser at the address http://127.0.0.1:5500 and see your manuscript. Whenever the manuscript.rsm file changes on disk, the browser will automatically reload and show the changes.

Output#

Sometimes it is useful to run the build without producing any output, just to see the logs. This is possible with the -s flag. This is specially useful with rsm-render and rsm-lint.

Logs#

There are three flags to control the logs.

  1. -v or -vv to control the verbosity.

  2. --log-no-timestamps to remove timestamps from logs (useful during testing).

  3. --log-format to change the format of the logs. The default value is "rsm" and it is most readable by humans. "json" is useful when transferring the logs to another application such as the online editor. "lint" is the format used by default by rsm-lint and it adheres to the same format used by other static analysis tools such as pylint and mypy. "plain" is useful during testing.

Misc.#

  1. rsm-render accepts another flag, -r which uses the translator that outputs handrails (see Translator).

  2. rsm-lint ignores -s since by default it has no output other than logs.

  3. rsm-lint ignores -v and -vv since it sets its own specific loglevel.

  4. rsm-lint ignores -r since it never reaches the translation step.

  5. rsm-lint and rsm-render do not accept --serve.