@setfilename m4.info
@include version.texi
@settitle GNU M4 @value{VERSION} macro processor
+@documentencoding UTF-8
+@set txicodequoteundirected
+@set txicodequotebacktick
@setchapternewpage odd
@finalout
@value{VERSION}), a package containing an implementation of the m4 macro
language.
-Copyright @copyright{} 1989-1994, 2004-2014, 2016 Free Software
-Foundation, Inc.
+Copyright @copyright{} 1989--1994, 2004--2014, 2016--2017, 2020--2021
+Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
macros, and using macros to define other macros, were described by Doug
McIlroy of Bell Labs in ``Macro Instruction Extensions of Compiler
Languages'', @emph{Communications of the ACM} 3, 4 (1960), 214--20,
-@url{http://dx.doi.org/10.1145/367177.367223}.
+@url{https://dl.acm.org/doi/10.1145/367177.367223}.
An important precursor of @code{m4} was GPM; see C. Strachey,
@c The title uses lower case and has no space between "macro" and "generator".
``A general purpose macrogenerator'', @emph{Computer Journal} 8, 3
-(1965), 225--41, @url{http://dx.doi.org/10.1093/comjnl/8.3.225}. GPM is
+(1965), 225--41,
+@url{https://academic.oup.com/comjnl/article/8/3/225/336044}. GPM is
also succinctly described in David Gries's book @emph{Compiler
Construction for Digital Computers}, Wiley (1971). Strachey was a
brilliant programmer: GPM fit into 250 machine instructions!
Kernighan and Ritchie then joined forces to develop the original
@code{m4}, described in ``The M4 Macro Processor'', Bell Laboratories
-(1977), @url{http://wolfram.schneider.org/bsd/7thEdManVol2/m4/m4.pdf}.
+(1977), @url{https://wolfram.schneider.org/bsd/7thEdManVol2/m4/m4.pdf}.
It had only 21 builtin macros.
While @code{GPM} was more @emph{pure}, @code{m4} is meant to deal with
@itemx --hashsize=@var{num}
Make the internal hash table for symbol lookup be @var{num} entries big.
For better performance, the number should be prime, but this is not
-checked. The default is 509 entries. It should not be necessary to
+checked. The default is 65537 entries. It should not be necessary to
increase this value, unless you define an excessive number of macros.
@item -L @var{num}
As a more complicated example, we will contrast an actual code
example from the Gnulib project@footnote{Derived from a patch in
-@uref{http://lists.gnu.org/archive/html/bug-gnulib/@/2007-01/@/msg00389.html},
+@uref{https://lists.gnu.org/archive/html/bug-gnulib/@/2007-01/@/msg00389.html},
and a followup patch in
-@uref{http://lists.gnu.org/archive/html/bug-gnulib/@/2007-02/@/msg00000.html}},
+@uref{https://lists.gnu.org/archive/html/bug-gnulib/@/2007-02/@/msg00000.html}},
showing both a buggy approach and the desired results. The user desires
to output a shell assignment statement that takes its argument and turns
it into a shell variable by converting it to uppercase and prepending a
@result{}Macro foo.
@end example
-The quotation strings can safely contain eight-bit characters.
-@ignore
-@comment Yuck. I know of no clean way to render an 8-bit character in
-@comment both info and dvi. This example uses the `open-guillemot' and
-@comment `close-guillemot' characters of the Latin-1 character set.
+The quotation strings can safely contain non-@sc{ascii} characters.
@example
define(`a', `b')
@result{}
-«a»
-@result{}«b»
-changequote(`«', `»')
+«a»
+@result{}«b»
+changequote(`«', `»')
@result{}
-«a»
+«a»
@result{}a
@end example
-@end ignore
+
If no single character is appropriate, @var{start} and @var{end} can be
of any length. Other implementations cap the delimiter length to five
characters, but GNU has no inherent limit.
@result{}# comment again
@end example
-The comment strings can safely contain eight-bit characters.
-@ignore
-@comment Yuck. I know of no clean way to render an 8-bit character in
-@comment both info and dvi. This example uses the `open-guillemot' and
-@comment `close-guillemot' characters of the Latin-1 character set.
+The comment strings can safely contain non-@sc{ascii} characters.
@example
define(`a', `b')
@result{}
-«a»
-@result{}«b»
-changecom(`«', `»')
+«a»
+@result{}«b»
+changecom(`«', `»')
@result{}
-«a»
-@result{}«a»
+«a»
+@result{}«a»
@end example
-@end ignore
+
If no single character is appropriate, @var{start} and @var{end} can be
of any length. Other implementations cap the delimiter length to five
characters, but GNU has no inherent limit.
@end ifnothtml
@ifhtml
See
-@uref{http://www.gnu.org/@/software/@/emacs/@/manual/@/emacs.html#Regexps,
+@uref{https://www.gnu.org/@/software/@/emacs/@/manual/@/emacs.html#Regexps,
Syntax of Regular Expressions} in the GNU Emacs Manual.
@end ifhtml
Support for ERE, Extended Regular Expressions is not
@ignore
@comment No need to fight 8-bit characters, as it is difficult to get
-@comment rendering right in both info and dvi.
+@comment rendering right in both info and dvi, and examples like this
+@comment do not work correctly with UTF-8 anyway since m4 is byte-oriented.
@example
-translit(`«abc~', `~-»')
+translit(`«abc~', `~-»')
@result{}abc
@end example
@comment systems where /bin/sh does not create its own process group.
@comment And PIPE is unreliable, since people tend to run with it
@comment ignored, with m4 inheriting that choice. That leaves KILL as
-@comment the only signal we can reliably test.
+@comment the only signal we can reliably test, but even that is tricky:
+@comment on Haiku, 'kill -9' actually causes a process to die with
+@comment signal 15 named KILLTHR on that platform.
@example
dnl This test assumes kill is a shell builtin, and that signals are
dnl recognizable.
ifdef(`__unix__', ,
`errprint(` skipping: syscmd does not have unix semantics
')m4exit(`77')')dnl
-syscmd(`kill -9 $$')
+changequote(`[', `]')
+@result{}
+syscmd([/bin/sh -c 'kill -9 $$'; st=$?; test $st = 137 || test $st = 265])
+@result{}
+ifelse(sysval, [0], , [errprint([ skipping: shell does not send signal 9
+])m4exit([77])])dnl
+syscmd([kill -9 $$])
@result{}
sysval
@result{}2304
@result{}
sysval
@result{}0
-esyscmd(`kill -9 $$')
+esyscmd([kill -9 $$])
@result{}
sysval
@result{}2304
modifying what @code{m4} is required to do. The requirements for
@code{m4} are shared between SUSv3 and POSIX, and
can be viewed at
-@uref{http://www.opengroup.org/onlinepubs/@/000095399/@/utilities/@/m4.html}.
+@uref{https://www.opengroup.org/onlinepubs/@/000095399/@/utilities/@/m4.html}.
@menu
* Extensions:: Extensions in GNU M4
@bye
@c Local Variables:
-@c coding: iso-8859-1
+@c coding: utf-8
@c fill-column: 72
@c ispell-local-dictionary: "american"
@c indent-tabs-mode: nil
projects / platform / upstream / m4.git / blobdiff