Changes to m4/doc/m4.texinfo,v

[Eric Blake]

CVSROOT:        /sources/m4
Module name:    m4
Changes by:     Eric Blake <ericb>      06/07/15 21:35:37

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.25
retrieving revision 1.26
diff -u -b -r1.25 -r1.26
--- doc/m4.texinfo      15 Jul 2006 00:15:01 -0000      1.25
+++ doc/m4.texinfo      15 Jul 2006 21:35:37 -0000      1.26
@@ -1,47 +1,76 @@
-\input texinfo
address@hidden %**start of header
+\input texinfo @c -*- texinfo -*-
address@hidden ========================================================
address@hidden %**start of header
 @setfilename m4.info
address@hidden GNU macro processor
address@hidden GNU M4 macro processor
address@hidden odd
address@hidden
address@hidden
address@hidden ifnothtml
 @finalout
address@hidden %**end of header
 
 @include version.texi
 
 @set beta
 
address@hidden A simple macro for optional variables.
address@hidden @tabchar{}
address@hidden ----------
address@hidden The testsuite expects literal tab output in some examples, but
address@hidden literal tabs in texinfo lead to formatting issues.
address@hidden tabchar
+@      @c
address@hidden macro
+
address@hidden @ovar{ARG}
address@hidden -------------------
address@hidden The ARG is an optional argument.  To be used for macro arguments 
in
address@hidden their documentation.
 @macro ovar{varname}
 @address@hidden@r{]}
 @end macro
 
address@hidden Text Processing Tools
address@hidden
-* m4: (m4).                    A powerful macro processor.
address@hidden direntry
address@hidden @dvar{ARG, DEFAULT}
address@hidden -------------------
address@hidden The ARG is an optional argument, defaulting to DEFAULT.  To be 
used
address@hidden for macro arguments in their documentation.
address@hidden dvar{varname, default}
address@hidden@var{\varname\} = @address@hidden
address@hidden macro
+
address@hidden %**end of header
address@hidden ========================================================
 
address@hidden
-This file documents GNU @code{m4} @value{VERSION}
address@hidden
 
-Copyright (C) 1989, 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000,
-2001, 2004, 2005, 2006 Free Software Foundation, Inc.
+This manual is for GNU M4 (version @value{VERSION}, @value{UPDATED}),
+a package containing an implementation of the m4 macro language.
+
+Copyright @copyright{} 1989, 1990, 1991, 1992, 1993, 1994, 1998, 1999,
+2000, 2001, 2004, 2005, 2006 Free Software Foundation, Inc.
 
address@hidden
 Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1
-or any later version published by the Free Software Foundation;
-with the no Invariant Sections, with no Front-Cover Texts,
-and with no Back-Cover Texts.  A copy of the license is included in
-the section entitled "GNU Free Documentation License".
-
address@hidden
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries copying permission notice
-identical to this one except for the removal of this paragraph
+under the terms of the @acronym{GNU} Free Documentation License,
+Version 1.2 or any later version published by the Free Software
+Foundation; with no Invariant Sections, with the Front-Cover texts
+being ``A @acronym{GNU} Manual,'' and with the Back-Cover Texts as in
+(a) below.  A copy of the license is included in the section entitled
address@hidden Free Documentation License.''
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and
+modify this @acronym{GNU} Manual, like @acronym{GNU} software.  Copies
+published by the Free Software Foundation raise funds for
address@hidden development.''
address@hidden quotation
address@hidden copying
 
address@hidden ignore
address@hidden ifinfo
address@hidden GNU programming tools
address@hidden
+* M4: (m4).                     A powerful macro processor.
address@hidden direntry
 
 @titlepage
address@hidden GNU m4, version @value{VERSION}
address@hidden GNU M4, version @value{VERSION}
 @subtitle A powerful macro processor
 @subtitle Edition @value{EDITION}, @value{UPDATED}
 @author by Ren@'e Seindal
@@ -49,24 +78,17 @@
 
 @page
 @vskip 0pt plus 1filll
-Copyright @copyright{} 1989, 1990, 1991, 1992, 1993, 1994, 1998, 1999,
-2000, 2001, 2004, 2005, 2006 Free Software Foundation, Inc.
-
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1
-or any later version published by the Free Software Foundation;
-with the no Invariant Sections, with no Front-Cover Texts,
-and with no Back-Cover Texts.  A copy of the license is included in
-the section entitled "GNU Free Documentation License".
-
address@hidden
 @end titlepage
 
