An overview of Mau

How Mau processes documents

Mau documents go through three major processing steps: lexing, parsing, and rendering.

         lexer             parser            visitor
Source ---------> Tokens ----------> Nodes -----------> Rendered text

Lexing is the simplest of such steps and nothing much happens other than a simple split of the source file into tokens.

Parsing is the core of the Mau language, where the tokens are converted into nodes of an Abstract Syntax Tree. Such nodes capture the information about part of the document (such as a paragraph, a title, an image) and contain children nodes. This way, Mau captures the structure and the content of the document.

Visiting is the final step in which the nodes of the AST are converted into a destination format.

Nodes

Roughly speaking, Mau scans the document and identifies document nodes. These are nodes that exist on one or more contiguous lines, and are separated by one or more empty lines. For example

= A title <---------- HEADER (a single line)

* Element 1 <-------- LIST (3 consecutive lines)
* Element 2
* Element 3

This is some text <-- PARAGRAPH (3 consecutive lines)
split on multiple     
contiguous lines.

This is another <---- PARAGRAPH (2 consecutive lines)
paragraph.

Mau parses each of these nodes, checking their syntax and creating child nodes to build the AST. For example

= A title
^  ^
|  +------------------ Text "A title"
+--------------------- Level 1

This is a paragraph with *styles* and macros [class]("applied to text", "highlight").
                         ^                      ^
                         +-- Style 'star'       +-- Macro 'class'
                             |                      |
                             +-- Text "styles"      +-- Text "applied to text"
                                                    +-- Classes ["highlight"]

The nodes used to represent text, as found for example inside headers, lists, paragraphs, as text nodes.

Document nodes

The list of document nodes that Mau accepts is:

• Arguments
• Blocks
• Commands
• Controls
• Headers
• Horizontal rules
• Includes
• Labels
• Lists
• Paragraphs
• Variables

Text nodes

Inside paragraphs, lists, and other document nodes, it is possible to create text nodes. The list of text nodes supported by Mau is:

• Text
• Escaped text
• Styled text
• Verbatim text
• Macros
• Class
• Control
• Footnote
• Header
• Image
• Link
• Mailto
• Raw
• Unicode

The manual

The next chapter of the manual will introduce text and document nodes starting from the simplest syntax and building up to the more complex nodes. This will help to learn Mau in a gentle and rational way.

To make the most out of these chapters, we recommend having a text editor and a terminal handy, where you can experiment writing and processing Mau code.

In the manual, you will be shown an example of the Mau source and (as much as possible) a rendering of that syntax like you see below

Some Mau source

Should you want to jump to the explanation of a specific node, at the end of the book you will find a comprehensive reference of all node types with their syntax, supported options, and template fields.

Set up a test environment

The best way to use this manual is to read it chapter by chapter, trying to run the code that is shown in the examples. In this section you will set up a minimal environment that produces visually pleasant output in your browser, so you won't be forced to read raw HTML in your editor (which, however, you can still do if you feel inclined).

Prerequisites

Make sure you have installed Mau and the HTML visitor plugin as described in the previous chapter. In summary

pip install mau mau-html-visitor

Create the project directory

Create a fresh directory and the files described below

mkdir mau-playground && cd mau-playground
mkdir templates

The directory structure will be

mau-playground/
  templates/
    document.html
  config.yaml
  test.mau

The configuration file

Create the file config.yaml with the following content

visitor:
  html:
    pretty: true
  templates:
    paths:
      - templates

This tells Mau where to find template files and enables pretty-printed HTML output. We will introduce configuration values while we explore Mau's syntax and give a detailed overview of all possible configuration keys in one of the final chapters.

Please keep in mind that pretty printing HTML often introduces unwanted spaces in <code> and <pre> tags. It is turned on here mostly because for the first examples you might want to look at the HTML code yourself. Feel free to turn it off at any time with pretty: false or simply removing the whole key html.

The document template

Create the file templates/document.html with the following content

<html>
  <head>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/water.css@2/out/water.css">
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/richleland/pygments-css@master/monokai.css">
  </head>
  <body>{{ content }}</body>
</html>

This is a Jinja template. The syntax {{ content }} injects the content of the document. The two CSS links pull in Water.css for beautiful default typography and a Pygments theme for source code highlighting. Templates will be discussed in great detail in a later chapter.

Your first document

Create the file test.mau

= Hello Mau

This is an example written in *Mau*.

Compile and view

To render any source file you create in this directory, run

mau -c config.yaml -i SOURCE_FILE -t mau_html_visitor:HtmlVisitor -o OUTPUT_FILE

So, for our test file the command is

mau -c config.yaml -i test.mau -t mau_html_visitor:HtmlVisitor -o test.html

Open test.html with your browser and you should see a nicely formatted page with a header and a paragraph.