more doc merges

[Eric Blake]

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

Some two-way merges.  On the branch, doc merges found a bug where
include(nosuchfile) failed to affect the exit status.  On head, I updated
the platform test macros, and added tests for some of the macros that were
not being exercised in the testsuite.  I decided it was better to name
module test macros by their module name (ie. __mpeval__ instead of
__gmp__), especially since it had never been documented or tested in 1.4o.

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

        * doc/m4.texinfo: Pull in various improvements from head.
        * src/builtin.c (include): Alter exit status on failure.
        * NEWS: Document this fix.

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

        * tests/builtins.at (__m4_version__): New test.
        * modules/traditional.c (m4_macro_table): Provide windows and os2
        macros, as appropriate.  Add __traditional__ macro.
        * modules/mpeval.c (m4_macro_table): Name the macro __mpeval__,
        not __gmp__, to match module name.
        * modules/load.c (m4_macro_table): Name the macro __load__, not
        __modules__, to match module name.
        * doc/m4.texinfo (History, Shell commands, Platform macros): Merge
        from the branch.
        (Standard Modules): Improve wording.
        (Incompatibilities): Move platform macros into their own node.
        (Load, Unload): Use actual examples.
        * NEWS: Document this change.
        * THANKS: Update.

- --
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

iD8DBQFFq4dO84KuGfSFAYARAg0+AKDPYwaTWZP9efmxu/Bx/kwaDv4eXACfZGXE
mBQzKr0U6zwp3yG8quzVlS0=
=ai3/
-----END PGP SIGNATURE-----