address@hidden
+
 @ifnottex
address@hidden Top, Preliminaries, (dir), (dir)
address@hidden GNU @code{m4}
address@hidden Top
address@hidden GNU M4
address@hidden
address@hidden ifnottex
 
address@hidden @item @address@hidden @value{hfillkludge} (UtilD, UtilT, SrcCD)
address@hidden
 GNU @code{m4} is an implementation of the traditional UNIX macro
 processor.  It is mostly SVR4 compatible, although it has some
 extensions (for example, handling more than 9 positional parameters
@@ -78,21 +100,20 @@
 GNU @code{m4} was originally written by Ren@'e Seindal, with
 subsequent changes by Fran@,{c}ois Pinard and other volunteers
 on the Internet.  All names and email addresses can be found in the
-files @file{AUTHORS} and @file{THANKS} from the GNU @code{m4}
-distribution.
+files @file{AUTHORS} and @file{THANKS} from the GNU M4 distribution.
 
 @ifclear beta
 This is release @value{VERSION}.  It is now to be considered stable,
-future releases are only meant to fix bugs, increase speed, or improve
-documentation.  address@hidden
+future releases on this branch are only meant to fix bugs, increase
+speed, or improve documentation.
 @end ifclear
 
 @ifset beta
 This is BETA release @value{VERSION}.  This is a development release,
-and is as such prone to bugs, crashes, unforeseen features, incomplete
address@hidden therefore, use at your own peril.  In case of
-problems, please do not hesitate to report them (see the README file in
-the distribution).
+and as such, is prone to bugs, crashes, unforeseen features, incomplete
address@hidden, therefore, use at your own peril.  In case of
+problems, please do not hesitate to report them (see the @file{README}
+file in the distribution).  @xref{Experiments}.
 @end ifset
 
 @menu
@@ -101,7 +122,7 @@
 
 * Macros::                      How to invoke macros
 * Definitions::                 How to define new macros
-* Conditionals::                Conditionals, loops an recursions
+* Conditionals::                Conditionals, loops, and recursions
 
 * Debugging::                   How to debug macros and input
 
@@ -113,17 +134,18 @@
 
 * Text handling::               Macros for text handling
 * Arithmetic::                  Macros for doing arithmetic
-* UNIX commands::               Macros for running UNIX commands
+* Shell commands::              Macros for running shell commands
 * Miscellaneous::               Miscellaneous builtin macros
-* Frozen files::                Fast loading of frozen states
+* Frozen files::                Fast loading of frozen state
 
 * Compatibility::               Compatibility with other versions of m4
 * Experiments::                 Experimental features in GNU m4
 * Answers::                     Correct version of some examples
-* Concept index::               Index for many concepts
-* Macro index::                 Index for all m4 macros
+* Copying This Manual::         How to make copies of this manual
+* Indices::                     Indices of concepts and macros
 
address@hidden --- The Detailed Node Listing ---
address@hidden
+ --- The Detailed Node Listing ---
 
 Introduction and preliminaries
 
@@ -165,7 +187,7 @@
 
 * Symbols::                     Getting the defined macro names
 
-Conditionals, loops and recursion
+Conditionals, loops, and recursion
 
 * Ifdef::                       Testing if a macro is defined
 * Ifelse::                      If-else construct, or multibranch
@@ -209,7 +231,7 @@
 Macros for text handling
 
 * Len::                         Calculating length of strings
-* Index::                       Searching for substrings
+* Index macro::                 Searching for substrings
 * Regexp::                      Searching for regular expressions
 * Substr::                      Extracting substrings
 * Translit::                    Translating characters
@@ -219,11 +241,12 @@
 Macros for doing arithmetic
 
 * Incr::                        Decrement and increment operators
-* Eval::                        Evaluating integer or rational expressions
-* Mpeval::
+* Eval::                        Evaluating integer expressions
+* Mpeval::                      Multiple precision arithmetic
 
-Running UNIX commands
+Running shell commands
 
+* Platform macros::             Determining the platform
 * Syscmd::                      Executing simple commands
 * Esyscmd::                     Reading the output of commands
 * Sysval::                      Exit codes
@@ -235,26 +258,39 @@
 * M4exit::                      Exiting from m4
 * Syncoutput::                  Turning on and off sync lines
 
+Fast loading of frozen state
+
+* Using frozen files::          Using frozen files
+* Frozen file format 1::        Frozen file format 1
+* Frozen file format 2::        Frozen file format 2
+
 Compatibility with other versions of @code{m4}
 
 * Extensions::                  Extensions in GNU m4
-* Other Incompat::              Other incompatibilities
+* Incompatibilities::           Other incompatibilities
+
+Copying This Manual
+
+* GNU Free Documentation License::  License for copying this manual
+
+Indices
+
+* Concept index::               Index for many concepts
+* Macro index::                 Index for all m4 macros
 
 @end detailmenu
 @end menu
 
address@hidden ifnottex
-
 @node Preliminaries
 @chapter Introduction and preliminaries
 
-This first chapter explains what is GNU @code{m4}, where @code{m4}
+This first chapter explains what GNU @code{m4} is, where @code{m4}
 comes from, how to read and use this documentation, how to call the
address@hidden program and how to report bugs about it.  It concludes by
address@hidden program, and how to report bugs about it.  It concludes by
 giving tips for reading the remainder of the manual.
 
 The following chapters then detail all the features of the @code{m4}
-language.
+language, as shipped in the GNU M4 package.
 
 @menu
 * Intro::                       Introduction to @code{m4}
@@ -271,7 +307,7 @@
 input to the output, expanding macros as it goes.  Macros are either
 builtin or user-defined, and can take any number of arguments.
 Besides just doing macro expansion, @code{m4} has builtin functions
-for including named files, running UNIX commands, doing integer
+for including named files, running shell commands, doing integer
 arithmetic, manipulating text in various ways, recursion, address@hidden
 @code{m4} can be used either as a front-end to a compiler, or as a
 macro processor in its own right.
@@ -1082,7 +1118,7 @@
 @xref{Pushdef, , Temporarily redefining macros}, for an explanation of
 @code{pushdef}.  Some other UNIX implementations replace all definitions
 of a macro with @code{define}.
address@hidden Incompat, , Other incompatibilities}, for more details.
address@hidden, , Other incompatibilities}, for more details.
 
 The first argument to @code{define} does not have to be a simple word.
 It can be any text string.  A macro with a non standard name cannot be
