CVSROOT: /sources/m4
Module name: m4
Changes by: Eric Blake <ericb> 06/07/15 21:35:37
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.25
retrieving revision 1.26
diff -u -b -r1.25 -r1.26
--- doc/m4.texinfo 15 Jul 2006 00:15:01 -0000 1.25
+++ doc/m4.texinfo 15 Jul 2006 21:35:37 -0000 1.26
@@ -1,47 +1,76 @@
-\input texinfo
[EMAIL PROTECTED] %**start of header
+\input texinfo @c -*- texinfo -*-
[EMAIL PROTECTED] ========================================================
[EMAIL PROTECTED] %**start of header
@setfilename m4.info
[EMAIL PROTECTED] GNU macro processor
[EMAIL PROTECTED] GNU M4 macro processor
[EMAIL PROTECTED] odd
[EMAIL PROTECTED]
[EMAIL PROTECTED]
[EMAIL PROTECTED] ifnothtml
@finalout
[EMAIL PROTECTED] %**end of header
@include version.texi
@set beta
[EMAIL PROTECTED] A simple macro for optional variables.
[EMAIL PROTECTED] @tabchar{}
[EMAIL PROTECTED] ----------
[EMAIL PROTECTED] The testsuite expects literal tab output in some examples, but
[EMAIL PROTECTED] literal tabs in texinfo lead to formatting issues.
[EMAIL PROTECTED] tabchar
+@ @c
[EMAIL PROTECTED] macro
+
[EMAIL PROTECTED] @ovar{ARG}
[EMAIL PROTECTED] -------------------
[EMAIL PROTECTED] The ARG is an optional argument. To be used for macro
arguments in
[EMAIL PROTECTED] their documentation.
@macro ovar{varname}
@[EMAIL PROTECTED]@r{]}
@end macro
[EMAIL PROTECTED] Text Processing Tools
[EMAIL PROTECTED]
-* m4: (m4). A powerful macro processor.
[EMAIL PROTECTED] direntry
[EMAIL PROTECTED] @dvar{ARG, DEFAULT}
[EMAIL PROTECTED] -------------------
[EMAIL PROTECTED] The ARG is an optional argument, defaulting to DEFAULT. To
be used
[EMAIL PROTECTED] for macro arguments in their documentation.
[EMAIL PROTECTED] dvar{varname, default}
[EMAIL PROTECTED]@var{\varname\} = @[EMAIL PROTECTED]
[EMAIL PROTECTED] macro
+
[EMAIL PROTECTED] %**end of header
[EMAIL PROTECTED] ========================================================
[EMAIL PROTECTED]
-This file documents GNU @code{m4} @value{VERSION}
[EMAIL PROTECTED]
-Copyright (C) 1989, 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000,
-2001, 2004, 2005, 2006 Free Software Foundation, Inc.
+This manual is for GNU M4 (version @value{VERSION}, @value{UPDATED}),
+a package containing an implementation of the m4 macro language.
+
+Copyright @copyright{} 1989, 1990, 1991, 1992, 1993, 1994, 1998, 1999,
+2000, 2001, 2004, 2005, 2006 Free Software Foundation, Inc.
[EMAIL PROTECTED]
Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1
-or any later version published by the Free Software Foundation;
-with the no Invariant Sections, with no Front-Cover Texts,
-and with no Back-Cover Texts. A copy of the license is included in
-the section entitled "GNU Free Documentation License".
-
[EMAIL PROTECTED]
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries copying permission notice
-identical to this one except for the removal of this paragraph
+under the terms of the @acronym{GNU} Free Documentation License,
+Version 1.2 or any later version published by the Free Software
+Foundation; with no Invariant Sections, with the Front-Cover texts
+being ``A @acronym{GNU} Manual,'' and with the Back-Cover Texts as in
+(a) below. A copy of the license is included in the section entitled
[EMAIL PROTECTED] Free Documentation License.''
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and
+modify this @acronym{GNU} Manual, like @acronym{GNU} software. Copies
+published by the Free Software Foundation raise funds for
[EMAIL PROTECTED] development.''
[EMAIL PROTECTED] quotation
[EMAIL PROTECTED] copying
[EMAIL PROTECTED] ignore
[EMAIL PROTECTED] ifinfo
[EMAIL PROTECTED] GNU programming tools
[EMAIL PROTECTED]
+* M4: (m4). A powerful macro processor.
[EMAIL PROTECTED] direntry
@titlepage
[EMAIL PROTECTED] GNU m4, version @value{VERSION}
[EMAIL PROTECTED] GNU M4, version @value{VERSION}
@subtitle A powerful macro processor
@subtitle Edition @value{EDITION}, @value{UPDATED}
@author by Ren@'e Seindal
@@ -49,24 +78,17 @@
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 1989, 1990, 1991, 1992, 1993, 1994, 1998, 1999,
-2000, 2001, 2004, 2005, 2006 Free Software Foundation, Inc.
-
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1
-or any later version published by the Free Software Foundation;
-with the no Invariant Sections, with no Front-Cover Texts,
-and with no Back-Cover Texts. A copy of the license is included in
-the section entitled "GNU Free Documentation License".
-
[EMAIL PROTECTED]
@end titlepage
[EMAIL PROTECTED]
+
@ifnottex
[EMAIL PROTECTED] Top, Preliminaries, (dir), (dir)
[EMAIL PROTECTED] GNU @code{m4}
[EMAIL PROTECTED] Top
[EMAIL PROTECTED] GNU M4
[EMAIL PROTECTED]
[EMAIL PROTECTED] ifnottex
[EMAIL PROTECTED] @item @[EMAIL PROTECTED] @value{hfillkludge} (UtilD, UtilT,
SrcCD)
[EMAIL PROTECTED]
GNU @code{m4} is an implementation of the traditional UNIX macro
processor. It is mostly SVR4 compatible, although it has some
extensions (for example, handling more than 9 positional parameters
@@ -78,21 +100,20 @@
GNU @code{m4} was originally written by Ren@'e Seindal, with
subsequent changes by Fran@,{c}ois Pinard and other volunteers
on the Internet. All names and email addresses can be found in the
-files @file{AUTHORS} and @file{THANKS} from the GNU @code{m4}
-distribution.
+files @file{AUTHORS} and @file{THANKS} from the GNU M4 distribution.
@ifclear beta
This is release @value{VERSION}. It is now to be considered stable,
-future releases are only meant to fix bugs, increase speed, or improve
-documentation. [EMAIL PROTECTED]
+future releases on this branch are only meant to fix bugs, increase
+speed, or improve documentation.
@end ifclear
@ifset beta
This is BETA release @value{VERSION}. This is a development release,
-and is as such prone to bugs, crashes, unforeseen features, incomplete
[EMAIL PROTECTED] therefore, use at your own peril. In case of
-problems, please do not hesitate to report them (see the README file in
-the distribution).
+and as such, is prone to bugs, crashes, unforeseen features, incomplete
[EMAIL PROTECTED], therefore, use at your own peril. In case of
+problems, please do not hesitate to report them (see the @file{README}
+file in the distribution). @xref{Experiments}.
@end ifset
@menu
@@ -101,7 +122,7 @@
* Macros:: How to invoke macros
* Definitions:: How to define new macros
-* Conditionals:: Conditionals, loops an recursions
+* Conditionals:: Conditionals, loops, and recursions
* Debugging:: How to debug macros and input
@@ -113,17 +134,18 @@
* Text handling:: Macros for text handling
* Arithmetic:: Macros for doing arithmetic
-* UNIX commands:: Macros for running UNIX commands
+* Shell commands:: Macros for running shell commands
* Miscellaneous:: Miscellaneous builtin macros
-* Frozen files:: Fast loading of frozen states
+* Frozen files:: Fast loading of frozen state
* Compatibility:: Compatibility with other versions of m4
* Experiments:: Experimental features in GNU m4
* Answers:: Correct version of some examples
-* Concept index:: Index for many concepts
-* Macro index:: Index for all m4 macros
+* Copying This Manual:: How to make copies of this manual
+* Indices:: Indices of concepts and macros
[EMAIL PROTECTED] --- The Detailed Node Listing ---
[EMAIL PROTECTED]
+ --- The Detailed Node Listing ---
Introduction and preliminaries
@@ -165,7 +187,7 @@
* Symbols:: Getting the defined macro names
-Conditionals, loops and recursion
+Conditionals, loops, and recursion
* Ifdef:: Testing if a macro is defined
* Ifelse:: If-else construct, or multibranch
@@ -209,7 +231,7 @@
Macros for text handling
* Len:: Calculating length of strings
-* Index:: Searching for substrings
+* Index macro:: Searching for substrings
* Regexp:: Searching for regular expressions
* Substr:: Extracting substrings
* Translit:: Translating characters
@@ -219,11 +241,12 @@
Macros for doing arithmetic
* Incr:: Decrement and increment operators
-* Eval:: Evaluating integer or rational expressions
-* Mpeval::
+* Eval:: Evaluating integer expressions
+* Mpeval:: Multiple precision arithmetic
-Running UNIX commands
+Running shell commands
+* Platform macros:: Determining the platform
* Syscmd:: Executing simple commands
* Esyscmd:: Reading the output of commands
* Sysval:: Exit codes
@@ -235,26 +258,39 @@
* M4exit:: Exiting from m4
* Syncoutput:: Turning on and off sync lines
+Fast loading of frozen state
+
+* Using frozen files:: Using frozen files
+* Frozen file format 1:: Frozen file format 1
+* Frozen file format 2:: Frozen file format 2
+
Compatibility with other versions of @code{m4}
* Extensions:: Extensions in GNU m4
-* Other Incompat:: Other incompatibilities
+* Incompatibilities:: Other incompatibilities
+
+Copying This Manual
+
+* GNU Free Documentation License:: License for copying this manual
+
+Indices
+
+* Concept index:: Index for many concepts
+* Macro index:: Index for all m4 macros
@end detailmenu
@end menu
[EMAIL PROTECTED] ifnottex
-
@node Preliminaries
@chapter Introduction and preliminaries
-This first chapter explains what is GNU @code{m4}, where @code{m4}
+This first chapter explains what GNU @code{m4} is, where @code{m4}
comes from, how to read and use this documentation, how to call the
[EMAIL PROTECTED] program and how to report bugs about it. It concludes by
[EMAIL PROTECTED] program, and how to report bugs about it. It concludes by
giving tips for reading the remainder of the manual.
The following chapters then detail all the features of the @code{m4}
-language.
+language, as shipped in the GNU M4 package.
@menu
* Intro:: Introduction to @code{m4}
@@ -271,7 +307,7 @@
input to the output, expanding macros as it goes. Macros are either
builtin or user-defined, and can take any number of arguments.
Besides just doing macro expansion, @code{m4} has builtin functions
-for including named files, running UNIX commands, doing integer
+for including named files, running shell commands, doing integer
arithmetic, manipulating text in various ways, recursion, [EMAIL PROTECTED]
@code{m4} can be used either as a front-end to a compiler, or as a
macro processor in its own right.
@@ -1082,7 +1118,7 @@
@xref{Pushdef, , Temporarily redefining macros}, for an explanation of
@code{pushdef}. Some other UNIX implementations replace all definitions
of a macro with @code{define}.
[EMAIL PROTECTED] Incompat, , Other incompatibilities}, for more details.
[EMAIL PROTECTED], , Other incompatibilities}, for more details.
The first argument to @code{define} does not have to be a simple word.
It can be any text string. A macro with a non standard name cannot be
@@ -1555,7 +1591,7 @@
@end deffn
@node Conditionals
[EMAIL PROTECTED] Conditionals, loops and recursion
[EMAIL PROTECTED] Conditionals, loops, and recursion
Macros, expanding to plain text, perhaps with arguments, are not quite
enough. We would like to have macros expand to different things, based
@@ -1687,7 +1723,7 @@
order of its arguments:
@example
-define(`reverse', `ifelse($#, 0, , $#, 1, ``$1'',
+define(`reverse', `ifelse(`$#', `0', , `$#', `1', ``$1'',
`reverse(shift($@@)), `$1'')')
@result{}
reverse
@@ -1801,10 +1837,10 @@
define(`foo', `Hello world.')
@result{}
dumpdef(`foo')
[EMAIL PROTECTED]: `Hello world.'
[EMAIL PROTECTED]:@tabchar{}`Hello world.'
@result{}
dumpdef(`define')
[EMAIL PROTECTED]: <define>
[EMAIL PROTECTED]:@tabchar{}<define>
@result{}
@end example
@@ -2603,10 +2639,10 @@
@end deffn
@example
-include(`no-such-file')
+include(`none')
@result{}
[EMAIL PROTECTED]: input.m4: 1: Cannot open no-such-file: No such file or
directory
-sinclude(`no-such-file')
[EMAIL PROTECTED]: input.m4: 1: Cannot open none: No such file or directory
+sinclude(`none')
@result{}
@end example
@@ -2892,7 +2928,7 @@
@example
define(`cleardivert',
-`pushdef(`_num', divnum)divert(-1)undivert($@@)divert(_num)popdef(`_num')')
+`pushdef(`_n', divnum)divert(`-1')undivert($@@)divert(_n)popdef(`_n')')
@result{}
@end example
@@ -3136,7 +3172,7 @@
@menu
* Len:: Calculating length of strings
-* Index:: Searching for substrings
+* Index macro:: Searching for substrings
* Regexp:: Searching for regular expressions
* Substr:: Extracting substrings
* Translit:: Translating characters
@@ -3163,7 +3199,7 @@
@result{}6
@end example
[EMAIL PROTECTED] Index
[EMAIL PROTECTED] Index macro
@section Searching for substrings
@deffn {Builtin (m4)} index (@var{string}, @var{substring})
@@ -3230,7 +3266,8 @@
remains unchanged for other invocations:
@example
-regexp(`GNUs not Unix', `\w(\w+)$', `*** \& *** \1 ***', `POSIX_EXTENDED')
+regexp(`GNUs not Unix', `\w(\w+)$', `*** \& *** \1 ***',
+ `POSIX_EXTENDED')
@result{}*** Unix *** nix ***
@end example
@@ -3367,7 +3404,8 @@
define(`upcase', `translit(`$*', `a-z', `A-Z')')dnl
define(`downcase', `translit(`$*', `A-Z', `a-z')')dnl
define(`capitalize1',
- `regexp(`$1', `^\(\w\)\(\w*\)', `upcase(`\1')`'downcase(`\2')')')dnl
+ `regexp(`$1', `^\(\w\)\(\w*\)',
+ `upcase(`\1')`'downcase(`\2')')')dnl
define(`capitalize',
`patsubst(`$1', `\w+', `capitalize1(`\&')')')dnl
capitalize(`GNUs not Unix')
@@ -3424,8 +3462,8 @@
@example
define(`foo', `The brown fox jumped over the lazy dog')
@result{}
-format(`The string "%s" is %d characters long', foo, len(foo))
[EMAIL PROTECTED] string "The brown fox jumped over the lazy dog" is 38
characters long
+format(`The string "%s" uses %d characters', foo, len(foo))
[EMAIL PROTECTED] string "The brown fox jumped over the lazy dog" uses 38
characters
@end example
Using the @code{forloop} macro defined in @xref{Loops}, this
@@ -3466,8 +3504,8 @@
@menu
* Incr:: Decrement and increment operators
-* Eval:: Evaluating integer or rational expressions
-* Mpeval::
+* Eval:: Evaluating integer expressions
+* Mpeval:: Multiple precision arithmetic
@end menu
@node Incr
@@ -3610,7 +3648,6 @@
Take note that @var{radix} cannot be larger than 36.
@node Mpeval
[EMAIL PROTECTED] node-name, next, previous, up
@section Multiple precision arithmetic
When @code{m4} is compiled with a multiple precision arithmetic library
@@ -3631,23 +3668,29 @@
The builtin macro @code{mpeval} is recognized only when given arguments.
@end deffn
[EMAIL PROTECTED] UNIX commands
[EMAIL PROTECTED] Running UNIX commands
[EMAIL PROTECTED] Shell commands
[EMAIL PROTECTED] Running shell commands
[EMAIL PROTECTED] executing UNIX commands
[EMAIL PROTECTED] running UNIX commands
[EMAIL PROTECTED] executing shell commands
[EMAIL PROTECTED] running shell commands
[EMAIL PROTECTED] shell commands, running
@cindex UNIX commands, running
[EMAIL PROTECTED] commands, running UNIX
-There are a few builtin macros in @code{m4} that allow you to run UNIX
[EMAIL PROTECTED] commands, running shell
+There are a few builtin macros in @code{m4} that allow you to run shell
commands from within @code{m4}.
@menu
+* Platform macros:: Determining the platform
* Syscmd:: Executing simple commands
* Esyscmd:: Reading the output of commands
* Sysval:: Exit codes
* Maketemp:: Making names for temporary files
@end menu
[EMAIL PROTECTED] Platform macros
[EMAIL PROTECTED] Determining the platform
[EMAIL PROTECTED] FIXME - port from branch
+
@node Syscmd
@section Executing simple commands
@@ -3685,7 +3728,7 @@
@cindex GNU extensions
@deffn {Builtin (gnu)} esyscmd (@var{shell-command})
-If you want @code{m4} to read the output of a UNIX command, use
+If you want @code{m4} to read the output of a shell command, use
@code{esyscmd}, which expands to the standard output of the shell
command @var{shell-command}.
@@ -3714,9 +3757,10 @@
@node Sysval
@section Exit codes
[EMAIL PROTECTED] exit code from UNIX commands
[EMAIL PROTECTED] exit code from shell commands
[EMAIL PROTECTED] shell commands, exit code from
@cindex UNIX commands, exit code from
[EMAIL PROTECTED] commands, exit code from UNIX
[EMAIL PROTECTED] commands, exit code from shell
@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
@@ -3827,11 +3871,12 @@
@comment status: 1
@example
-define(`fatal_error', `errprint(`m4: '__file__: __line__`: fatal error: $*
+define(`fatal_error',
+ `errprint(`m4:'__file__:__line__`: fatal error: $*
')m4exit(1)')
@result{}
fatal_error(`This is a BAD one, buster')
[EMAIL PROTECTED]: input.m4: 3: fatal error: This is a BAD one, buster
[EMAIL PROTECTED]:input.m4: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
@@ -3860,20 +3905,29 @@
@end deffn
@node Frozen files
[EMAIL PROTECTED] Fast loading of frozen states
[EMAIL PROTECTED] Fast loading of frozen state
[EMAIL PROTECTED] fast loading of frozen files
[EMAIL PROTECTED] frozen files for fast loading
[EMAIL PROTECTED] initialization, frozen states
[EMAIL PROTECTED] dumping into frozen file
[EMAIL PROTECTED] reloading a frozen file
[EMAIL PROTECTED] GNU extensions
Some bigger @code{m4} applications may be built over a common base
containing hundreds of definitions and other costly initializations.
Usually, the common base is kept in one or more declarative files,
which files are listed on each @code{m4} invocation prior to the
user's input file, or else, @code{include}'d from this input file.
[EMAIL PROTECTED]
+* Using frozen files:: Using frozen files
+* Frozen file format 1:: Frozen file format 1
+* Frozen file format 2:: Frozen file format 2
[EMAIL PROTECTED] menu
+
[EMAIL PROTECTED] Using frozen files
[EMAIL PROTECTED] Using frozen files
+
[EMAIL PROTECTED] fast loading of frozen files
[EMAIL PROTECTED] frozen files for fast loading
[EMAIL PROTECTED] initialization, frozen state
[EMAIL PROTECTED] dumping into frozen file
[EMAIL PROTECTED] reloading a frozen file
[EMAIL PROTECTED] GNU extensions
Reading the common base of a big application, over and over again, may
be time consuming. GNU @code{m4} offers some machinery to speed up
the start of an application using lengthy common bases. Presume the
@@ -3966,6 +4020,16 @@
It is looked up the same way as an @code{include} file (@pxref{Search
Path}).
[EMAIL PROTECTED] Frozen file format 1
[EMAIL PROTECTED] Frozen file format 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.
+
[EMAIL PROTECTED] Frozen file format 2
[EMAIL PROTECTED] Frozen file format 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}.
@@ -4050,7 +4114,7 @@
@menu
* Extensions:: Extensions in GNU m4
-* Other Incompat:: Other incompatibilities
+* Incompatibilities:: Other incompatibilities
@end menu
@node Extensions
@@ -4143,7 +4207,7 @@
Also, the debugging and tracing facilities in GNU @code{m4} are much
more extensive than in most other versions of @code{m4}.
[EMAIL PROTECTED] Other Incompat
[EMAIL PROTECTED] Incompatibilities
@section Other incompatibilities
There are a few other incompatibilities between this implementation of
@@ -4260,7 +4324,7 @@
@node Answers
[EMAIL PROTECTED] Answers
[EMAIL PROTECTED] Correct version of some examples
Some of the examples in this manuals are buggy. Correctly working
macros are presented here.
@@ -4280,20 +4344,36 @@
If called without arguments, it will call undivert without argument,
otherwise they will be passed to undivert().
[EMAIL PROTECTED] ==========================================================
Appendices
+
[EMAIL PROTECTED] Copying This Manual
[EMAIL PROTECTED] Copying This Manual
[EMAIL PROTECTED] License
+
[EMAIL PROTECTED]
+* GNU Free Documentation License:: License for copying this manual
[EMAIL PROTECTED] menu
[EMAIL PROTECTED] fdl.texi
[EMAIL PROTECTED] Indices
[EMAIL PROTECTED] Indices
+
[EMAIL PROTECTED]
+* Concept index:: Index for many concepts
+* Macro index:: Index for all m4 macros
[EMAIL PROTECTED] menu
@node Concept index
[EMAIL PROTECTED] Concept index
[EMAIL PROTECTED] Concept index
@printindex cp
@node Macro index
[EMAIL PROTECTED] Macro index
[EMAIL PROTECTED] Macro index
References are exclusively to the places where a builtin is introduced
-the first time. Names starting and ending with @samp{__} have these
-characters removed in the index.
+the first time.
@iftex
@sp 1
@@ -4301,6 +4381,11 @@
@printindex fn
[EMAIL PROTECTED]
[EMAIL PROTECTED]
@bye
+
[EMAIL PROTECTED] Local Variables:
[EMAIL PROTECTED] fill-column: 72
[EMAIL PROTECTED] ispell-local-dictionary: "american"
[EMAIL PROTECTED] indent-tabs-mode: nil
[EMAIL PROTECTED] whitespace-check-buffer-indent: nil
[EMAIL PROTECTED] End:
