Re: doc merge

[Eric Blake]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

According to Eric Blake on 3/1/2007 7:27 AM:
> A simple patch while waiting for any review on my bigger extended argument
> patch - merge more doc sections from the branch:
> 
> 2007-03-01  Eric Blake  <address@hidden>
> 
>       * doc/m4.texinfo (Syscmd, Esyscmd): Merge more doc sections.

Another merge.  This makes the index consistent between both branches, and
picks up the sysval section in HEAD.

branch:
2007-03-01  Eric Blake  <address@hidden>

        * doc/m4.texinfo: Pick up more index entries from head.  Follow
        more texinfo recommendations.
        (Sysval): Improve tests.

head:
2007-03-01  Eric Blake  <address@hidden>

        * doc/m4.texinfo: Improve the indices.
        (Concept index): Rearrange to be last.
        (Sysval): Merge from branch.

- --
Don't work too hard, make some time for fun as well!

Eric Blake             address@hidden
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFF55j284KuGfSFAYARAj/uAKCS7H/NMF5g9KrPdRzAbdvOE6Oy8ACcC6Kd
CtoEH1Flzi5O5srgZvGm+d4=
=/Thp
-----END PGP SIGNATURE-----

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.1.1.1.2.119
diff -u -p -r1.1.1.1.2.119 m4.texinfo
--- doc/m4.texinfo      1 Mar 2007 21:46:05 -0000       1.1.1.1.2.119
+++ doc/m4.texinfo      2 Mar 2007 03:18:26 -0000
@@ -2,15 +2,14 @@
 @comment ========================================================
 @comment %**start of header
 @setfilename m4.info
address@hidden GNU M4 macro processor
address@hidden version.texi
address@hidden GNU M4 @value{VERSION} macro processor
 @setchapternewpage odd
 @ifnothtml
 @setcontentsaftertitlepage
 @end ifnothtml
 @finalout
 
address@hidden version.texi
-
 @c @tabchar{}
 @c ----------
 @c The testsuite expects literal tab output in some examples, but
@@ -476,6 +475,7 @@ would explicitly pass the empty string f
 after @var{argument}, rather than ignoring them.
 @end deffn
 
address@hidden numbers
 All macro arguments in @code{m4} are strings, but some are given
 special interpretation, e.g., as numbers, file names, regular
 expressions, etc.  The documentation for each macro will state how the
@@ -645,7 +645,7 @@ details.  This option may be given more 
 
 @item -s
 @itemx --synclines
address@hidden syncronization lines
address@hidden synchronization lines
 @cindex location, input
 @cindex input location
 Generate synchronization lines, for use by the C preprocessor or other
@@ -2786,6 +2786,7 @@ Fortunately, there is support for macro 
 @cindex displaying macro definitions
 @cindex macros, displaying definitions
 @cindex definitions, displaying macro
address@hidden standard error, output to
 If you want to see what a name expands into, you can use the builtin
 @code{dumpdef}:
 
@@ -2835,6 +2836,7 @@ display.
 @cindex tracing macro expansion
 @cindex macro expansion, tracing
 @cindex expansion, tracing macro
address@hidden standard error, output to
 It is possible to trace macro calls and expansions through the builtins
 @code{traceon} and @code{traceoff}:
 
@@ -3822,7 +3824,6 @@ m4wrap(`m4wrap(`)')len(abc')
 
 @cindex file inclusion
 @cindex inclusion, of files
-
 @code{m4} allows you to include named files at any point in the input.
 
 @menu
@@ -3929,6 +3930,7 @@ using @code{undivert} (@pxref{Undivert})
 @acronym{GNU} @code{m4} allows included files to be found in other directories
 than the current working directory.
 
address@hidden @env{M4PATH}
 If the @option{--prepend-include} or @option{-B} command-line option was
 provided (@pxref{Preprocessor features, , Invoking m4}), those
 directories are searched first, in reverse order that those options were
@@ -3951,6 +3953,7 @@ Diversions are a way of temporarily savi
 reinserted into the output stream, @dfn{undiverted}, again at a later
 time.
 
