19.2 Invoking Macros

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

     @macroname {arg1, arg2, ...}

and the result will be just 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 (but not the definition), even when the macro takes no arguments, consistent with all other Texinfo commands. For example:

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

produces:

     No arguments here.

Passing strings containing commas as macro arguments requires special care, since they should be properly quoted to prevent makeinfo from confusing them with argument separators. To manually quote a comma, prepend it with a backslash character, like this: \,. Alternatively, use the @comma command (see Inserting a Comma). However, to facilitate use of macros, makeinfo implements a set of rules called automatic quoting:

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

             @macro FIXME{text}
             @strong{FIXME: \text\}
             @end macro
             
             @FIXME{A nice feature, though it can be dangerous.}
   

   will produce the following output

             FIXME: A nice feature, though it can be dangerous.
   

   And indeed, it can. Namely, makeinfo does not control 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, to be treated as a part of an argument.

Other 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. However, commas in parameters, even if escaped by a backslash, might cause trouble in TeX.

If the macro is defined to take a single argument, and is invoked without any braces, the entire rest of the line after the macro name is supplied as the argument. For example:

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

produces:

     Twice: aah & aah.

If the macro is defined to take a single argument, and is invoked with braces, the braced text is passed as the argument, regardless of commas. For example:

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

produces:

     Twice: a,b & a,b.