1 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.

1.1 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

1.2 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''.

1.3 Using @texinfo{} Macros As Arguments

How to use @texinfo{} macros as arguments to other @texinfo{} macros.

About This Document

This document was generated on January 15, 2023 using texi2html 5.0.

The buttons in the navigation panels have the following meaning:

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

• 1. Section One
  • 1.1 Subsection One-One
    • ...
  • 1.2 Subsection One-Two
    • 1.2.1 Subsubsection One-Two-One
    • 1.2.2 Subsubsection One-Two-Two
    • 1.2.3 Subsubsection One-Two-Three     <== Current Position
    • 1.2.4 Subsubsection One-Two-Four
  • 1.3 Subsection One-Three
    • ...
  • 1.4 Subsection One-Four

This document was generated on January 15, 2023 using texi2html 5.0.