Changes to m4/doc/m4.texinfo,v

[Eric Blake]

CVSROOT:        /sources/m4
Module name:    m4
Changes by:     Eric Blake <ericb>      07/01/15 14:04:27

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.92
retrieving revision 1.93
diff -u -b -r1.92 -r1.93
--- doc/m4.texinfo      13 Jan 2007 13:55:37 -0000      1.92
+++ doc/m4.texinfo      15 Jan 2007 14:04:26 -0000      1.93
@@ -396,11 +396,13 @@
 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 @@
 @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 @@
 @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 @@
 @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 @@
 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 @@
 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 @@
 
 @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,24 +7113,6 @@
 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
 
 @node  Experiments