Macros

Text macros

Paragraphs of text can contain macros, which implement special commands. The list of available macros is:

  • class
  • control
  • footnote
  • header
  • image
  • link
  • mailto
  • raw
  • unicode

The macros control, header and footnote will be discussed later in the sections relative to those concepts.

Macro syntax

Macros come always in the form [name](arguments) where name is one of the names listed above, and arguments is a comma-separated list of unnamed and named arguments, for example (unnamed1, unnamed2, name1=value1, name2=value2).

Order of arguments

All unnamed arguments must be specified before named arguments. For example, the following syntax is invalid: (unnamed1, name1=value1, name2=value2, unnamed2).

The amount of spaces between commas is irrelevant, and can be zero. The following versions of macro arguments are all valid

  • (unnamed1,name1=value1)
  • (unnamed1, name1=value1)
  • (unnamed1, name1 = value1)
  • (unnamed1, name1 = value1)

Quoted arguments

Arguments can always be quoted to make the source code easier to read. They however must be quoted when they contains ambiguous characters like a space, a comma, a closing round bracket. The following versions of macro arguments are all valid

  • (argument1, argument2)
  • ("argument1", argument2)
  • ("argument with a space", argument2)
  • ("argument, with a comma", argument2)
  • ("argument, with a bracket)", argument2)

while the following are not, because the missing quotes make the syntax ambiguous

  • (argument, with a comma, argument2)
  • (argument, with a bracket), argument2)

Macro class

The macro class attaches the given classes to a piece of text, if those are supported by the output format. In HTML, those become part of the tag attribute class and can be targeted by CSS.

Mau source code
Some [class]("text with classes", class1, class2).

Some text with classes.

<p>Some <span class="class1 class2">text with classes</span>.</p>

Macro control

The macro control is used to render text conditionally. The macro will be introduced in a later chapter.

Macro footnote

The macro footnote is used to create an internal link to a footnote. The macro will be introduced in a later chapter.

Macro header

The macro header is used to create an internal link to a document header. The macro will be introduced in a later section.

Macro image

The macro image embeds an image file in a paragraph.

Mau source code
An embedded image [image]("https://placehold.co/40")

An embedded image 

<p>An embedded image <span class="image"><img src="https://placehold.co/40"></span></p>

The macro link creates a hyperlink.

Mau source code
A link with text: [link](www.wikipedia.org, "the free encyclopedia").

A link with text: the free encyclopedia.

<p>A link with text: <a href="www.wikipedia.org">the free encyclopedia</a>.</p>

Automatic link text

If no text is added to the macro, the text of the link will be the link itself.

Mau source code
Both paragraphs have the same output.

This is a link: [link](https://www.wikipedia.org).

This is a link: [link](https://www.wikipedia.org, https://www.wikipedia.org).

Both paragraphs have the same output.

This is a link: https://www.wikipedia.org.

This is a link: https://www.wikipedia.org.

<p>Both paragraphs have the same output.</p>

<p>This is a link: <a href="https://www.wikipedia.org">https://www.wikipedia.org</a>.</p>

<p>This is a link: <a href="https://www.wikipedia.org">https://www.wikipedia.org</a>.</p>

Macro mailto

The macro mailto works like the macro link but creates a mailto: connection.

Mau source code
Send an email to [mailto](info@project-mau.org).

Send an email to [mailto](info@project-mau.org, "this address").

Send an email to info@project-mau.org.

Send an email to this address.

<p>Send an email to <a href="mailto:info@project-mau.org">info@project-mau.org</a>.</p>

<p>Send an email to <a href="mailto:info@project-mau.org">this address</a>.</p>

Macro raw

Sometimes we need to include text in a paragraph verbatim but do not want to style it as code. The text can be either escaped with the techniques shown before (in particular using $$ and $$), or inserted with the macro raw.

Mau source code
This is Mau syntax: [raw]("$escaped$")

This is an HTML tag: [raw]("<span>some text</span>")

For comparison, this is the HTML tag in verbatim: `<span>some text</span>`

This is Mau syntax: $escaped$

This is an HTML tag: some text

For comparison, this is the HTML tag in verbatim: <span>some text</span>

<p>This is Mau syntax: $escaped$</p>

<p>This is an HTML tag: <span>some text</span></p>

<p>For comparison, this is the HTML tag in verbatim: <code>&lt;span&gt;some text&lt;/span&gt;</code></p>

Macro unicode

The macro unicode is used to add a Unicode data point to a piece of text. This is useful if you have the data points and do not want to copy and paste the Unicode characters directly into the text.

Mau source code
Volcano: [unicode](1F30B)

Volcano: 🌋

<p>Volcano: 🌋</p>