address@hidden @env{TMPDIR}
 Numbered diversions are counted from 0 upwards, diversion number 0
 being the normal output stream.  The number of simultaneous diversions
 is limited mainly by the memory used to describe them, because @acronym{GNU}
@@ -4155,6 +4158,7 @@ undiverted, in numerical order.
 
 @cindex file inclusion
 @cindex inclusion, of files
address@hidden @acronym{GNU} extensions
 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.
@@ -5249,6 +5253,8 @@ run yet.
 @end deffn
 
 @example
+sysval
address@hidden
 syscmd(`false')
 @result{}
 ifelse(sysval, `0', `zero', `non-zero')
@@ -5306,6 +5312,10 @@ syscmd(`kill -9 $$')
 @result{}
 sysval
 @result{}2304
+syscmd()
address@hidden
+sysval
address@hidden
 esyscmd(`kill -9 $$')
 @result{}
 sysval
@@ -5414,6 +5424,7 @@ any of the previous chapters.
 @cindex printing error messages
 @cindex error messages, printing
 @cindex messages, printing error
address@hidden standard error, output to
 You can print error messages using @code{errprint}:
 
 @deffn Builtin errprint (@var{message}, @dots{})
@@ -5617,9 +5628,10 @@ speed up the start of an application usi
 
 @node Using frozen files
 @section Using frozen files
+
 @cindex fast loading of frozen files
 @cindex frozen files for fast loading
address@hidden initialization, frozen states
address@hidden initialization, frozen state
 @cindex dumping into frozen file
 @cindex reloading a frozen file
 @cindex @acronym{GNU} extensions
@@ -5717,6 +5729,7 @@ exit with status 63 to indicate version 
 
 @node Frozen file format
 @section Frozen file format
+
 @cindex frozen file format
 @cindex file format, frozen file
 Frozen files are sharable across architectures.  It is safe to write
@@ -5804,6 +5817,7 @@ is made to summarize these here.
 @section Extensions in @acronym{GNU} @code{m4}
 
 @cindex @acronym{GNU} extensions
address@hidden @acronym{POSIX}
 This version of @code{m4} contains a few facilities that do not exist
 in System V @code{m4}.  These extra facilities are all suppressed by
 using the @option{-G} command line option (@pxref{Limits control, ,

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.99
diff -u -p -r1.99 m4.texinfo
--- doc/m4.texinfo      1 Mar 2007 14:30:25 -0000       1.99
+++ doc/m4.texinfo      2 Mar 2007 03:20:58 -0000
@@ -2,15 +2,14 @@
 @comment ========================================================
 @comment %**start of header
 @setfilename m4.info
address@hidden GNU M4 macro processor
address@hidden version.texi
address@hidden GNU M4 @value{VERSION} macro processor
 @setchapternewpage odd
 @ifnothtml
 @setcontentsaftertitlepage
 @end ifnothtml
 @finalout
 
address@hidden version.texi
-
 @set beta
 
 @c @tabchar{}
@@ -295,8 +294,8 @@ How to make copies of this manual
 
 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
@@ -322,6 +321,7 @@ language, as shipped in the @acronym{GNU
 @node Intro
 @section Introduction to @code{m4}
 
address@hidden 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.
@@ -353,6 +353,8 @@ debugging their @code{m4} scripts than d
 @node History
 @section Historical references
 
address@hidden history of @code{m4}
address@hidden @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
@@ -413,6 +415,9 @@ Libtool.  @acronym{GNU} M4 2.0 is the re
 @node Bugs
 @section Problems and bugs
 
address@hidden reporting bugs
address@hidden bug reports
address@hidden 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
@@ -439,6 +444,7 @@ features, please report them too.
 @node Manual
 @section Using this manual
 
address@hidden 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
@@ -529,6 +535,8 @@ primitive is spelled within @code{m4}.
 @node Invoking m4
 @chapter Invoking @code{m4}
 
address@hidden command line
address@hidden invoking @code{m4}
 The format of the @code{m4} command is:
 
 @comment ignore
@@ -611,6 +619,8 @@ Discard all comments instead of copying 
 
 @item -E
 @itemx --fatal-warnings
address@hidden errors, fatal
address@hidden 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,
@@ -715,6 +725,7 @@ with respect to file names is significan
 
 @cindex macro definitions, on the command line
 @cindex command line, macro definitions on the
address@hidden 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
@@ -775,6 +786,9 @@ redefining the same @var{NAME} adds anot
 Short for @option{--syncoutput=1}, turning synchronization lines on.
 
 @item address@hidden@r{]}
address@hidden synchronization lines
address@hidden location, input
address@hidden input location
 Control the generation of synchronization lines from the command line.
 Synchronization lines are for use by the C preprocessor or other
 similar tools.  Order is significant with respect to file names.  This
@@ -830,6 +844,8 @@ It is implied if @env{POSIXLY_CORRECT} i
 
 @item -L @var{NUM}
 @itemx address@hidden
address@hidden nesting limit
address@hidden 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
@@ -846,6 +862,7 @@ when some complex @code{m4} input was ge
 Most users would never need this option.  If shown to be obtrusive,
 this option (which is still experimental) might well disappear.
 
address@hidden 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
@@ -1046,6 +1063,7 @@ exception of the @sc{nul} character (the
 @section Macro names
 
 @cindex names
address@hidden 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
@@ -1062,6 +1080,7 @@ changed at any time, using the builtin m
 @section Quoting input to @code{m4}
 
 @cindex quoted string
address@hidden 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
@@ -1126,6 +1145,7 @@ the builtin macros @code{changecom} (@px
 @node Other tokens
 @section Other kinds of input tokens
 
address@hidden 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,
@@ -1343,6 +1363,7 @@ expansion is treated.
 @section Macro invocation
 
 @cindex macro invocation
address@hidden invoking macros
 Macro invocations has one of the forms
 
 @comment ignore
@@ -1475,6 +1496,7 @@ divert`'
 the @code{divert} builtin macro will be called, which expands to the
 empty string.
 
address@hidden 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 @address@hidden(`abcde', `3', `2')}} as input:
@@ -1556,6 +1578,8 @@ macro(`unquoted trailing whitespace kept
 @result{}
 @end example
 
address@hidden warnings, suppressing
address@hidden 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
@@ -1655,6 +1679,8 @@ example with the parentheses, the `right
 foo(`() (() (')
 @end example
 
address@hidden quoting rule of thumb
address@hidden 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
@@ -1800,7 +1826,15 @@ not recognized.  It can only be referenc
 (@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.
+
address@hidden Composite array (@var{index})
address@hidden 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}.
address@hidden deffn
 
 @example
 define(`array', `defn(format(``array[%d]'', `$1'))')
