texinfo/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