1@c This file is included in makeinfo.texi.
2@c
3@ifinfo
4@comment Here are some useful examples of the macro facility.
5
6@c Simply insert the right version of the texinfo name.
7@macro texinfo{}
8TeXinfo
9@end macro
10
11@macro dfn{text}
12@dfn{\text\}
13@cpindex \text\
14@end macro
15
16@c Define a macro which expands to a pretty version of the name of the
17@c Makeinfo program.
18@macro makeinfo{}
19@code{Makeinfo}
20@end macro
21
22@c Define a macro which is used to define other macros.  This one makes
23@c a macro which creates a node and gives it a sectioning command.  Note
24@c that the created macro uses the original definition within the
25@c expansion text.  This takes advantage of the non-recursion feature of
26@c macro execution.
27@macro node_define{orig-name}
28@macro \orig-name\{title}
29@node \title\
30@\orig-name\ \title\
31@end macro
32@end macro
33
34@c Now actually define a new set of sectioning commands.
35@node_define {chapter}
36@node_define {section}
37@node_define {subsection}
38@end ifinfo
39
40@chapter The Macro Facility
41
42This chapter describes the new macro facility.
43
44A @dfn{macro} is a command that you define in terms of other commands.
45It doesn't exist as a @texinfo{} command until you define it as part of
46the input file to @makeinfo{}.  Once the command exists, it behaves much
47as any other @texinfo{} command.  Macros are a useful way to ease the
48details and tedium of writing a `correct' info file.  The following
49sections explain how to write and invoke macros.
50
51@menu
52* How to Use Macros in @texinfo{}::
53                        How to use the macro facility.
54
55* Using Macros Recursively::
56                        How to write a macro which does (or doesn't) recurse.
57
58* Using @texinfo{} Macros As Arguments::
59                        Passing a macro as an argument.
60@end menu
61
62@section How to Use Macros in @texinfo{}
63
64Using macros in @texinfo{} is easy.  First you define the macro.  After
65that, the macro command is available as a normal @texinfo{} command.
66Here is what a definition looks like:
67
68@example
69@@macro @var{name}@{@var{arg1}, @var{@dots{}} @var{argn}@}
70@var{@texinfo{} commands@dots{}}
71@@end macro
72@end example
73
74The arguments that you specify that the macro takes are expanded with
75the actual parameters used when calling the macro if they are seen
76surrounded by backslashes.  For example, here is a definition of
77@code{@@codeitem}, a macro which can be used wherever @code{@@item} can
78be used, but which surrounds its argument with @code{@@code@{@dots{}@}}.
79
80@example
81@@macro codeitem@{item@}
82@@item @@code@{\item\@}
83@@end macro
84@end example
85
86When the macro is expanded, all of the text between the @code{@@macro}
87and @code{@@end macro} is inserted into the document at the expansion
88point, with the actual parameters substituted for the named parameters.
89So, a call to the above macro might look like:
90
91@example
92@@codeitem@{Foo@}
93@end example
94
95and @makeinfo{} would execute the following code:
96
97@example
98@@item @@code@{Foo@}
99@end example
100
101A special case is made for macros which only take a single argument, and
102which are invoked without any brace characters (i.e.,
103@samp{@{}@dots{}@samp{@}}) surrounding an argument; the rest of the line
104is supplied as is as the sole argument to the macro.  This special case
105allows one to redefine some standard @texinfo{} commands without
106modifying the input file.  Along with the non-recursive action of macro
107invocation, one can easily redefine the sectioning commands to also
108provide index entries:
109
110@example
111@@macro chapter@{name@}
112@@chapter \name\
113@@findex \name\
114@@end macro
115@end example
116
117Thus, the text:
118
119@example
120@@chapter strlen
121@end example
122
123will expand to:
124
125@example
126@@chapter strlen
127@@findex strlen
128@end example
129
130@section Using Macros Recursively
131
132Normally, while a particular macro is executing, any call to that macro
133will be seen as a call to a builtin @texinfo{} command.  This allows one
134to redefine a builtin @texinfo{} command as a macro, and then use that
135command within the definition of the macro itself.  For example, one
136might wish to make sure that whereever a term was defined with
137@code{@@dfn@{@dots{}@}}, the location of the definition would appear
138in the concept index for the manual.  Here is a macro which redefines
139@code{@@dfn} to do just that:
140
141@example
142@@macro dfn@{text@}
143@@dfn@{\text\@}
144@@cpindex \text\
145@@end macro
146@end example
147
148Note that we used the builtin @texinfo{} command @code{@@dfn} within our
149overriding macro definition.
150
151This behaviour itself can be overridden for macro execution by writing a
152special @dfn{macro control command} in the definition of the macro.  The
153command is considered special because it doesn't affect the output text
154directly, rather, it affects the way in which the macro is defined.  One
155such special command is @code{@@allow-recursion}.
156
157@example
158@@macro silly@{arg@}
159@@allow-recursion
160\arg\
161@@end macro
162@end example
163
164Now @code{@@silly} is a macro that can be used within a call to itself:
165
166@example
167This text @@silly@{@@silly@{some text@}@} is ``some text''.
168@end example
169
170@section Using @texinfo{} Macros As Arguments
171
172@printindex cp
173How to use @texinfo{} macros as arguments to other @texinfo{} macros.
174
175@bye
176
177
178