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