178 lines
5.0 KiB
Plaintext
178 lines
5.0 KiB
Plaintext
@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
|
|
|
|
|