← Back to branch summary

~ubuntu-branches/ubuntu/maverick/texinfo/maverick

« back to all changes in this revision

Viewing changes to doc/macro.texi

  • Committer: Bazaar Package Importer
  • Author(s): Norbert Preining
  • Date: 2005-10-28 15:10:30 UTC
  • mto: (2.1.1 dapper) (3.1.4 hardy)
  • mto: This revision was merged to the branch mainline in revision 3.
  • Revision ID: james.westby@ubuntu.com-20051028151030-9nsf2s2k2z3fktjt
Tags: upstream-4.8
Import upstream version 4.8

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/macro.texi
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{}
8
 
TeXinfo
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
 
 
42
 
This chapter describes the new macro facility.
43
 
 
44
 
A @dfn{macro} is a command that you define in terms of other commands.
45
 
It doesn't exist as a @texinfo{} command until you define it as part of
46
 
the input file to @makeinfo{}.  Once the command exists, it behaves much
47
 
as any other @texinfo{} command.  Macros are a useful way to ease the
48
 
details and tedium of writing a `correct' info file.  The following
49
 
sections 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
 
 
64
 
Using macros in @texinfo{} is easy.  First you define the macro.  After
65
 
that, the macro command is available as a normal @texinfo{} command.
66
 
Here 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
 
 
74
 
The arguments that you specify that the macro takes are expanded with
75
 
the actual parameters used when calling the macro if they are seen
76
 
surrounded by backslashes.  For example, here is a definition of
77
 
@code{@@codeitem}, a macro which can be used wherever @code{@@item} can
78
 
be 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
 
 
86
 
When the macro is expanded, all of the text between the @code{@@macro}
87
 
and @code{@@end macro} is inserted into the document at the expansion
88
 
point, with the actual parameters substituted for the named parameters.
89
 
So, a call to the above macro might look like:
90
 
 
91
 
@example
92
 
@@codeitem@{Foo@}
93
 
@end example
94
 
 
95
 
and @makeinfo{} would execute the following code:
96
 
 
97
 
@example
98
 
@@item @@code@{Foo@}
99
 
@end example
100
 
 
101
 
A special case is made for macros which only take a single argument, and
102
 
which are invoked without any brace characters (i.e.,
103
 
@samp{@{}@dots{}@samp{@}}) surrounding an argument; the rest of the line
104
 
is supplied as is as the sole argument to the macro.  This special case
105
 
allows one to redefine some standard @texinfo{} commands without
106
 
modifying the input file.  Along with the non-recursive action of macro
107
 
invocation, one can easily redefine the sectioning commands to also
108
 
provide index entries:
109
 
 
110
 
@example
111
 
@@macro chapter@{name@}
112
 
@@chapter \name\
113
 
@@findex \name\
114
 
@@end macro
115
 
@end example
116
 
 
117
 
Thus, the text:
118
 
 
119
 
@example
120
 
@@chapter strlen
121
 
@end example
122
 
 
123
 
will expand to:
124
 
 
125
 
@example
126
 
@@chapter strlen
127
 
@@findex strlen
128
 
@end example
129
 
 
130
 
@section Using Macros Recursively
131
 
 
132
 
Normally, while a particular macro is executing, any call to that macro
133
 
will be seen as a call to a builtin @texinfo{} command.  This allows one
134
 
to redefine a builtin @texinfo{} command as a macro, and then use that
135
 
command within the definition of the macro itself.  For example, one
136
 
might wish to make sure that whereever a term was defined with
137
 
@code{@@dfn@{@dots{}@}}, the location of the definition would appear
138
 
in 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
 
 
148
 
Note that we used the builtin @texinfo{} command @code{@@dfn} within our
149
 
overriding macro definition.
150
 
 
151
 
This behaviour itself can be overridden for macro execution by writing a
152
 
special @dfn{macro control command} in the definition of the macro.  The
153
 
command is considered special because it doesn't affect the output text
154
 
directly, rather, it affects the way in which the macro is defined.  One
155
 
such 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
 
 
164
 
Now @code{@@silly} is a macro that can be used within a call to itself:
165
 
 
166
 
@example
167
 
This text @@silly@{@@silly@{some text@}@} is ``some text''.
168
 
@end example
169
 
 
170
 
@section Using @texinfo{} Macros As Arguments
171
 
 
172
 
@printindex cp
173
 
How to use @texinfo{} macros as arguments to other @texinfo{} macros.
174
 
 
175
 
@bye
176
 
 
177