manpagez: man pages & more
info texinfo
Home | html | info | man
[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [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.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

This document was generated on October 2, 2013 using texi2html 5.0.

© manpagez.com 2000-2024
Individual documents may contain additional copyright information.