| @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 |
| |
| |