16.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 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. Another method is to surround the argument with ‘@asis{…}’. For texi2any, 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, two rules for automatic quoting are implemented:

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, there is no control on 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.

The backslash itself can be quoted in macro arguments with another backslash. For example:

@macname {\\bleh}

will pass the argument ‘\bleh’ to macname.

texi2any also recognizes ‘\{’ and ‘\}’ sequences for curly braces, but these are not recognized by the implementation in TeX. There should, however, rarely be a need for these, as they are only needed when a macro argument contains unbalanced braces.

If a macro is defined to take exactly one argument, it can be invoked without any braces, taking all of the line after the macro name as the argument. For example:

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

produces:

Twice: aah & aah.

In these arguments, there is no escaping of special characters, so each ‘\’ stands for itself.

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.