@@ -1555,7 +1591,7 @@
 @end deffn
 
 @node Conditionals
address@hidden Conditionals, loops and recursion
address@hidden Conditionals, loops, and recursion
 
 Macros, expanding to plain text, perhaps with arguments, are not quite
 enough.  We would like to have macros expand to different things, based
@@ -1687,7 +1723,7 @@
 order of its arguments:
 
 @example
-define(`reverse', `ifelse($#, 0, , $#, 1, ``$1'',
+define(`reverse', `ifelse(`$#', `0', , `$#', `1', ``$1'',
                          `reverse(shift($@@)), `$1'')')
 @result{}
 reverse
@@ -1801,10 +1837,10 @@
 define(`foo', `Hello world.')
 @result{}
 dumpdef(`foo')
address@hidden: `Hello world.'
address@hidden:@tabchar{}`Hello world.'
 @result{}
 dumpdef(`define')
address@hidden: <define>
address@hidden:@tabchar{}<define>
 @result{}
 @end example
 
@@ -2603,10 +2639,10 @@
 @end deffn
 
 @example
-include(`no-such-file')
+include(`none')
 @result{}
address@hidden: input.m4: 1: Cannot open no-such-file: No such file or directory
-sinclude(`no-such-file')
address@hidden: input.m4: 1: Cannot open none: No such file or directory
+sinclude(`none')
 @result{}
 @end example
 
@@ -2892,7 +2928,7 @@
 
 @example
 define(`cleardivert',
-`pushdef(`_num', divnum)divert(-1)undivert($@@)divert(_num)popdef(`_num')')
+`pushdef(`_n', divnum)divert(`-1')undivert($@@)divert(_n)popdef(`_n')')
 @result{}
 @end example
 
@@ -3136,7 +3172,7 @@
 
 @menu
 * Len::                         Calculating length of strings
-* Index::                       Searching for substrings
+* Index macro::                 Searching for substrings
 * Regexp::                      Searching for regular expressions
 * Substr::                      Extracting substrings
 * Translit::                    Translating characters
@@ -3163,7 +3199,7 @@
 @result{}6
 @end example
 
address@hidden Index
address@hidden Index macro
 @section Searching for substrings
 
 @deffn {Builtin (m4)} index (@var{string}, @var{substring})
@@ -3230,7 +3266,8 @@
 remains unchanged for other invocations:
 
 @example
-regexp(`GNUs not Unix', `\w(\w+)$', `*** \& *** \1 ***', `POSIX_EXTENDED')
+regexp(`GNUs not Unix', `\w(\w+)$', `*** \& *** \1 ***',
+       `POSIX_EXTENDED')
 @result{}*** Unix *** nix ***
 @end example
 
@@ -3367,7 +3404,8 @@
 define(`upcase',   `translit(`$*', `a-z', `A-Z')')dnl
 define(`downcase', `translit(`$*', `A-Z', `a-z')')dnl
 define(`capitalize1',
-       `regexp(`$1', `^\(\w\)\(\w*\)', `upcase(`\1')`'downcase(`\2')')')dnl
+       `regexp(`$1', `^\(\w\)\(\w*\)',
+               `upcase(`\1')`'downcase(`\2')')')dnl
 define(`capitalize',
        `patsubst(`$1', `\w+', `capitalize1(`\&')')')dnl
 capitalize(`GNUs not Unix')
@@ -3424,8 +3462,8 @@
 @example
 define(`foo', `The brown fox jumped over the lazy dog')
 @result{}
-format(`The string "%s" is %d characters long', foo, len(foo))
address@hidden string "The brown fox jumped over the lazy dog" is 38 characters 
long
+format(`The string "%s" uses %d characters', foo, len(foo))
address@hidden string "The brown fox jumped over the lazy dog" uses 38 
characters
 @end example
 
 Using the @code{forloop} macro defined in @xref{Loops}, this
@@ -3466,8 +3504,8 @@
 
 @menu
 * Incr::                        Decrement and increment operators
-* Eval::                        Evaluating integer or rational expressions
-* Mpeval::
+* Eval::                        Evaluating integer expressions
+* Mpeval::                      Multiple precision arithmetic
 @end menu
 
 @node Incr
@@ -3610,7 +3648,6 @@
 Take note that @var{radix} cannot be larger than 36.
 
 @node Mpeval
address@hidden  node-name,  next,  previous,  up
 @section Multiple precision arithmetic
 
 When @code{m4} is compiled with a multiple precision arithmetic library
@@ -3631,23 +3668,29 @@
 The builtin macro @code{mpeval} is recognized only when given arguments.
 @end deffn
 
address@hidden UNIX commands
address@hidden Running UNIX commands
address@hidden Shell commands
address@hidden Running shell commands
 
address@hidden executing UNIX commands
address@hidden running UNIX commands
address@hidden executing shell commands
address@hidden running shell commands
address@hidden shell commands, running
 @cindex UNIX commands, running
address@hidden commands, running UNIX
-There are a few builtin macros in @code{m4} that allow you to run UNIX
address@hidden commands, running shell
+There are a few builtin macros in @code{m4} that allow you to run shell
 commands from within @code{m4}.
 
 @menu
+* Platform macros::             Determining the platform
 * Syscmd::                      Executing simple commands
 * Esyscmd::                     Reading the output of commands
 * Sysval::                      Exit codes
 * Maketemp::                    Making names for temporary files
 @end menu
 
address@hidden Platform macros
address@hidden Determining the platform
address@hidden FIXME - port from branch
+
 @node Syscmd
 @section Executing simple commands
 
@@ -3685,7 +3728,7 @@
 
 @cindex GNU extensions
 @deffn {Builtin (gnu)} esyscmd (@var{shell-command})
-If you want @code{m4} to read the output of a UNIX command, use
+If you want @code{m4} to read the output of a shell command, use
 @code{esyscmd}, which expands to the standard output of the shell
 command @var{shell-command}.
 
@@ -3714,9 +3757,10 @@
 @node Sysval
 @section Exit codes
 
address@hidden exit code from UNIX commands
address@hidden exit code from shell commands
address@hidden shell commands, exit code from
 @cindex UNIX commands, exit code from
address@hidden commands, exit code from UNIX
address@hidden commands, exit code from shell
 @deffn {Builtin (m4)} sysval
 To see whether a shell command succeeded, use @code{sysval}, which
 expands to the exit status of the last shell command run with
@@ -3827,11 +3871,12 @@
 
 @comment status: 1
 @example
-define(`fatal_error', `errprint(`m4: '__file__: __line__`: fatal error: $*
+define(`fatal_error',
+       `errprint(`m4:'__file__:__line__`: fatal error: $*
 ')m4exit(1)')
 @result{}
 fatal_error(`This is a BAD one, buster')
address@hidden: input.m4: 3: fatal error: This is a BAD one, buster
address@hidden:input.m4:4: fatal error: This is a BAD one, buster
 @end example
 
 After this macro call, @code{m4} will exit with exit code 1.  This macro
@@ -3860,20 +3905,29 @@
 @end deffn
 
 @node Frozen files
address@hidden Fast loading of frozen states
address@hidden Fast loading of frozen state
 
address@hidden fast loading of frozen files
address@hidden frozen files for fast loading
address@hidden initialization, frozen states
address@hidden dumping into frozen file
address@hidden reloading a frozen file
address@hidden GNU extensions
 Some bigger @code{m4} applications may be built over a common base
 containing hundreds of definitions and other costly initializations.
 Usually, the common base is kept in one or more declarative files,
 which files are listed on each @code{m4} invocation prior to the
 user's input file, or else, @code{include}'d from this input file.
 
address@hidden
+* Using frozen files::          Using frozen files
+* Frozen file format 1::        Frozen file format 1
+* Frozen file format 2::        Frozen file format 2
address@hidden menu
+
address@hidden Using frozen files
address@hidden Using frozen files
+
address@hidden fast loading of frozen files
address@hidden frozen files for fast loading
address@hidden initialization, frozen state
address@hidden dumping into frozen file
address@hidden reloading a frozen file
address@hidden GNU extensions
 Reading the common base of a big application, over and over again, may
 be time consuming.  GNU @code{m4} offers some machinery to speed up
 the start of an application using lengthy common bases.  Presume the
@@ -3966,6 +4020,16 @@
 It is looked up the same way as an @code{include} file (@pxref{Search
 Path}).
 
address@hidden Frozen file format 1
address@hidden Frozen file format 1
+
+Wow - thanks for really reading the manual.  Report this as a bug if
+this text is not removed before a release.
+FIXME - split out the two formats into separate nodes.
+
address@hidden Frozen file format 2
address@hidden Frozen file format 2
+
 Frozen files are sharable across architectures.  It is safe to write
 a frozen file on one machine and read it on another, given that the
 second machine uses the same, or a newer version of GNU @code{m4}.
@@ -4050,7 +4114,7 @@
 
 @menu
 * Extensions::                  Extensions in GNU m4
-* Other Incompat::              Other incompatibilities
+* Incompatibilities::           Other incompatibilities
 @end menu
 
 @node Extensions
@@ -4143,7 +4207,7 @@
 Also, the debugging and tracing facilities in GNU @code{m4} are much
 more extensive than in most other versions of @code{m4}.
 
address@hidden Other Incompat
address@hidden Incompatibilities
 @section Other incompatibilities
 
 There are a few other incompatibilities between this implementation of
@@ -4260,7 +4324,7 @@
 
 
 @node Answers
address@hidden Answers
address@hidden Correct version of some examples
 
 Some of the examples in this manuals are buggy.  Correctly working
 macros are presented here.
@@ -4280,20 +4344,36 @@
 If called without arguments, it will call undivert without argument,
 otherwise they will be passed to undivert().
 
address@hidden ========================================================== 
Appendices
+
address@hidden Copying This Manual
address@hidden Copying This Manual
address@hidden License
+
address@hidden
+* GNU Free Documentation License::  License for copying this manual
address@hidden menu
 
address@hidden fdl.texi
 
address@hidden Indices
address@hidden Indices
+
address@hidden
+* Concept index::               Index for many concepts
+* Macro index::                 Index for all m4 macros
address@hidden menu
 
 @node Concept index
address@hidden Concept index
address@hidden Concept index
 
 @printindex cp
 
 @node Macro index
address@hidden Macro index
address@hidden Macro index
 
 References are exclusively to the places where a builtin is introduced
-the first time.  Names starting and ending with @samp{__} have these
-characters removed in the index.
+the first time.
 
 @iftex
 @sp 1
@@ -4301,6 +4381,11 @@
 
 @printindex fn
 
address@hidden
address@hidden
 @bye
+
address@hidden Local Variables:
address@hidden fill-column: 72
address@hidden ispell-local-dictionary: "american"
address@hidden indent-tabs-mode: nil
address@hidden whitespace-check-buffer-indent: nil
address@hidden End: