Install and Run Mau

"I’ll install a two-way bug so Pris, you can hear us and we can hear you, and I’ll rig up an alarm system that any of the four of us can set off. It’s obvious that the synthetic identities didn’t work out, even Garland’s."

Philip K. Dick, Do Androids Dream of Electric Sheep? (1968)

This chapter details how to install Mau both as a stand-alone tool and as a plugin for Pelican. The only requirements are a working Python3 installation and a virtual environment.

While Python comes preinstalled in several operating systems these days, you can find detailed instructions on how to install it on the Python official website. Virtual environments are covered in the official documentation, but you might want to also explore tools to manage them, like pyenv. However, these are not mandatory to run Mau.

Install Mau as a stand-alone tool

Mau is available on PyPI and to install it you just need to run

pip install mau

At this point you should have the command line tool mau available. You can test it with

mau --version

You can get help directly on the command line running

mau --help

The option -f is used to specify the output format, and the only output available out of the box is yaml, which prints out the Abstract Syntax Tree using YAML. To render Mau source code you need a visitor plugin.

At the moment there are two plugins available: the HTML visitor and the TeX visitor. You can install only one of them or both.

pip install mau-html-visitor
pip install mau-tex-visitor

Now, if you run mau --help you will see the new output format available to the option -f.

Run Mau as a stand-alone tool

The simplest command line for Mau is

mau -f FORMAT -i INPUT

that reads the Mau source file INPUT and converts it into the desired format saving the output in a file called INPUT.EXT, where EXT is a suitable extension that depends on the chosen format. If the input file has the extension .mau that will be automatically removed.

If you want to specify the output format and the name of the output file you can use the two options -f and -o

mau -f FORMAT -i INPUT -o OUTPUT

where FORMAT is one of the output formats that Mau supports, and both INPUT and OUTPUT are full paths, extensions included.

Example

Make sure you installed the HTML visitor and create the file test.mau in the current directory with this content

= A test

This is a test for the Mau markup processor.

Now you can run

mau -f html -i test.mau -o test.html

That will parse the content of test.mau and render it as HTML into test.html. The content of that file is

<html>
  <head>
  </head>
  <body>
    <h1 id="a-test-aae2">A test</h1>
    <p>This is a test for the Mau markup processor.</p>
  </body>
</html>

(minus the formatting which was added here for clarity)

You can now open the output file with your browser

firefox test.html

and enjoy your first document created with Mau.

Configuration file

Mau supports a configuration file written in YAML that can be loaded with the option -c

mau -c config.yml -f html -i test.mau -o test.html

Each value defined in the config file is stored as a variable and can be used in the Mau source. A complete description of the configuration file can be found in Configuration. You can learn more about variables in Mau documents in Basic syntax.

Using Mau programmatically

You can use Mau programmatically in your Python code. See Python interface to know more about the API.

That chapter also details how to use Mau to write posts and pages in Pelican through a specific plugin.