texinfo: Defining Macros

Defining New Texinfo Commands

Invoking Macros

Back to Software Index

19.1 Defining Macros
====================

You use the Texinfo '@macro' command to define a macro, like this:

     @macro MACRONAME{PARAM1, PARAM2, ...}
     TEXT ... \PARAM1\ ...
     @end macro

  The "parameters" PARAM1, PARAM2, ... correspond to arguments supplied
when the macro is subsequently used in the document (described in the
next section).

  For a macro to work consistently with TeX, MACRONAME must consist
entirely of letters: no digits, hyphens, underscores, or other special
characters.  So, we recommend using only letters.  However, 'makeinfo'
will accept anything consisting of alphanumerics, and (except as the
first character) '-'.  The '_' character is excluded so that macros can
be called inside '@math' without a following space (Note: Inserting
Math).

  If a macro needs no parameters, you can define it either with an empty
list ('@macro foo {}') or with no braces at all ('@macro foo').

  The definition or "body" of the macro can contain most Texinfo
commands, including macro invocations.  However, a macro definition that
defines another macro does not work in TeX due to limitations in the
design of '@macro'.

  In the macro body, instances of a parameter name surrounded by
backslashes, as in '\PARAM1\' in the example above, are replaced by the
corresponding argument from the macro invocation.  You can use parameter
names any number of times in the body, including zero.

  To get a single '\' in the macro expansion, use '\\'.  Any other use
of '\' in the body yields a warning.

  The newline characters after the '@macro' line and before the '@end
macro' line are ignored, that is, not included in the macro body.  All
other whitespace is treated according to the usual Texinfo rules.
However, there are still undesirable and unpredictable interactions
between newlines, macros, and commands which are line-delimited, as
warned about below (Note: Macro Details).

  To allow a macro to be used recursively, that is, in an argument to a
call to itself, you must define it with '@rmacro', like this:

     @rmacro rmac {arg}
     a\arg\b
     @end rmacro
     ...
     @rmac{1@rmac{text}2}

  This produces the output 'a1atextb2b'.  With '@macro' instead of
'@rmacro', an error message is given.

  You can undefine a macro FOO with '@unmacro FOO'.  It is not an error
to undefine a macro that is already undefined.  For example:

     @unmacro foo