With recent doc improvements, the index grew to be just large enough to tickle a current texinfo limitation, rather than cleanly splitting over two pages in a pdf or dvi manual:
http://www.nabble.com/overfull-%5Cvbox-in-%40printindex-tf3328666.html#a9255712 The solution was to add even more index entries (a rather useful task in and of itself), so that the index no longer runs off the bottom of a printed page. 2007-03-01 Eric Blake <[EMAIL PROTECTED]> Avoid overfull \vbox warning from texinfo, due to indices that weren't quite big enough to split across page boundaries. * doc/m4.texinfo: Add lots of concept index entries. (Concept Index): Move to be last, as recommended by texinfo manual. (Define, Arguments, Pseudo Arguments): Add more function entries. Index: doc/m4.texinfo =================================================================== RCS file: /sources/m4/m4/doc/m4.texinfo,v retrieving revision 1.1.1.1.2.118 diff -u -r1.1.1.1.2.118 m4.texinfo --- doc/m4.texinfo 28 Feb 2007 21:51:36 -0000 1.1.1.1.2.118 +++ doc/m4.texinfo 1 Mar 2007 21:37:57 -0000 @@ -275,8 +275,8 @@ Indices of concepts and macros -* Concept index:: Index for many concepts * Macro index:: Index for all @code{m4} macros +* Concept index:: Index for many concepts @end detailmenu @end menu @@ -302,6 +302,7 @@ @node Intro @section Introduction to @code{m4} [EMAIL PROTECTED] overview of @code{m4} @code{m4} is a macro processor, in the sense that it copies its input to the output, expanding macros as it goes. Macros are either builtin or user-defined, and can take any number of arguments. @@ -333,6 +334,8 @@ @node History @section Historical references [EMAIL PROTECTED] history of @code{m4} [EMAIL PROTECTED] @acronym{GNU} M4, history of @code{GPM} was an important ancestor of @code{m4}. See C. Stratchey: ``A General Purpose Macro generator'', Computer Journal 8,3 (1965), pp. 225 ff. @code{GPM} is also succinctly described into @@ -391,6 +394,9 @@ @node Bugs @section Problems and bugs [EMAIL PROTECTED] reporting bugs [EMAIL PROTECTED] bug reports [EMAIL PROTECTED] suggestions, reporting If you have problems with @acronym{GNU} M4 or think you've found a bug, please report it. Before reporting a bug, make sure you've actually found a real bug. Carefully reread the documentation and see if it @@ -417,6 +423,7 @@ @node Manual @section Using this manual [EMAIL PROTECTED] examples, understanding This manual contains a number of examples of @code{m4} input and output, and a simple notation is used to distinguish input, output and error messages from @code{m4}. Examples are set out from the normal text, and @@ -486,6 +493,8 @@ @node Invoking m4 @chapter Invoking @code{m4} [EMAIL PROTECTED] command line [EMAIL PROTECTED] invoking @code{m4} The format of the @code{m4} command is: @comment ignore @@ -552,6 +561,8 @@ @item -E @itemx --fatal-warnings [EMAIL PROTECTED] errors, fatal [EMAIL PROTECTED] fatal errors Controls the effect of warnings. If unspecified, then execution continues and exit status is unaffected when a warning is printed. If specified exactly once, warnings become fatal; when one is issued, @@ -610,6 +621,7 @@ @cindex macro definitions, on the command line @cindex command line, macro definitions on the [EMAIL PROTECTED] preprocessor features Several options allow @code{m4} to behave more like a preprocessor. Macro definitions and deletions can be made on the command line, the search path can be altered, and the output file can track where the @@ -633,6 +645,9 @@ @item -s @itemx --synclines [EMAIL PROTECTED] syncronization lines [EMAIL PROTECTED] location, input [EMAIL PROTECTED] input location Generate synchronization lines, for use by the C preprocessor or other similar tools. Order is significant with respect to file names. This option is useful, for example, when @code{m4} is used as a @@ -682,6 +697,8 @@ @item -L @var{NUM} @itemx [EMAIL PROTECTED] [EMAIL PROTECTED] nesting limit [EMAIL PROTECTED] limit, nesting Artificially limit the nesting of macro calls to @var{NUM} levels, stopping program execution if this limit is ever exceeded. When not specified, nesting is limited to 1024 levels. A value of zero means @@ -694,6 +711,7 @@ Most users would never need this option. If shown to be obtrusive, this option (which is still experimental) might well disappear. [EMAIL PROTECTED] rescanning This option does @emph{not} have the ability to break endless rescanning loops, since these do not necessarily consume much memory or stack space. Through clever usage of rescanning loops, one can @@ -844,6 +862,7 @@ @section Macro names @cindex names [EMAIL PROTECTED] words A name is any sequence of letters, digits, and the character @samp{_} (underscore), where the first character is not a digit. @code{m4} will use the longest such sequence found in the input. If a name has a @@ -856,6 +875,7 @@ @section Quoting input to @code{m4} @cindex quoted string [EMAIL PROTECTED] string, quoted A quoted string is a sequence of characters surrounded by quote strings, defaulting to @samp{`} and @samp{'}, where the nested begin and end quotes within the @@ -907,6 +927,7 @@ @node Other tokens @section Other kinds of input tokens [EMAIL PROTECTED] tokens, special Any character, that is neither a part of a name, nor of a quoted string, nor a comment, is a token by itself. When not in the context of macro expansion, all of these tokens are just copied to output. However, @@ -1114,6 +1135,7 @@ @section Macro invocation @cindex macro invocation [EMAIL PROTECTED] invoking macros Macro invocations has one of the forms @comment ignore @@ -1235,6 +1257,7 @@ the @code{divert} builtin macro will be called, which expands to the empty string. [EMAIL PROTECTED] rescanning The output of macro evaluations is always rescanned. The following example would yield the string @samp{de}, exactly as if @code{m4} has been given @[EMAIL PROTECTED](`abcde', `3', `2')}} as input: @@ -1316,6 +1339,8 @@ @result{} @end example [EMAIL PROTECTED] warnings, suppressing [EMAIL PROTECTED] suppressing warnings Normally @code{m4} will issue warnings if a builtin macro is called with an inappropriate number of arguments, but it can be suppressed with the @option{--quiet} command line option (or @option{--silent}, or @@ -1392,6 +1417,8 @@ foo(`() (() (') @end example [EMAIL PROTECTED] quoting rule of thumb [EMAIL PROTECTED] rule of thumb, quoting It is, however, in certain cases necessary (because nested expansion must occur to create the arguments for the outer macro) or convenient (because it uses fewer characters) to leave out quotes for some @@ -1526,7 +1553,15 @@ (@pxref{Indir}) and @code{defn} (@pxref{Defn}). @cindex arrays -Arrays and associative arrays can be simulated by using this trick. +Arrays and associative arrays can be simulated by using non-standard +macro names. + [EMAIL PROTECTED] Composite array (@var{index}) [EMAIL PROTECTED] Composite array_set (@var{index}, @ovar{value}) +Provide access to entries within an array. @code{array} reads the entry +at location @var{index}, and @code{array_set} assigns @var{value} to +location @var{index}. [EMAIL PROTECTED] deffn @example define(`array', `defn(format(``array[%d]'', `$1'))') @@ -1549,13 +1584,18 @@ @section Arguments to macros @cindex macros, arguments to [EMAIL PROTECTED] Arguments to macros [EMAIL PROTECTED] arguments to macros Macros can have arguments. The @var{n}th argument is denoted by @code{$n} in the expansion text, and is replaced by the @var{n}th actual argument, when the macro is expanded. Replacement of arguments happens before rescanning, regardless of how many nesting levels of quoting appear in the expansion. Here is an example of a macro with -two arguments. It simply exchanges the order of the two arguments. +two arguments. + [EMAIL PROTECTED] Composite exch (@var{arg1}, @var{arg2}) +Expands to @var{arg2} followed by @var{arg1}, effectively exchanging +their order. [EMAIL PROTECTED] deffn @example define(`exch', `$2, $1') @@ -1670,8 +1710,11 @@ and for all the actual arguments. The number of actual arguments in a macro call is denoted by @code{$#} -in the expansion text. Thus, a macro to display the number of arguments -given can be +in the expansion text. + [EMAIL PROTECTED] Composite nargs (@dots{}) +Expands to a count of the number of arguments supplied. [EMAIL PROTECTED] deffn @example define(`nargs', `$#') @@ -1779,6 +1822,9 @@ @result{}$$$ hello $$$ @end example [EMAIL PROTECTED] rescanning [EMAIL PROTECTED] literal output [EMAIL PROTECTED] output, literal If you want a macro to expand to something like @samp{$12}, the judicious use of nested quoting can put a safe character between the @code{$} and the next character, relying on the rescanning to remove the @@ -1861,6 +1907,8 @@ @cindex macros, how to rename @cindex renaming macros [EMAIL PROTECTED] macros, displaying definitions [EMAIL PROTECTED] definitions, displaying macro It is possible to rename an already defined macro. To do this, you need the builtin @code{defn}: @@ -1921,6 +1969,7 @@ @result{} @end example [EMAIL PROTECTED] rescanning However, it is important to remember that @code{m4} rescanning is purely textual. If an unbalanced end-quote string occurs in a macro definition, the rescan will see that embedded quote as the termination @@ -1943,6 +1992,8 @@ @result{}AA' @end example [EMAIL PROTECTED] builtins, special tokens [EMAIL PROTECTED] tokens, builtin macro Using @code{defn} to generate special tokens for builtin macros outside of expected contexts can sometimes trigger warnings. But most of the time, such tokens are silently converted to the empty string. @@ -1963,6 +2014,8 @@ @cindex macros, temporary redefinition of @cindex temporary redefinition of macros @cindex redefinition of macros, temporary [EMAIL PROTECTED] definition stack [EMAIL PROTECTED] stack, macro definition It is possible to redefine a macro temporarily, reverting to the previous definition at a later time. This is done with the builtins @code{pushdef} and @code{popdef}: @@ -2245,6 +2298,8 @@ @section If-else construct, or multibranch @cindex comparing strings [EMAIL PROTECTED] discarding input [EMAIL PROTECTED] input, discarding The other conditional, @code{ifelse}, is much more powerful. It can be used as a way to introduce a long comment, as an if-else construct, or as a multibranch, depending on the number of arguments supplied: @@ -2317,6 +2372,8 @@ @end example @cindex multibranches [EMAIL PROTECTED] switch statement [EMAIL PROTECTED] case statement However, @code{ifelse} can take more than four arguments. If given more than four arguments, @code{ifelse} works like a @code{case} or @code{switch} statement in traditional programming languages. If @var{string-1} and @@ -2710,6 +2767,8 @@ @node Debugging @chapter How to debug macros and input [EMAIL PROTECTED] debugging macros [EMAIL PROTECTED] macros, debugging When writing macros for @code{m4}, they often do not work as intended on the first try (as is the case with most programming languages). Fortunately, there is support for macro debugging in @code{m4}. @@ -3044,6 +3103,8 @@ @section Deleting whitespace in input @cindex deleting whitespace in input [EMAIL PROTECTED] discarding input [EMAIL PROTECTED] input, discarding The builtin @code{dnl} stands for ``Discard to Next Line'': @deffn Builtin dnl @@ -3100,8 +3161,9 @@ @node Changequote @section Changing the quote characters [EMAIL PROTECTED] changing the quote delimiters [EMAIL PROTECTED] quote delimiters, changing the [EMAIL PROTECTED] changing quote delimiters [EMAIL PROTECTED] quote delimiters, changing [EMAIL PROTECTED] delimiters, changing The default quote delimiters can be changed with the builtin @code{changequote}: @@ -3303,6 +3365,7 @@ @cindex changing comment delimiters @cindex comment delimiters, changing [EMAIL PROTECTED] delimiters, changing The default comment delimiters can be changed with the builtin macro @code{changecom}: @@ -3447,6 +3510,9 @@ @cindex lexical structure of words @cindex words, lexical structure of [EMAIL PROTECTED] syntax, changing [EMAIL PROTECTED] changing syntax [EMAIL PROTECTED] regular expressions @quotation The macro @code{changeword} and all associated functionality is experimental. It is only available if the @option{--enable-changeword} @@ -3667,6 +3733,8 @@ @cindex saving input @cindex input, saving [EMAIL PROTECTED] deferring expansion [EMAIL PROTECTED] expansion, deferring It is possible to `save' some text until the end of the normal input has been seen. Text can be saved, to be read again by @code{m4} when the normal input has been exhausted. This feature is normally used to @@ -3877,6 +3945,7 @@ @node Diversions @chapter Diverting and undiverting output [EMAIL PROTECTED] deferring output Diversions are a way of temporarily saving output. The output of @code{m4} can at any time be diverted to a temporary file, and be reinserted into the output stream, @dfn{undiverted}, again at a later @@ -4024,6 +4093,8 @@ @result{}Wrapped TEXT precedes diverted text. @end example [EMAIL PROTECTED] discarding input [EMAIL PROTECTED] input, discarding If output is diverted to a negative diversion, it is simply discarded. This can be used to suppress unwanted output. A common example of unwanted output is the trailing newlines after macro definitions. Here @@ -4082,6 +4153,8 @@ order given. If no arguments are supplied, all diversions are undiverted, in numerical order. [EMAIL PROTECTED] file inclusion [EMAIL PROTECTED] inclusion, of files As a @acronym{GNU} extension, @var{diversions} may contain non-numeric strings, which are treated as the names of files to copy into the output without expansion. A warning is issued if a file could not be opened. @@ -4287,6 +4360,7 @@ @node Index macro @section Searching for substrings [EMAIL PROTECTED] substrings, locating Searching for substrings is done with @code{index}: @deffn Builtin index (@var{string}, @var{substring}) @@ -4316,14 +4390,17 @@ @node Regexp @section Searching for regular expressions [EMAIL PROTECTED] basic regular expressions @cindex regular expressions [EMAIL PROTECTED] expressions, regular @cindex @acronym{GNU} extensions Searching for regular expressions is done with the builtin @code{regexp}: @deffn Builtin regexp (@var{string}, @var{regexp}, @ovar{replacement}) Searches for @var{regexp} in @var{string}. The syntax for regular -expressions is the same as in @acronym{GNU} Emacs. +expressions is the same as in @acronym{GNU} Emacs, which is similar to +Basic Regular Expressions (@sc{BRE}) in @acronym{POSIX}. @ifnothtml @xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs Manual}. @@ -4333,6 +4410,8 @@ @uref{http://www.gnu.org/@/software/@/emacs/@/manual/@/emacs.html#Regexps, Syntax of Regular Expressions} in the @acronym{GNU} Emacs Manual. @end ifhtml +Support for Extended Regular Expressions (@sc{ERE}) is not available, +but will be added in @acronym{GNU} M4 2.0. If @var{replacement} is omitted, @code{regexp} expands to the index of the first match of @var{regexp} in @var{string}. If @var{regexp} does @@ -4502,7 +4581,9 @@ @node Patsubst @section Substituting text by regular expression [EMAIL PROTECTED] basic regular expressions @cindex regular expressions [EMAIL PROTECTED] expressions, regular @cindex pattern substitution @cindex substitution by regular expression @cindex @acronym{GNU} extensions @@ -4973,10 +5054,7 @@ @node Shell commands @chapter Macros for running shell commands [EMAIL PROTECTED] executing UNIX commands [EMAIL PROTECTED] running UNIX commands @cindex UNIX commands, running [EMAIL PROTECTED] commands, running UNIX @cindex executing shell commands @cindex running shell commands @cindex shell commands, running @@ -5032,7 +5110,6 @@ @result{}Extensions are active @end example [EMAIL PROTECTED] platform macro On UNIX systems, @acronym{GNU} @code{m4} will define @[EMAIL PROTECTED] by default, or @code{unix} when the @option{-G} option is specified. @@ -5371,6 +5448,8 @@ @node Location @section Printing current location [EMAIL PROTECTED] location, input [EMAIL PROTECTED] input location To make it possible to specify the location of an error, three utility builtins exist: @@ -5785,7 +5864,7 @@ is modeled after the C library function @code{printf} (@pxref{Format}). @item -Searches and text substitution through regular expressions are +Searches and text substitution through basic regular expressions are supported by the @code{regexp} (@pxref{Regexp}) and @code{patsubst} (@pxref{Patsubst}) builtins. @@ -6035,7 +6114,6 @@ @acronym{GNU} @code{m4} makes no attempt at prohibiting self-referential definitions like: [EMAIL PROTECTED] ignore @example define(`x', `x') @result{} @@ -6043,8 +6121,10 @@ @result{} @end example [EMAIL PROTECTED] rescanning There is nothing inherently wrong with defining @samp{x} to -return @samp{x}. The wrong thing is to expand @samp{x} unquoted. +return @samp{x}. The wrong thing is to expand @samp{x} unquoted, +because that would cause an infinite rescan loop. In @code{m4}, one might use macros to hold strings, as we do for variables in other programming languages, further checking them with: @@ -6054,11 +6134,11 @@ @end example @noindent -In cases like this one, an interdiction for a macro to hold its own -name would be a useless limitation. Of course, this leaves more rope -for the @acronym{GNU} @code{m4} user to hang himself! Rescanning hangs may be -avoided through careful programming, a little like for endless loops -in traditional programming languages. +In cases like this one, an interdiction for a macro to hold its own name +would be a useless limitation. Of course, this leaves more rope for the [EMAIL PROTECTED] @code{m4} user to hang himself! Rescanning hangs may be +avoided through careful programming, a little like for endless loops in +traditional programming languages. @end itemize @node Answers @@ -6173,6 +6253,8 @@ @error{}m4trace: -3- shift(`4') @end example [EMAIL PROTECTED] quadratic behavior, avoiding [EMAIL PROTECTED] avoiding quadratic behavior Each successive iteration was adding more quoted @code{shift} invocations, and the entire list contents were passing through every iteration. In general, when recursing, it is a good idea to make the @@ -6413,27 +6495,24 @@ @appendix Indices of concepts and macros @menu -* Concept index:: Index for many concepts * Macro index:: Index for all @code{m4} macros +* Concept index:: Index for many concepts @end menu [EMAIL PROTECTED] Concept index [EMAIL PROTECTED] Index for many concepts - [EMAIL PROTECTED] cp - @node Macro index @appendixsec Index for all @code{m4} macros -References are exclusively to the places where a builtin is introduced -the first time. - [EMAIL PROTECTED] [EMAIL PROTECTED] 1 [EMAIL PROTECTED] iftex +This index covers all @code{m4} builtins, as well as several useful +composite macros. References are exclusively to the places where a +macro is introduced the first time. @printindex fn [EMAIL PROTECTED] Concept index [EMAIL PROTECTED] Index for many concepts + [EMAIL PROTECTED] cp + @bye @c Local Variables: _______________________________________________ M4-patches mailing list [email protected] http://lists.gnu.org/mailman/listinfo/m4-patches
