mdoc

Modular documents

With mdoc you can create recursive, modular documents. It has four main features:

1. Include entire files in other documents.
2. Include snippets of files in other documents.
3. Use externally defined variables throughout your documents.
4. Evaluate Python expressions inside your documents.

That's the 'modular' part. The 'recursive' part means that the included documents can themselves include other documents, ad infinitum.

For example, this readme was generated from the various pieces sitting in the readme directory.

mdoc tags

mdoc accomplishes all of this by parsing your input files for mdoc tags. These tags look like:

1. {mdoc include file.ext}, to include the file file.ext
2. {mdoc snippet eq1 from file.ext}, to include the snippet called eq1 from the file file.ext
3. {mdoc var1}, to insert the variable called var1
4. {mdoc eval expression}, to evaluate the Python expression expression

You might be wondering how, if this readme is generated using mdoc, I was able to type {mdoc ...} above without it being parsed. This is thanks to the static option, which prevents included files from being parsed and includes them verbatim:

1. {mdoc include file.ext static} includes file.ext but does not parse it for mdoc tags
2. {mdoc include snippet eq1 from file.ext static} includes snippet eq1 from file.ext but does not parse it for mdoc tags

There is no static option for variables or evals, since that wouldn't make any sense.

Snippets are defined as follows:

# Inside file.ext
{mdoc snip snippet_name}
...
snippet contents
...
{mdoc unsnip snippet_name}

You can then reference the snippet name and the file it lives in to include it in another document:

# Inside main file
{mdoc snippet snippet_name from file.ext}

This is very handy for including snippets of code that may change over time, as well as other fluctuating content.

Of course, the words include, snippet, snip, unsnip and eval are reserved and cannot be used as mdoc variables names.

usage

Using mdoc is simple, once you've installed it. Simply navigate into the folder where your main document template lives and run:

mdoc --input INPUT_DOCUMENT --output OUTPUT_DOCUMENT --variables VARIABLES_JSON

This will parse INPUT_DOCUMENT, insert any variables defined in VARIABLES_JSON, and spit out OUTPUT_DOCUMENT.

If you do not wish to generate an output file and simply want to see what the output would look like, you can replace the --output OUTPUT_DOCUMENT with --dryrun.

If you've lost track of all the variables needed throughout your documents, you can use --showvariables rather than --output or --dryrun and it will spit out a JSON-formatted list of all the variables you need. You can pipe this into a file to make things really easy!

mdoc --input INPUT_DOCUMENT --showvariables > VARIABLES_JSON