1 files changed, 177 insertions, 0 deletions
diff --git a/texinfo/makeinfo/macro.texi b/texinfo/makeinfo/macro.texi
new file mode 100644
index 00000000000..8a3fe802392
--- /dev/null
+++ b/texinfo/makeinfo/macro.texi
@@ -0,0 +1,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
+
+