@@ -1817,19 +1851,24 @@ array(eval(`10 + 7'))
 @result{}array element no. 17
 @end example
 
-Change the @code{%d} to @code{%s} and it is an associative array.
+Change the @samp{%d} to @samp{%s} and it is an associative array.
 
 @node Arguments
 @section Arguments to macros
 
 @cindex macros, arguments to
address@hidden Arguments to macros
address@hidden 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.
+
address@hidden Composite exch (@var{arg1}, @var{arg2})
+Expands to @var{arg2} followed by @var{arg1}, effectively exchanging
+their order.
address@hidden deffn
 
 @example
 define(`exch', `$2, $1')
@@ -1902,8 +1941,11 @@ There is a special notation for the numb
 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.
+
address@hidden Composite nargs (@dots{})
+Expands to a count of the number of arguments supplied.
address@hidden deffn
 
 @example
 define(`nargs', `$#')
@@ -2011,6 +2053,9 @@ foo
 @result{}$$$ hello $$$
 @end example
 
address@hidden rescanning
address@hidden literal output
address@hidden 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
@@ -2093,6 +2138,8 @@ case, @code{undefine} does nothing.
 
 @cindex macros, how to rename
 @cindex renaming macros
address@hidden macros, displaying definitions
address@hidden definitions, displaying macro
 It is possible to rename an already defined macro.  To do this, you need
 the builtin @code{defn}:
 
@@ -2161,6 +2208,7 @@ defn(`string')
 @result{}
 @end example
 
address@hidden 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
@@ -2183,6 +2231,8 @@ echo(foo)
 @result{}AA'
 @end example
 
address@hidden builtins, special tokens
address@hidden 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.
@@ -2225,6 +2275,8 @@ blah
 @cindex macros, temporary redefinition of
 @cindex temporary redefinition of macros
 @cindex redefinition of macros, temporary
address@hidden definition stack
address@hidden 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}:
@@ -2634,7 +2686,9 @@ defn2([foo])
 @node M4symbols
 @section Getting the defined macro names
 
address@hidden macro names
address@hidden macro names, listing
address@hidden listing macro names
address@hidden currently defined macros
 @cindex @acronym{GNU} extensions
 The name of the currently defined macros can be accessed by
 @code{m4symbols}:
@@ -2704,6 +2758,8 @@ ifdef(`no_such_macro', `yes', `no', `ext
 @section If-else construct, or multibranch
 
 @cindex comparing strings
address@hidden discarding input
address@hidden 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:
@@ -2776,6 +2832,8 @@ foo(`a', `b', `c')
 @end example
 
 @cindex multibranches
address@hidden switch statement
address@hidden 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
@@ -3188,6 +3246,8 @@ cleanup
 @node Debugging
 @chapter How to debug macros and input
 
address@hidden debugging macros
address@hidden 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}.
@@ -3206,6 +3266,7 @@ Fortunately, there is support for macro 
 @cindex displaying macro definitions
 @cindex macros, displaying definitions
 @cindex definitions, displaying macro
address@hidden standard error, output to
 If you want to see what a name expands into, you can use the builtin
 @code{dumpdef}:
 
@@ -3284,6 +3345,7 @@ debugmode(`-m')
 @cindex tracing macro expansion
 @cindex macro expansion, tracing
 @cindex expansion, tracing macro
address@hidden standard error, output to
 It is possible to trace macro calls and expansions through the builtins
 @code{traceon} and @code{traceoff}:
 
@@ -3776,6 +3838,8 @@ to @code{m4}.
 @section Deleting whitespace in input
 
 @cindex deleting whitespace in input
address@hidden discarding input
address@hidden input, discarding
 The builtin @code{dnl} stands for ``Discard to Next Line'':
 
 @deffn {Builtin (m4)} dnl
@@ -3834,8 +3898,9 @@ define(`hi', `HI')
 @node Changequote
 @section Changing the quote characters
 
address@hidden changing the quote delimiters
address@hidden quote delimiters, changing the
address@hidden changing quote delimiters
address@hidden quote delimiters, changing
address@hidden delimiters, changing
 The default quote delimiters can be changed with the builtin
 @code{changequote}:
 
@@ -4021,6 +4086,7 @@ It is an error if the end of file occurs
 
 @cindex changing comment delimiters
 @cindex comment delimiters, changing
address@hidden delimiters, changing
 The default comment delimiters can be changed with the builtin
 macro @code{changecom}:
 
@@ -4169,6 +4235,12 @@ changecom(`/*', `*/')
 @section Changing the regular expression syntax
 
 @cindex regular expression syntax, changing
address@hidden basic regular expressions
address@hidden extended regular expressions
address@hidden regular expressions
address@hidden expressions, regular
address@hidden syntax, changing regular expression
address@hidden flavors of regular expressions
 @cindex @acronym{GNU} extensions
 The @acronym{GNU} extensions @code{patsubst}, @code{regexp}, and more
 recently, @code{renamesyms} each deal with regular expressions.  There
@@ -4278,6 +4350,7 @@ patsubst(`ab', `a\|b', `c')
 @cindex lexical structure of the input
 @cindex input, lexical structure of the
 @cindex syntax table
address@hidden changing syntax
 @cindex @acronym{GNU} extensions
 @quotation
 The macro @code{changesyntax} and all associated functionality is
@@ -4680,6 +4753,8 @@ macro calls.
 
 @cindex saving input
 @cindex input, saving
address@hidden deferring expansion
address@hidden 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
@@ -4760,7 +4835,6 @@ m4wrap(`m4wrap(`)')len(abc')
 
 @cindex file inclusion
 @cindex inclusion, of files
-
 @code{m4} allows you to include named files at any point in the input.
 
 @menu
@@ -4889,6 +4963,7 @@ debug flag (@pxref{Debugmode}) can help 
 @node Diversions
 @chapter Diverting and undiverting output
 
address@hidden 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
@@ -4970,6 +5045,8 @@ m4wrap(`Wrapped text precedes ')
 @result{}Wrapped TEXT precedes diverted text.
 @end example
 
address@hidden discarding input
address@hidden 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
@@ -5028,6 +5105,8 @@ Undiverts the numeric @var{diversions} g
 order given.  If no arguments are supplied, all diversions are
 undiverted, in numerical order.
 
address@hidden file inclusion
address@hidden inclusion, of files
 @cindex @acronym{GNU} extensions
 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
@@ -5225,6 +5304,8 @@ cleardivert, , Answers}).
 @chapter Extending M4 with dynamic runtime modules
 
 @cindex modules
address@hidden dynamic modules
address@hidden loadable modules
 @acronym{GNU} M4 1.4.x had a monolithic architecture.  All of its
 functionality was contained in a single binary, and additional macros
 could be added only by writing more code in the M4 language, or at the
@@ -5530,6 +5611,7 @@ len(`abcdef')
 @node Index macro
 @section Searching for substrings
 
address@hidden substrings, locating
 Searching for substrings is done with @code{index}:
 
 @deffn {Builtin (m4)} index (@var{string}, @var{substring})
@@ -5560,6 +5642,7 @@ index(`abc')
 @section Searching for regular expressions
 
 @cindex regular expressions
address@hidden expressions, regular
 @cindex @acronym{GNU} extensions
 Searching for regular expressions is done with the builtin
 @code{regexp}:
@@ -5763,6 +5846,7 @@ translit(`abc')
 @section Substituting text by regular expression
 
 @cindex regular expressions
address@hidden expressions, regular
 @cindex pattern substitution
 @cindex substitution by regular expression
 @cindex @acronym{GNU} extensions
@@ -6395,7 +6479,6 @@ environment of @code{m4}.  If defined, e
 string.
 @end deffn
 
address@hidden platform macro
 On UNIX systems, @acronym{GNU} @code{m4} will define @address@hidden
 in the @samp{gnu} module, and @code{unix} in the @samp{traditional}
 module.
@@ -6546,25 +6629,87 @@ esyscmd(`echo hi')
 @node Sysval
 @section Exit status
 
address@hidden exit code from shell commands
address@hidden shell commands, exit code from
address@hidden UNIX commands, exit code from
address@hidden commands, exit code from shell
address@hidden UNIX commands, exit status from
address@hidden exit status from shell commands
address@hidden shell commands, exit status from
address@hidden commands, exit status from shell
address@hidden status of shell commands
+To see whether a shell command succeeded, use @code{sysval}:
+
 @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
address@hidden or @code{esyscmd}.
+Expands to the exit status of the last shell command run with
address@hidden or @code{esyscmd}.  Expands to 0 if no command has been
+run yet.
 @end deffn
 
 @example
+sysval
address@hidden
 syscmd(`false')
 @result{}
-ifelse(sysval, 0, zero, nonzero)
address@hidden
+ifelse(sysval, `0', `zero', `non-zero')
address@hidden
+syscmd(`exit 2')
address@hidden
+sysval
address@hidden
 syscmd(`true')
 @result{}
 sysval
 @result{}0
+esyscmd(`false')
address@hidden
+ifelse(sysval, `0', `zero', `non-zero')
address@hidden
+esyscmd(`exit 2')
address@hidden
+sysval
address@hidden
+esyscmd(`true')
address@hidden
+sysval
address@hidden
address@hidden example
+
address@hidden results in 127 if there was a problem executing the
+command, for example, if the system-imposed argument length is exceeded,
+or if there were not enough resources to fork.  It is not possible to
+distinguish between failed execution and successful execution that had
+an exit status of 127.
+
+On UNIX platforms, where it is possible to detect when command execution
+is terminated by a signal, rather than a normal exit, the result is the
+signal number shifted left by eight bits.
+
address@hidden This test has difficulties being portable, even on platforms
address@hidden where syscmd invokes /bin/sh.  Kill is not portable with signal
address@hidden names.  According to autoconf, the only portable signal numbers
address@hidden are 1 (HUP), 2 (INT), 9 (KILL), 13 (PIPE) and 15 (TERM).  But
address@hidden all shells handle SIGINT, and ksh handles HUP (as in, the shell
address@hidden exits normally rather than letting the signal terminate it).
address@hidden Also, TERM is flaky, as it can also kill the running m4 on
address@hidden systems where /bin/sh does not create its own process group.
address@hidden And PIPE is unreliable, since people tend to run with it
address@hidden ignored, with m4 inheriting that choice.  That leaves KILL as
address@hidden the only signal we can reliably test.
address@hidden
+dnl This test assumes kill is a shell builtin, and that signals are
+dnl recognizable.
+ifdef(`__unix__', ,
+      `errprint(` skipping: syscmd does not have unix semantics
+')m4exit(`77')')dnl
+syscmd(`kill -9 $$')
address@hidden
+sysval
address@hidden
+syscmd()
address@hidden
+sysval
address@hidden
+esyscmd(`kill -9 $$')
address@hidden
+sysval
address@hidden
 @end example
 
 When the @option{--safer} option (@pxref{Operation modes, , Invoking
@@ -6835,6 +6980,8 @@ had one, and @acronym{POSIX} is silent o
 @node Location
 @section Printing current location
 
address@hidden location, input
address@hidden input location
 To make it possible to specify the location of an error, three
 utility builtins exist:
 
@@ -6930,6 +7077,10 @@ within @code{syscmd} (@pxref{Syscmd}) to
 @section Exiting from @code{m4}
 
 @cindex exiting from @code{m4}
address@hidden status, setting @code{m4} exit
+If you need to exit from @code{m4} before the entire input has been
+read, you can use @code{m4exit}:
+
 @deffn {Builtin (m4)} m4exit (@ovar{code})
 If you need to exit from @code{m4} before the entire input has been
 read, you can use @code{m4exit}, which causes @code{m4} to exit, with
@@ -6955,7 +7106,10 @@ not followed, e.g., diverted text is not
 @node Syncoutput
 @section Turning on and off sync lines
 
address@hidden Toggling sync lines within @code{m4}
address@hidden toggling synchronization lines
address@hidden synchronization lines
address@hidden location, input
address@hidden input location
 @deffn {Builtin (gnu)} syncoutput (@var{truth})
 If you need to toggle sync lines on and off while processing macros, or
 to insure that they are off or on, you may do so using
@@ -7089,6 +7243,8 @@ Path}).
 @node Frozen file format 1
 @section Frozen file format 1
 
address@hidden frozen file format 1
address@hidden file format, frozen file version 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.
@@ -7103,6 +7259,8 @@ because a newer version of M4 reloaded t
 @node Frozen file format 2
 @section Frozen file format 2
 
address@hidden frozen file format 2
address@hidden file format, frozen file version 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}.
@@ -7510,6 +7668,8 @@ foreachq(`x', ``1', `2', `3', `4'', `x
 @error{}m4trace: -3- shift(`4')
 @end example
 
address@hidden quadratic behavior, avoiding
address@hidden 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
@@ -7756,27 +7916,24 @@ fatal_error(`inside wrapped text')')
 @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
 
address@hidden Concept index
address@hidden Index for many concepts
-
address@hidden 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.
-
address@hidden
address@hidden 1
address@hidden 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
 
address@hidden Concept index
address@hidden Index for many concepts
+
address@hidden cp
+
 @bye
 
 @c Local Variables: