Go to the first, previous, next, last section, table of contents.


Macros: Defining New Texinfo Commands

A Texinfo macro allows you to define a new Texinfo command as any sequence of text and/or existing commands (including other macros). The macro can have any number of parameters---text you supply each time you use the macro. (This has nothing to do with the @defmac command, which is for documenting macros in the subject of the manual; see section The Template for a Definition.)

Defining Macros

You use the Texinfo @macro command to define a macro. For example:

@macro macro-name{param1, param2, ...}
text ... \param1\ ...
@end macro

The parameters param1, param2, ... correspond to arguments supplied when the macro is subsequently used in the document (see the next section).

If a macro needs no parameters, you can define it either with an empty list (`@macro foo {}') or with no braces at all (`@macro foo').

The definition or body of the macro can contain any Texinfo commands, including previously-defined macros. (It is not possible to have mutually recursive Texinfo macros.) In the body, instances of a parameter name surrounded by backslashes, as in `\param1\' in the example above, are replaced by the corresponding argument from the macro invocation.

You can undefine a macro foo with @unmacro foo. It is not an error to undefine a macro that is already undefined. For example:

@unmacro foo

Invoking Macros

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

@macro-name {arg1, arg2, ...}

and the result will be just as if you typed the body of macro-name 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. To insert a comma, brace, or backslash in an argument, prepend a backslash, as in

@macro-name {\\\{\}\,}

which will pass the (almost certainly error-producing) argument `\{},' to macro-name.

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.


Go to the first, previous, next, last section, table of contents.