texinfo/doc/macro.texi

@c This file is included in makeinfo.texi.
@c
@ifinfo
@comment Here are some useful examples of the macro facility.

@c Simply insert the right version of the texinfo name.
@macro texinfo{}
TeXinfo
@end macro

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

@c Define a macro which expands to a pretty version of the name of the
@c Makeinfo program.
@macro makeinfo{}
@code{Makeinfo}
@end macro

@c Define a macro which is used to define other macros.  This one makes
@c a macro which creates a node and gives it a sectioning command.  Note
@c that the created macro uses the original definition within the
@c expansion text.  This takes advantage of the non-recursion feature of
@c macro execution.
@macro node_define{orig-name}
@macro \orig-name\{title}
@node \title\
@\orig-name\ \title\
@end macro
@end macro

@c Now actually define a new set of sectioning commands.
@node_define {chapter}
@node_define {section}
@node_define {subsection}
@end ifinfo

@chapter The Macro Facility

This chapter describes the new macro facility.

A @dfn{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.

@menu
* How to Use Macros in @texinfo{}::
                        How to use the macro facility.

* Using Macros Recursively::
                        How to write a macro which does (or doesn't) recurse.

* Using @texinfo{} Macros As Arguments::
                        Passing a macro as an argument.
@end menu

@section 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:

@example
@@macro @var{name}@{@var{arg1}, @var{@dots{}} @var{argn}@}
@var{@texinfo{} commands@dots{}}
@@end macro
@end example

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
@code{@@codeitem}, a macro which can be used wherever @code{@@item} can
be used, but which surrounds its argument with @code{@@code@{@dots{}@}}.

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

When the macro is expanded, all of the text between the @code{@@macro}
and @code{@@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:

@example
@@codeitem@{Foo@}
@end example

and @makeinfo{} would execute the following code:

@example
@@item @@code@{Foo@}
@end example

A special case is made for macros which only take a single argument, and
which are invoked without any brace characters (i.e.,
@samp{@{}@dots{}@samp{@}}) 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:

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

Thus, the text:

@example
@@chapter strlen
@end example

will expand to:

@example
@@chapter strlen
@@findex strlen
@end example

@section 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
@code{@@dfn@{@dots{}@}}, the location of the definition would appear
in the concept index for the manual.  Here is a macro which redefines
@code{@@dfn} to do just that:

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

Note that we used the builtin @texinfo{} command @code{@@dfn} within our
overriding macro definition.

This behaviour itself can be overridden for macro execution by writing a
special @dfn{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 @code{@@allow-recursion}.

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

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

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

@section Using @texinfo{} Macros As Arguments

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

@bye