Index: NEWS
===================================================================
RCS file: /sources/m4/m4/NEWS,v
retrieving revision 1.1.1.1.2.89
diff -u -p -r1.1.1.1.2.89 NEWS
--- NEWS        13 Jan 2007 13:33:13 -0000      1.1.1.1.2.89
+++ NEWS        15 Jan 2007 13:33:47 -0000
@@ -13,6 +13,8 @@ Version 1.4.9 - ?? ??? 2007, by ????  (C
   previously undocumented alias of '=' meaning '==' in eval now triggers a
   deprecation warning, so that a future version of M4 can implement a form
   of variable assignment as an extension.
+* The `include' builtin now affects exit status on failure, as required by
+  POSIX.  Use `sinclude' if you need a successful exit status.
 * Improved portability to platforms such as BSD/OS.
 
 Version 1.4.8 - 20 November 2006, by Eric Blake  (CVS version 1.4.7a)
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.1.1.1.2.107
diff -u -p -r1.1.1.1.2.107 m4.texinfo
--- doc/m4.texinfo      9 Jan 2007 16:12:43 -0000       1.1.1.1.2.107
+++ doc/m4.texinfo      15 Jan 2007 13:33:48 -0000
@@ -377,7 +377,7 @@ limitations.
 
 More recently, in 2004, Paul Eggert released 1.4.1 and 1.4.2 which
 addressed some long standing bugs in the venerable 1.4 release.  Then in
-2005 Gary V. Vaughan collected together the many patches to
+2005, Gary V. Vaughan collected together the many patches to
 @acronym{GNU} @code{m4} 1.4 that were floating around the net and
 released 1.4.3 and 1.4.4.  And in 2006, Eric Blake joined the team and
 prepared patches for the release of 1.4.5, 1.4.6, 1.4.7, and 1.4.8.  The
@@ -551,8 +551,8 @@ performing any other actions.
 
 @item -E
 @itemx --fatal-warnings
-Stop execution and exit @code{m4} once the first warning has been
-issued, considering all of them to be fatal.
+Stop execution and exit @code{m4} once the first warning or error has
+been issued, considering all of them to be fatal.
 
 @item -i
 @itemx --interactive
@@ -805,7 +805,9 @@ token is either a name, a quoted string,
 is not a part of either a name or a string.  Input to @code{m4} can also
 contain comments.  @acronym{GNU} @code{m4} does not yet understand
 locales; all operations are byte-oriented rather than
-character-oriented.  However, @code{m4} is eight-bit clean, so you can
+character-oriented (although if your locale uses a single byte
+encoding, such as @sc{ISO-8859-1}, you will not notice a difference).
+However, @code{m4} is eight-bit clean, so you can
 use address@hidden characters in quoted strings (@pxref{Changequote}),
 comments (@pxref{Changecom}), and macro names (@pxref{Indir}), with the
 exception of the @sc{nul} character (the zero byte @samp{'\0'}).
@@ -1014,13 +1016,28 @@ sometimes be the source of spurious, unw
 @code{m4} offers several mechanisms or techniques for inhibiting the
 recognition of names as macro calls.
 
-First of all, many builtin macros cannot meaningfully be called
-without arguments.  For any of these macros, whenever an opening
-parenthesis does not immediately follow their name, the builtin macro
-call is not triggered.  This solves the most usual cases, like for
address@hidden or @samp{eval}.  Later in this document, the sentence
-``This macro is recognized only with parameters'' refers to this
-specific provision.
address@hidden @acronym{GNU} extensions
address@hidden blind macro
address@hidden macro, blind
+First of all, many builtin macros cannot meaningfully be called without
+arguments.  As a @acronym{GNU} extension, for any of these macros,
+whenever an opening parenthesis does not immediately follow their name,
+the builtin macro call is not triggered.  This solves the most usual
+cases, like for @samp{include} or @samp{eval}.  Later in this document,
+the sentence ``This macro is recognized only with parameters'' refers to
+this specific provision of @acronym{GNU} M4, also known as a blind
+builtin macro.  For the builtins defined by @acronym{POSIX} that bear
+this disclaimer, @acronym{POSIX} specifically states that invoking those
+builtins without arguments is unspecified, because many other
+implementations simply invoke the builtin as though it were given one
+empty argument instead.
+
address@hidden
+eval
address@hidden
+eval(`1')
address@hidden
address@hidden example
 
 There is also a command line option (@option{--prefix-builtins}, or
 @option{-P}, @pxref{Operation modes, , Invoking m4}) that renames all
@@ -2045,10 +2062,12 @@ ifelse(foo, `foo', `true', `false')
 @result{}false
 @end example
 
address@hidden macro, blind
address@hidden blind macro
 Notice how the first argument was used unquoted; it is common to compare
 the expansion of a macro with a string.  With this macro, you can now
-reproduce the behavior of many of the builtins, where the macro is
-recognized only with arguments.
+reproduce the behavior of blind builtins, where the macro is recognized
+only with arguments.
 
 @example
 define(`foo', `ifelse(`$#', `0', ``$0'', `arguments:$#')')
@@ -2499,7 +2518,8 @@ It is possible to trace macro calls and 
 @deffn Builtin traceon (@address@hidden)
 @deffnx Builtin traceoff (@address@hidden)
 When called without any arguments, @code{traceon} and @code{traceoff}
-will turn tracing on and off, respectively, for all defined macros.
+will turn tracing on and off, respectively, for all currently defined
+macros.
 
 When called with arguments, only the macros listed in @var{names} are
 affected, whether or not they are currently defined.
@@ -2594,54 +2614,66 @@ display.
 
 @cindex controlling debugging output
 @cindex debugging output, controlling
-The @option{-d} option to @code{m4} (@pxref{Debugging options, ,
-Invoking m4}) controls the amount of details presented, when using the
-macros described in the preceding sections.
+The @option{-d} option to @code{m4} (or @option{--debug},
address@hidden options, , Invoking m4}) controls the amount of details
+presented in three
+categories of output.  Trace output is requested by @code{traceon}
+(@pxref{Trace}), and each line is prefixed by @samp{m4trace:} in
+relation to a macro invocation.  Debug output tracks useful events not
+associated with a macro invocation, and each line is prefixed by
address@hidden:}.  Finally, @code{dumpdef} (@pxref{Dumpdef}) output is
+affected, with no prefix added to the output lines.
 
 The @var{flags} following the option can be one or more of the
 following:
 
 @table @code
 @item a
-Show the actual arguments in each macro call.  This applies to all macro
-calls if the @samp{t} flag is used, otherwise only the macros covered by
-calls of @code{traceon}.
+In trace output, show the actual arguments that were collected before
+invoking the macro.  This applies to all macro calls if the @samp{t}
+flag is used, otherwise only the macros covered by calls of
address@hidden
 
 @item c
-Show several trace lines for each macro call.  A line is shown when the
-macro is seen, but before the arguments are collected; a second line
-when the arguments have been collected and a third line after the call
-has completed.
+In trace output, show several trace lines for each macro call.  A line
+is shown when the macro is seen, but before the arguments are collected;
+a second line when the arguments have been collected and a third line
+after the call has completed.
 
 @item e
