CLI Commands#
RSM provides three command line utilities when installed locally:
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.
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.
-v
or-vv
to control the verbosity.--log-no-timestamps
to remove timestamps from logs (useful during testing).--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 byrsm-lint
and it adheres to the same format used by other static analysis tools such aspylint
andmypy
."plain"
is useful during testing.
Misc.#
rsm-render
accepts another flag,-r
which uses the translator that outputs handrails (see Translator).rsm-lint
ignores-s
since by default it has no output other than logs.rsm-lint
ignores-v
and-vv
since it sets its own specific loglevel.rsm-lint
ignores-r
since it never reaches the translation step.rsm-lint
andrsm-render
do not accept--serve
.