texinfo: Invoking Macros

Defining New Texinfo Commands

Macro Details

Defining Macros

Back to Software Index

19.2 Invoking Macros
====================

After a macro is defined (see the previous section), you can "invoke"
(use) it in your document like this:

     @MACRONAME {ARG1, ARG2, ...}

and the result will be more or less as if you typed the body of
MACRONAME at that spot.  For example:

     @macro foo {p, q}
     Together: \p\ & \q\.
     @end macro
     @foo{a, b}

produces:

     Together: a & b.

  Thus, the arguments and parameters are separated by commas and
delimited by braces; any whitespace after (but not before) a comma is
ignored.  The braces are required in the invocation even when the macro
takes no arguments, consistent with other Texinfo commands.  For
example:

     @macro argless {}
     No arguments here.
     @end macro
     @argless{}

produces:

     No arguments here.

  Passing macro arguments containing commas requires special care, since
commas also separate the arguments.  To include a comma character in an
argument, the most reliable method is to use the '@comma{}' command.
For 'makeinfo', you can also prepend a backslash character, as in '\,',
but this does not work with TeX.

  It's not always necessary to worry about commas.  To facilitate use of
macros, 'makeinfo' implements two rules for "automatic quoting" in some
circumstances:

  1. If a macro takes only one argument, all commas in its invocation
     are quoted by default.  For example:

          @macro TRYME{text}
          @strong{TRYME: \text\}
          @end macro

          @TRYME{A nice feature, though it can be dangerous.}

     will produce the following output

          *TRYME: A nice feature, though it can be dangerous.*

     And indeed, it can.  Namely, 'makeinfo' does not control the number
     of arguments passed to one-argument macros, so be careful when you
     invoke them.

  2. If a macro invocation includes another command (including a
     recursive invocation of itself), any commas in the nested command
     invocation(s) are quoted by default.  For example, in

          @say{@strong{Yes, I do}, person one}

     the comma after 'Yes' is implicitly quoted.  Here's another
     example, with a recursive macro:

          @rmacro cat{a,b}
          \a\\b\
          @end rmacro

          @cat{@cat{foo, bar}, baz}

     will produce the string 'foobarbaz'.

  3. Otherwise, a comma should be explicitly quoted, as above, for it to
     be treated as a part of an argument.

  In addition to the comma, characters that need to be quoted in macro
arguments are curly braces and backslash.  For example:

     @MACNAME {\\\{\}\,}

will pass the (almost certainly error-producing) argument '\{},' to
MACNAME.

  Unfortunately, this has not been reliably implemented in TeX.  When
macros are used in the argument to other commands, for example, errors
or incorrect output (the '\' "escape" being included literally) are
likely to result.

  If a macro is defined to take exactly one argument, it can (but need
not) be invoked without any braces; then the entire rest of the line
after the macro name is used as the argument.  (Braces around the
argument(s) are required in all other cases, i.e., if the macro takes
either zero or more than one argument.)  For example:

     @macro bar {p}
     Twice: \p\ & \p\.
     @end macro
     @bar aah

produces:

     Twice: aah & aah.

  Likewise, if a macro is defined to take exactly one argument, and is
invoked with braces, the braced text is passed as the argument, also
regardless of commas.  For example:

     @macro bar {p}
     Twice: \p\ & \p\.
     @end macro
     @bar{a,b}

produces:

     Twice: a,b & a,b.

  If a macro is defined to take more than one argument, but is called
with only one (in braces), the remaining arguments are set to the empty
string, and no error is given.  For example:

     @macro addtwo {p, q}
     Both: \p\\q\.
     @end macro
     @addtwo{a}

produces simply:

     Both: a.