-Show the expansion of each macro call, if it is not void.  This applies
-to all macro calls if the @samp{t} flag is used, otherwise only the
-macros covered by calls of @code{traceon}.
+In trace output, show the expansion of each macro call, if it is not
+void.  This applies to all macro calls if the @samp{t} flag is used,
+otherwise only the macros covered by calls of @code{traceon}.
 
 @item f
-Show the name of the current input file in each trace output line.
+In debug and trace output, include the name of the current input file in
+the output line.
 
 @item i
-Print a message each time the current input file is changed, giving file
-name and input line number.
+In debug output, print a message each time the current input file is
+changed.
 
 @item l
-Show the current input line number in each trace output line.
+In debug and trace output, include the current input line number in the
+output line.
 
 @item p
-Print a message when a named file is found through the path search
-mechanism (@pxref{Search Path}), giving the actual file name used.
+In debug output, print a message when a named file is found through the
+path search mechanism (@pxref{Search Path}), giving the actual file name
+used.
 
 @item q
-Quote actual arguments and macro expansions in the display with the
-current quotes.
+In trace and dumpdef output, quote actual arguments and macro expansions
+in the display with the current quotes.  This is useful in connection
+with the @samp{a} and @samp{e} flags above.
 
 @item t
-Trace all macro calls made in this invocation of @code{m4}.
+In trace output, trace all macro calls made in this invocation of
address@hidden, regardless of the settings of @code{traceon}.
 
 @item x
-Add a unique `macro call id' to each line of the trace output.  This is
-useful in connection with the @samp{c} flag above.
+In trace output, add a unique `macro call id' to each line of the trace
+output.  This is useful in connection with the @samp{c} flag above.
 
 @item V
 A shorthand for all of the above flags.
