Re: branch-1_4 doc improvements

[Eric Blake]

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

According to Eric Blake on 7/14/2006 7:55 PM:
> 
> Unless anyone else has a last-minute itch, I hope to release 1.4.5 tomorrow.

Hmm, the exit status is probably worth documenting.

2006-07-15  Eric Blake  <address@hidden>

        * src/m4.c (usage): Document exit status.
        * doc/m4.texinfo: Use `exit status', not `exit code'.
        (Invoking m4): Document exit status.

- --
Life is short - so eat dessert first!

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

iD8DBQFEuWdT84KuGfSFAYARAjQ1AKDGTDz6NWexle8ZKMWhdXA1C5VT/QCfUUnO
HPR3ywzUNAIcM7gP8vWANnY=
=5Zox
-----END PGP SIGNATURE-----

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.1.1.1.2.45
diff -u -p -r1.1.1.1.2.45 m4.texinfo
--- doc/m4.texinfo      15 Jul 2006 02:17:15 -0000      1.1.1.1.2.45
+++ doc/m4.texinfo      15 Jul 2006 21:49:28 -0000
@@ -234,7 +234,7 @@ Running shell commands
 * Platform macros::             Determining the platform
 * Syscmd::                      Executing simple commands
 * Esyscmd::                     Reading the output of commands
-* Sysval::                      Exit codes
+* Sysval::                      Exit status
 * Maketemp::                    Making names for temporary files
 
 Miscellaneous builtin macros
@@ -592,6 +592,9 @@ only be read once, so the file name @fil
 the command line.  It is an error if an input file ends in the middle of
 argument collection or a quoted string.
 
+If none of the input files invoked @code{m4exit} (@pxref{M4exit}), the
+exit status of @code{m4} will be 0 for success, and 1 for failure.
+
 If you need to read a file whose name starts with a @file{-}, you can
 specify it as @samp{./-file}, or use @option{--} to mark the end of
 options.
@@ -3605,7 +3608,7 @@ exit value if this is not the case.
 * Platform macros::             Determining the platform
 * Syscmd::                      Executing simple commands
 * Esyscmd::                     Reading the output of commands
-* Sysval::                      Exit codes
+* Sysval::                      Exit status
 * Maketemp::                    Making names for temporary files
 @end menu
 
@@ -3730,14 +3733,13 @@ Note how the expansion of @code{esyscmd}
 the command, as well as using the newline that appeared after the macro.
 
 @node Sysval
address@hidden Exit codes
address@hidden Exit status
 
address@hidden exit code from UNIX commands
address@hidden UNIX commands, exit code from
address@hidden commands, exit code from UNIX
address@hidden exit code from shell commands
address@hidden shell 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 sysval
@@ -3904,12 +3906,13 @@ errprint(`m4:'__file__:__line__: `input 
 @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 m4exit (@dvar{code, 0})
-Causes @code{m4} to exit, with exit code @var{code}.  If @var{code} is
-left out, the exit code is zero.  No further input is read, and all
+Causes @code{m4} to exit, with exit status @var{code}.  If @var{code} is
+left out, the exit status is zero.  No further input is read, and all
 wrapped and diverted text is discarded.
 @end deffn
 
@@ -3930,7 +3933,7 @@ fatal_error(`this is a BAD one, buster')
 @error{}m4:stdin: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
+After this macro call, @code{m4} will exit with exit status 1.  This macro
 is only intended for error exits, since the normal exit procedures are
 not followed, e.g., diverted text is not undiverted, and saved text
 (@pxref{M4wrap}) is not reread.
Index: src/m4.c
===================================================================
RCS file: /sources/m4/m4/src/Attic/m4.c,v
retrieving revision 1.1.1.1.2.17
diff -u -p -r1.1.1.1.2.17 m4.c
--- src/m4.c    13 Jul 2006 22:09:54 -0000      1.1.1.1.2.17
+++ src/m4.c    15 Jul 2006 21:49:28 -0000
@@ -215,6 +215,11 @@ of directories included after any specif
 \n\
 If no FILE or if FILE is `-', standard input is read.\n\
 ", stdout);
+      fputs ("\
+\n\
+Exit status is 0 for success, 1 for failure, or whatever value was passed\n\
+to the m4exit macro.\n\
+", stdout);
     }
   exit (status);
 }