summaryrefslogtreecommitdiff
path: root/contrib/texinfo/makeinfo/macro.texi
diff options
context:
space:
mode:
Diffstat (limited to 'contrib/texinfo/makeinfo/macro.texi')
-rw-r--r--contrib/texinfo/makeinfo/macro.texi177
1 files changed, 0 insertions, 177 deletions
diff --git a/contrib/texinfo/makeinfo/macro.texi b/contrib/texinfo/makeinfo/macro.texi
deleted file mode 100644
index 8a3fe802392e..000000000000
--- a/contrib/texinfo/makeinfo/macro.texi
+++ /dev/null
@@ -1,177 +0,0 @@
-@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
-
-