Important

New in v5.3.0 Macros have been superseded by Procedures, Functions and Custom Widgets which together provide more robust and flexible ways to encapsulate and re-use code.

For text substitutions it is now recommended to use: Substituted Attribute Values, substitute Operator and Transclusion and Substitution

Introduction

A macro is a named snippet of text. They are typically defined with the Pragma: \define:

\define my-macro(parameter:"Default value")
This is the macro, and the parameter is $parameter$.
\end

The name wrapped in double angled brackets is used a shorthand way of transcluding the snippet. Such transclusions are known as macro calls, and each call can supply a different set of parameters:

<<my-macro>>
<<my-macro "The parameter">>

The parameters that are specified in the macro call are substituted for special placeholders within the snippet:

• $parameter-name$ is replaced with the value of the named parameter
• $(variable-name)$ is replaced with the value of the named variable).

How Macros Work

Macros are implemented as a special kind of variable. The only thing that distinguishes them from ordinary variables is the way that the parameters are handled.

Using Macros

• Macro Definitions describes how to create macros
• Macro Calls describes how to use macros
• Macro Parameter Handling describes how macro parameters work
• Macro Pitfalls describes some of the pitfalls of using macros
• Core Macros lists the built-in core macros