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 section Inserting `,' with @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.