@@ -3488,6 +3520,7 @@ The macros @code{include} and @code{sinc
 parameters.
 @end deffn
 
address@hidden status: 1
 @example
 include(`none')
 @error{}m4:stdin:1: cannot open `none': No such file or directory
@@ -4706,8 +4739,8 @@ exit value if this is not the case.
 @section Determining the platform
 
 @cindex platform macros
-Sometimes it is desirable for an input file to know which
-platform @code{m4} is running on.  @acronym{GNU} @code{m4} provides several
+Sometimes it is desirable for an input file to know which platform
address@hidden is running on.  @acronym{GNU} @code{m4} provides several
 macros that are predefined to expand to the empty string; checking for
 their existence will confirm platform details.
 
Index: src/builtin.c
===================================================================
RCS file: /sources/m4/m4/src/Attic/builtin.c,v
retrieving revision 1.1.1.1.2.53
diff -u -p -r1.1.1.1.2.53 builtin.c
--- src/builtin.c       6 Jan 2007 19:56:11 -0000       1.1.1.1.2.53
+++ src/builtin.c       15 Jan 2007 13:33:48 -0000
@@ -1209,8 +1209,10 @@ include (int argc, token_data **argv, bo
   if (fp == NULL)
     {
       if (!silent)
-       M4ERROR ((warning_status, errno,
-                 "cannot open `%s'", ARG (1)));
+       {
+         M4ERROR ((warning_status, errno, "cannot open `%s'", ARG (1)));
+         retcode = EXIT_FAILURE;
+       }
       return;
     }
 

Index: NEWS
===================================================================
RCS file: /sources/m4/m4/NEWS,v
retrieving revision 1.35
diff -u -p -r1.35 NEWS
--- NEWS        6 Jan 2007 19:56:53 -0000       1.35
+++ NEWS        15 Jan 2007 13:50:34 -0000
@@ -127,6 +127,9 @@ promoted to 2.0.
   - FIXME: This feature can cause core dumps when renaming multiple
   symbols to the same name.
 
+*** New `__traditional__' builtin identifies when the traditional module
+    is loaded instead of the gnu module.
+
 *** The `modules' and `symbols' builtins, introduced in previous betas,
     have been renamed `m4modules' and `m4symbols', in order to minimize
     problems when upgrading from 1.4.x and processing English text.  To
Index: modules/gnu.c
===================================================================
RCS file: /sources/m4/m4/modules/gnu.c,v
retrieving revision 1.70
diff -u -p -r1.70 gnu.c
--- modules/gnu.c       23 Dec 2006 00:02:20 -0000      1.70
+++ modules/gnu.c       15 Jan 2007 13:50:34 -0000
@@ -1,5 +1,5 @@
 /* GNU m4 -- A simple macro processor
-   Copyright (C) 2000, 2004, 2005, 2006 Free Software Foundation, Inc.
+   Copyright (C) 2000, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
 
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
@@ -88,14 +88,18 @@ m4_builtin m4_builtin_table[] =
 /* A table for mapping m4 symbol names to simple expansion text. */
 m4_macro m4_macro_table[] =
 {
-  /* name                      text */
-#ifdef _WIN32
-  { "__windows__",             "" },
+  /* name              text */
+#if UNIX
+  { "__unix__",                "" },
+#elif W32_NATIVE
+  { "__windows__",     "" },
+#elif OS2
+  { "__os2__",         "" },
 #else
-  { "__unix__",                        "" },
+# warning Platform macro not provided
 #endif
-  { "__gnu__",                 "" },
-  { "__m4_version__",          VERSION/**/TIMESTAMP },
+  { "__gnu__",         "" },
+  { "__m4_version__",  VERSION/**/TIMESTAMP },
 
   { NULL, NULL },
 };
Index: modules/load.c
===================================================================
RCS file: /sources/m4/m4/modules/load.c,v
retrieving revision 1.20
diff -u -p -r1.20 load.c
--- modules/load.c      26 Sep 2006 13:19:26 -0000      1.20
+++ modules/load.c      15 Jan 2007 13:50:35 -0000
@@ -1,5 +1,5 @@
 /* GNU m4 -- A simple macro processor
-   Copyright (C) 2000, 2005, 2006 Free Software Foundation, Inc.
+   Copyright (C) 2000, 2005, 2006, 2007 Free Software Foundation, Inc.
 
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
@@ -62,9 +62,9 @@ m4_builtin m4_builtin_table[] =
 /* A table for mapping m4 symbol names to simple expansion text. */
 m4_macro m4_macro_table[] =
 {
-  /* name                      text */
-  { "__modules__",             "" },
-  { NULL, NULL },
+  /* name              text */
+  { "__load__",                "" },
+  { NULL,              NULL },
 };
 
 
Index: modules/mpeval.c
===================================================================
RCS file: /sources/m4/m4/modules/mpeval.c,v
retrieving revision 1.22
diff -u -p -r1.22 mpeval.c
--- modules/mpeval.c    6 Jan 2007 19:56:54 -0000       1.22
+++ modules/mpeval.c    15 Jan 2007 13:50:35 -0000
@@ -119,9 +119,9 @@ m4_builtin m4_builtin_table[] =
 /* A table for mapping m4 symbol names to simple expansion text. */
 m4_macro m4_macro_table[] =
 {
-  /* name                      text */
-  { "__gmp__",                 "" },
-  { 0, 0 },
+  /* name              text */
+  { "__mpeval__",      "" },
+  { NULL,              NULL },
 };
 
 
Index: modules/traditional.c
===================================================================
RCS file: /sources/m4/m4/modules/traditional.c,v
retrieving revision 1.5
diff -u -p -r1.5 traditional.c
--- modules/traditional.c       26 Sep 2006 13:19:26 -0000      1.5
+++ modules/traditional.c       15 Jan 2007 13:50:35 -0000
@@ -1,5 +1,5 @@
 /* GNU m4 -- A simple macro processor
-   Copyright (C) 2000, 2006 Free Software Foundation, Inc.
+   Copyright (C) 2000, 2006, 2007 Free Software Foundation, Inc.
 
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
@@ -28,6 +28,15 @@
 m4_macro m4_macro_table[] =
 {
   /* name              text */
+#if UNIX
   { "unix",            "" },
-  { 0,                 0 },
+#elif W32_NATIVE
+  { "windows",         "" },
+#elif OS2
+  { "os2",             "" },
+#else
+# warning Platform macro not provided
+#endif
+  { "__traditional__", "" },
+  { NULL,              NULL },
 };
Index: tests/builtins.at
===================================================================
RCS file: /sources/m4/m4/tests/builtins.at,v
retrieving revision 1.36
diff -u -p -r1.36 builtins.at
--- tests/builtins.at   13 Jan 2007 13:55:37 -0000      1.36
+++ tests/builtins.at   15 Jan 2007 13:50:35 -0000
@@ -71,6 +71,23 @@ outer:3
 AT_CLEANUP
 
 
+## -------------- ##
+## __m4_version__ ##
+## -------------- ##
+
+AT_SETUP([__m4_@&address@hidden)
+
+AT_DATA([in], [[__m4_version__
+]])
+AT_CHECK_M4([--version], [0], [stdout])
+AT_CHECK([[sed -e 's/.*(GNU M4 \(.*\)) \([^ ]*\).*/\2 \1/;q' < stdout]],
+[0], [stdout])
+mv stdout expout
+AT_CHECK_M4([in], [0], [expout])
+
+AT_CLEANUP
+
+
 ## ----- ##
 ## debug ##
 ## ----- ##
Index: tests/modules.at
===================================================================
RCS file: /sources/m4/m4/tests/modules.at,v
retrieving revision 1.23
diff -u -p -r1.23 modules.at
--- tests/modules.at    3 Oct 2006 12:57:18 -0000       1.23
+++ tests/modules.at    15 Jan 2007 13:50:35 -0000
@@ -1,5 +1,5 @@
 # Hand crafted tests for GNU M4.                               -*- Autotest -*-
-# Copyright (C) 2001, 2006 Free Software Foundation, Inc.
+# Copyright (C) 2001, 2006, 2007 Free Software Foundation, Inc.
 
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -67,6 +67,32 @@ AT_CHECK_M4([-M "$abs_builddir" -R froze
 AT_CLEANUP([frozen.m4f])
 
 
+## ------------------ ##
+## module test macros ##
+## ------------------ ##
+
+AT_SETUP([module test macros])
+AT_CHECK_DYNAMIC_MODULE
+AT_CHECK_GMP
+
+AT_DATA([in], [[load(`mpeval')
+-__load__-__mpeval__-
+unload(`mpeval')
+-__load__-__mpeval__-
+unload(`load')
+-__load__-__mpeval__-
+]])
+
+AT_CHECK_M4([-m load in], [0], [[
+---
+
+--__mpeval__-
+
+-__load__-__mpeval__-
+]])
+
+AT_CLEANUP
+
 
 ## ---------------------------- ##
 ## Exercising the test module.  ##
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.92
diff -u -p -r1.92 m4.texinfo
--- doc/m4.texinfo      13 Jan 2007 13:55:37 -0000      1.92
+++ doc/m4.texinfo      15 Jan 2007 13:50:36 -0000
@@ -396,11 +396,13 @@ engine, since all other implementations 
 limitations.
 
 More recently, in 2004, Paul Eggert released 1.4.1 and 1.4.2 which
-addressed some long standing bugs in the venerable 1.4 release.
-Then in 2005 Gary V. Vaughan collected together the many
-patches to @acronym{GNU} @code{m4} 1.4 that were floating around the net and
+addressed some long standing bugs in the venerable 1.4 release.  Then in
+2005, Gary V. Vaughan collected together the many patches to
address@hidden @code{m4} 1.4 that were floating around the net and
 released 1.4.3 and 1.4.4.  And in 2006, Eric Blake joined the team and
-prepared patches for the release of 1.4.5, 1.4.6, 1.4.7, and 1.4.8.
+prepared patches for the release of 1.4.5, 1.4.6, 1.4.7, and 1.4.8.  The
+1.4.x series remains open for bug fixes, including release 1.4.9 in
+2007.
 
 Meanwhile, development was underway for new features for @code{m4},
 such as dynamic module loading and additional builtins, practically
@@ -629,8 +631,8 @@ issues a warning because it may be withd
 @itemx --prefix-builtins
 Internally modify @emph{all} builtin macro names so they all start with
 the prefix @samp{m4_}.  For example, using this option, one should write
address@hidden instead of @samp{define}, and @samp{m4___file__}
-instead of @samp{__file__}.  This option has no effect if @option{-R}
address@hidden instead of @samp{define}, and @address@hidden
+instead of @address@hidden  This option has no effect if @option{-R}
 is also specified.
 
 @item -Q
@@ -5115,7 +5117,7 @@ position depends on when the module was 
 @end deffn
 
 For example, if @acronym{GNU} @code{m4} is started with the
address@hidden option to load the module @samp{load} and make this
address@hidden load} option to load the module @samp{load} and make this
 builtin available, @code{m4modules} will yield the following:
 
 @comment options: -m load
@@ -5141,14 +5143,17 @@ Once the @code{load} module has successf
 @samp{load} macro is entirely equivalent to the @option{-m} command line
 option.
 
address@hidden ignore
address@hidden The -mmpeval/--unload=mpeval pair allows the testsuite to skip 
this
address@hidden test if mpeval was not configured for usage.
address@hidden options: -m load -m mpeval --unload-module=mpeval
 @example
+$ @kbd{m4 -m load}
 m4modules
 @result{}load,gnu,m4
-load(`mymodule')
+load(`mpeval')
 @result{}
 m4modules
address@hidden,load,gnu,m4
address@hidden,load,gnu,m4
 @end example
 
 @node Unload
@@ -5164,63 +5169,101 @@ running the module's finalization method
 The macro @code{unload} is recognized only with parameters.
 @end deffn
 
address@hidden options: -m mpeval -m load
address@hidden
+$ @kbd{m4 -m mpeval -m load}
+m4modules
address@hidden,mpeval,gnu,m4
+unload(`mpeval')
address@hidden
+m4modules
address@hidden,gnu,m4
address@hidden example
+
 @node Standard Modules
 @section Standard bundled modules
 
 @acronym{GNU} @code{m4} ships with several bundled modules as standard.
-By convention these modules define a text macro that can be tested with
address@hidden when they have loaded.
+By convention, these modules define a text macro that can be tested
+with @code{ifdef} when they are loaded; only the @code{m4} module lacks
+this feature test macro.
 
 @table @code
 @item m4
-Provides all of the builtins defined by System V @code{m4}.  This module
-is always loaded -- @acronym{GNU} @code{m4} would only be a very slow
-version of @samp{cat} without the builtins supplied by this module.
+Provides all of the builtins defined by @acronym{POSIX}.  This module
+is always loaded --- @acronym{GNU} @code{m4} would only be a very slow
+version of @command{cat} without the builtins supplied by this module.
 
 @item gnu
 Provides all of the @acronym{GNU} extensions, as defined by
address@hidden M4 through the 1.4.x release series.  In addition to the
address@hidden text macro, this module also defines either
address@hidden or @samp{__windows__} as appropriate, and the following:
address@hidden M4 through the 1.4.x release series.  It also provides a
+couple of feature test macros:
+
address@hidden {Macro (gnu)} __gnu__
+Expands to the empty string, as an indication that the @samp{gnu}
+module is loaded.
address@hidden deffn
 
 @deffn {Macro (gnu)} __m4_version__
-This macro expand to the release version number of the running GNU
address@hidden executable.
+Expands to a quoted string containing the release version number of the
+running @acronym{GNU} @code{m4} executable.
 @end deffn
 
-This module is always loaded, unless the @option{-G} option is supplied
-at startup.
+This module is always loaded, unless the @option{-G} command line
+option is supplied at startup (@pxref{Limits control, , Invoking m4}).
 
 @item traditional
-This module defines a single text macro for compatibility with System V
address@hidden, and is loaded instead of the @samp{gnu} module if @option{-G}
-is specified.
-
address@hidden {Macro (traditional)} unix
-Expands to the empty string.
+This module provides compatibility with System V @code{m4}, for anything
+not specified by @acronym{POSIX}, and is loaded instead of the
address@hidden module if the @option{-G} command line option is specified.
+
address@hidden {Macro (traditional)} __traditional__
+Expands to the empty string, as an indication that the
address@hidden module is loaded.
 @end deffn
 
 @item load
 This module supplies the builtins required to use modules from within a
-GNU @code{m4} program.  @xref{Modules}, for more details.  The module
-also defines the following macro:
address@hidden @code{m4} program.  @xref{Modules}, for more details.  The
+module also defines the following macro:
 
address@hidden {Macro (load)} __modules__
-Expands to the empty string.
address@hidden {Macro (load)} __load__
+Expands to the empty string, as an indication that the @samp{load}
+module is loaded.
 @end deffn
 
 @item mpeval
 This module provides the implementation for the experimental
address@hidden feature.  If the host machine does not have the GNU gmp
-library, the builtin will generate an error if called.  @xref{Mpeval},
-for more details.  The module also defines the following macro:
-
address@hidden {Macro (mpeval)} __gmp__
-Expands to the empty string.
address@hidden feature.  If the host machine does not have the
address@hidden gmp library, the builtin will generate an error if called.
address@hidden, for more details.  The module also defines the following
+macro:
+
address@hidden {Macro (mpeval)} __mpeval__
+Expands to the empty string, as an indication that the @samp{mpeval}
+module is loaded.
 @end deffn
-
 @end table
 
+Here is an example of using the feature test macros.
+
address@hidden
+$ @kbd{m4}
+__gnu__-__traditional__
address@hidden
+ifdef(`__gnu__', `Extensions are active', `Minimal features')
address@hidden are active
address@hidden example
+
address@hidden options: -G
address@hidden
+$ @kbd{m4 --traditional}
+__gnu__-__traditional__
address@hidden
+ifdef(`__gnu__', `Extensions are active', `Minimal features')
address@hidden features
address@hidden example
+
 @node Text handling
 @chapter Macros for text handling
 
@@ -6111,6 +6154,13 @@ mpeval(`-1 >>> 1')
 There are a few builtin macros in @code{m4} that allow you to run shell
 commands from within @code{m4}.
 
+Note that the definition of a valid shell command is system dependent.
+On UNIX systems, this is the typical @code{/bin/sh}.  But on other
+systems, such as native Windows, the shell has a different syntax of
+commands that it understands.  Some examples in this chapter assume
address@hidden/bin/sh}, and also demonstrate how to quit early with a known
+exit value if this is not the case.
+
 @menu
 * Platform macros::             Determining the platform
 * Syscmd::                      Executing simple commands
@@ -6122,7 +6172,50 @@ commands from within @code{m4}.
 
 @node Platform macros
 @section Determining the platform
address@hidden FIXME - port from branch
+Sometimes it is desirable for an input file to know which platform
address@hidden is running on.  @acronym{GNU} @code{m4} provides several
+macros that are predefined to expand to the empty string; checking for
+their existence will confirm platform details.
+
address@hidden {Optional builtin (gnu)} __os2__
address@hidden {Optional builtin (traditional)} os2
address@hidden {Optional builtin (gnu)} __unix__
address@hidden {Optional builtin (traditional)} unix
address@hidden {Optional builtin (gnu)} __windows__
address@hidden {Optional builtin (traditional)} windows
+Each of these macros is conditionally defined as needed to describe the
+environment of @code{m4}.  If defined, each macro expands to the empty
+string.
address@hidden 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.
+
+On native Windows systems, @acronym{GNU} @code{m4} will define
address@hidden@w{__windows__}} in the @samp{gnu} module, and @code{windows} in
+the @samp{traditional} module.
+
+On OS/2 systems, @acronym{GNU} @code{m4} will define @address@hidden
+in the @samp{gnu} module, and @code{os2} in the @samp{traditional}
+module.
+
+If @acronym{GNU} M4 does not provide a platform macro for your system,
+please report that as a bug.
+
address@hidden
+define(`provided', `0')
address@hidden
+ifdef(`__unix__', `define(`provided', incr(provided))')
address@hidden
+ifdef(`__windows__', `define(`provided', incr(provided))')
address@hidden
+ifdef(`__os2__', `define(`provided', incr(provided))')
address@hidden
+provided
address@hidden
address@hidden example
 
 @node Syscmd
 @section Executing simple commands
@@ -7020,27 +7113,9 @@ However, this appears to be a bug in @ac
 traditional implementations also ignore all whitespace (formfeed,
 carriage return, and vertical tab).  @acronym{GNU} @code{m4} follows
 tradition and ignores all leading unquoted whitespace.
-
address@hidden
address@hidden __gnu__
-GNU @code{m4} without @samp{-G} option will define the macro
address@hidden@w{__gnu__}} to expand to the empty string.
-
address@hidden
address@hidden unix
address@hidden __unix__
-On UNIX systems, GNU @code{m4} without the @option{-G} option will
-define the macro @address@hidden, otherwise the macro @code{unix}.
-Both will expand to the empty string.
-
address@hidden
address@hidden __windows__
-On Windows systems, GNU @code{m4} without the @option{-G} option will
-define the macro @address@hidden, which expands to the empty
-string.
 @end itemize
 
address@hidden  Experiments
address@hidden Experiments
 @section Experimental features in @acronym{GNU} M4
 
 Certain features of GNU @code{m4} are experimental.