1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
@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
|
