Macros

Some tags tend to be long if used with lots of options. But that's no problem as macros are there to define shortcuts for them - or anything else you don't want to write again and again.

A macro is defined in a special paragraph beginning with a +:

    +TEXT:A simple text.

After that definition, you can use it like a tag:

    \TEXT

.. and it will be replaced by the contents that was defined for it.

Of course such context can be more complicated. Here is an example that colorizes red:

    +RED:\F{color=red}<__body__>

and can be used this way:

    \RED<Red text!>

To make this work, the macro needs to know where to insert its body ( Red text!) when translating into the defined text. This is done by the __body__ placeholder, so that our example is equivalent to

    \F{color=red}<Red text!>

- but shorter ;-)

The right side of a macro definition can contain anything that is valid within a paragraph, including other macros. So, with the definition

    +REDTEXT:\RED<\TEXT>

the text

    \REDTEXT

would be translated into

    \F{color=red}<A simple text.>

Here is an example of combined tags:

    +IBX:\I<\B<\X<__body__>>>

Macros can be used to perform very complex tasks as we will see in the advanced section. For now, in their simple form they offer an easy way to relieve a writer by defining shortcuts.

As a further example, you might want to abbreviate the very long \REF{name="..." type=linked}<...> tag. The dotted parts are variable, and we instantly see that this cannot be expressed with what we know now: we can inject the body part but do not know how to deal with the variable option.

Fortunately, the placeholder syntax is generic. Here is the definition of a shortcut for this case:

    +LREF:\REF{name="__n__" type=linked}<__body__>>

The __n__ is a placeholder for a macro option n and will be replaced by its value. So, we have defined a macro LREF with a body and an option n whitch takes the target name. We can use it like this:

    See \LREF{n="our anchor"}<there>.

With the definition above, this will be translated into

    See \REF{name="our anchor" type=linked}<there>.