[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Changes to m4/doc/m4.texinfo,v
From: |
Eric Blake |
Subject: |
Changes to m4/doc/m4.texinfo,v |
Date: |
Mon, 15 Jan 2007 14:04:28 +0000 |
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
- Changes to m4/doc/m4.texinfo,v, Eric Blake, 2007/01/03
- Changes to m4/doc/m4.texinfo,v, Eric Blake, 2007/01/06
- Changes to m4/doc/m4.texinfo,v, Eric Blake, 2007/01/09
- Changes to m4/doc/m4.texinfo,v, Eric Blake, 2007/01/12
- Changes to m4/doc/m4.texinfo,v, Eric Blake, 2007/01/13
- Changes to m4/doc/m4.texinfo,v,
Eric Blake <=
- Changes to m4/doc/m4.texinfo,v, Eric Blake, 2007/01/23