_define chapter _define section _define subsection

The Macro Facility
******************

This chapter describes the new macro facility.

A macro is a command that you define in terms of other commands. It doesn't exist as a TeXinfo command until you define it as part of the input file to Makeinfo.  Once the command exists, it behaves much as any other TeXinfo command.  Macros are a useful way to ease the details and tedium of writing a `correct' info file.  The following sections explain how to write and invoke macros.

How to Use Macros in TeXinfo
============================

Using macros in TeXinfo is easy.  First you define the macro.  After that, the macro command is available as a normal TeXinfo command. Here is what a definition looks like:

     @macro NAME{ARG1, ... ARGN}
     TEXINFO COMMANDS...
     @end macro

The arguments that you specify that the macro takes are expanded with the actual parameters used when calling the macro if they are seen surrounded by backslashes.  For example, here is a definition of @codeitem, a macro which can be used wherever @item can be used, but which surrounds its argument with @code{...}.

     @macro codeitem{item}
     @item @code{\item\}
     @end macro

When the macro is expanded, all of the text between the @macro and @end macro is inserted into the document at the expansion point, with the actual parameters substituted for the named parameters. So, a call to the above macro might look like:

     @codeitem{Foo}

and Makeinfo would execute the following code:

     @item @code{Foo}

A special case is made for macros which only take a single argument, and which are invoked without any brace characters (i.e., {...}) surrounding an argument; the rest of the line is supplied as is as the sole argument to the macro.  This special case allows one to redefine some standard TeXinfo commands without modifying the input file.  Along with the non-recursive action of macro invocation, one can easily redefine the sectioning commands to also provide index entries:

     @macro chapter{name}
     @chapter \name\
     @findex \name\
     @end macro

Thus, the text:

     @chapter strlen

will expand to:

     @chapter strlen
     @findex strlen

Using Macros Recursively
========================

Normally, while a particular macro is executing, any call to that macro will be seen as a call to a builtin TeXinfo command.  This allows one to redefine a builtin TeXinfo command as a macro, and then use that command within the definition of the macro itself.  For example, one might wish to make sure that whereever a term was defined with @dfn{...}, the location of the definition would appear in the concept index for the manual.  Here is a macro which redefines @dfn to do just that:

     @macro dfn{text}
     @dfn{\text\}
     @cpindex \text\
     @end macro

Note that we used the builtin TeXinfo command @dfn within our overriding macro definition.

This behaviour itself can be overridden for macro execution by writing a special macro control command in the definition of the macro.  The command is considered special because it doesn't affect the output text directly, rather, it affects the way in which the macro is defined.  One such special command is @allow-recursion.

     @macro silly{arg}
     @allow-recursion
     \arg\
     @end macro

Now @silly is a macro that can be used within a call to itself:

     This text @silly{@silly{some text}} is ``some text''.

How to use TeXinfo macros as arguments to other TeXinfo macros.