I've been busy documenting quite a few m4sugar macros. Applied:
From: Eric Blake <[EMAIL PROTECTED]>
Date: Thu, 11 Oct 2007 14:17:13 -0600
Subject: [PATCH] Some more m4sugar documentation.
* lib/m4sugar/m4sugar.m4: Clean up macro order.
* doc/autoconf.texi (Programming in M4): Lighten the warning on
using m4sugar; it is stabilizing and useful.
(Redefined M4 Macros): Touch up wording on M4 builtins; sort. Add
m4_divert, m4_undivert, __file__, __line__, __oline__.
(Diagnostics): New node, documenting m4_assert, m4_errprintn,
m4_fatal, m4_location, m4_warn.
(Diversion support): New node, documenting m4_divert_push,
m4_divert_pop, m4_divert_text, m4_divert_once.
(Text processing Macros): Sort. Add m4_flatten, m4_join,
m4_newline, m4_strip, m4_text_box, m4_text_wrap.
(Programming in M4sh, Macro Names): Document namespace
limitations. Mention that non-Automake macros should not begin
with `AM_'.
(Reporting Messages): Mark AC_DIAGNOSE, AC_WARNING, and AC_FATAL
as obsolescent.
(Printing Messages): Change cross-reference.
Signed-off-by: Eric Blake <[EMAIL PROTECTED]>
---
ChangeLog | 16 ++
NEWS | 19 ++-
doc/autoconf.texi | 490 +++++++++++++++++++++++++++++++++++++++---------
lib/m4sugar/m4sugar.m4 | 93 +++++-----
4 files changed, 477 insertions(+), 141 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index af30a9b..fff17d8 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,21 @@
2007-10-12 Eric Blake <[EMAIL PROTECTED]>
+ Some more m4sugar documentation.
+ * lib/m4sugar/m4sugar.m4: Clean up macro order.
+ * doc/autoconf.texi (Programming in M4): Lighten the warning on
+ using m4sugar; it is stabilizing and useful.
+ (Redefined M4 Macros): Touch up wording on M4 builtins; sort. Add
+ m4_divert, m4_undivert, __file__, __line__, __oline__.
+ (Diagnostics): New node, documenting m4_assert, m4_errprintn,
+ m4_fatal, m4_location, m4_warn.
+ (Diversion support): New node, documenting m4_divert_push,
+ m4_divert_pop, m4_divert_text, m4_divert_once.
+ (Text processing Macros): Sort. Add m4_flatten, m4_join,
+ m4_newline, m4_strip, m4_text_box, m4_text_wrap.
+ (Reporting Messages): Mark AC_DIAGNOSE, AC_WARNING, and AC_FATAL
+ as obsolescent.
+ (Printing Messages): Change cross-reference.
+
Document interaction of recent m4_append change with Libtool HEAD.
* lib/m4sugar/m4sugar.m4 (m4_append): Document semantics change.
(m4_append_uniq): Add new parameters, based on lt_append_uniq.
diff --git a/NEWS b/NEWS
index 1e87c4d..00d3019 100644
--- a/NEWS
+++ b/NEWS
@@ -78,16 +78,18 @@ GNU Autoconf NEWS - User visible changes.
- The following macros were previously available as undocumented
interfaces; the macros are now documented as stable interfaces.
- m4_bmatch m4_bpatsubsts m4_case m4_default m4_do m4_ifndef
- m4_ifset m4_ifval m4_ifvaln m4_n m4_shiftn
- m4_version_compare m4_warn
+ __oline__ m4_assert m4_bmatch m4_bpatsubsts m4_case
+ m4_default m4_divert_once m4_divert_pop m4_divert_push
+ m4_divert_text m4_do m4_errprintn m4_fatal m4_flatten
+ m4_ifndef m4_ifset m4_ifval m4_ifvaln m4_location
+ m4_n m4_shiftn m4_strip m4_version_compare m4_warn
- The following macros were previously available as undocumented
interfaces, but had bugs. Packages that relied on the
undocumented and buggy behavior should analyze their code to make
sure it still works with the new documented behavior.
- m4_text_wrap
+ m4_join m4_text_box m4_text_wrap
- Packages using the undocumented m4sugar macro m4_PACKAGE_VERSION
should consider using the new AC_AUTOCONF_VERSION instead.
@@ -144,6 +146,15 @@ GNU Autoconf NEWS - User visible changes.
practical importance on current systems. New programs need not use
AC_C_LONG_DOUBLE. We have no current plans to remove it.
+** AC_DIAGNOSE, AC_WARNING, and AC_FATAL are obsolescent.
+ The documentation now favors the use of M4sugar macros m4_warn and
+ m4_fatal, since the naming makes it more obvious that the
+ diagnostics are associated with M4 expansion (ie. when running
+ `autoconf'), and offers less confusion with the AC_MSG_ERROR,
+ AC_MSG_FAILURE, and AC_MSG_WARN macros which manage diagnostics
+ when running `configure'. We have no current plans to remove these
+ macros.
+
* Major changes in Autoconf 2.61a (2006-12-11)
** AC_FUNC_FSEEKO was broken in 2.61; it didn't make fseeko and ftello visible
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 239e56f..4a10316 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -449,6 +449,8 @@ Using @command{autom4te}
Programming in M4sugar
* Redefined M4 Macros:: M4 builtins changed in M4sugar
+* Diagnostic Macros:: Diagnostic messages from M4sugar
+* Diversion support:: Diversions in M4sugar
* Conditional constructs:: Conditions in M4
* Looping constructs:: Iteration in M4
* Evaluation Macros:: More quotation and evaluation control
@@ -8998,7 +9000,7 @@ only be made to the macro definitions and all the callers
change
automatically.
To diagnose static issues, i.e., when @command{autoconf} is run, see
[EMAIL PROTECTED] Messages}.
[EMAIL PROTECTED] Macros}.
@defmac AC_MSG_CHECKING (@var{feature-description})
@acindex{MSG_CHECKING}
@@ -9087,9 +9089,9 @@ Autoconf is written on top of two layers: @dfn{M4sugar},
which provides
convenient macros for pure M4 programming, and @dfn{M4sh}, which
provides macros dedicated to shell script generation.
-As of this version of Autoconf, these two layers are still experimental,
-and their interface might change in the future. As a matter of fact,
[EMAIL PROTECTED] that is not documented must not be used}.
+As of this version of Autoconf, these two layers still contain
+experimental macros, whose interface might change in the future. As a
+matter of fact, @emph{anything that is not documented must not be used}.
@menu
* M4 Quotation:: Protecting macros from unwanted expansion
@@ -10079,6 +10081,8 @@ define your own macros into these namespaces.
@menu
* Redefined M4 Macros:: M4 builtins changed in M4sugar
+* Diagnostic Macros:: Diagnostic messages from M4sugar
+* Diversion support:: Diversions in M4sugar
* Conditional constructs:: Conditions in M4
* Looping constructs:: Iteration in M4
* Evaluation Macros:: More quotation and evaluation control
@@ -10115,27 +10119,98 @@ define your own macros into these namespaces.
@msindex{traceoff}
@msindex{traceon}
@msindex{translit}
[EMAIL PROTECTED]
With a few exceptions, all the M4 native macros are moved in the
@samp{m4_} pseudo-namespace, e.g., M4sugar renames @code{define} as
@code{m4_define} etc.
+The list of macros unchanged from M4, except for their name, is:
[EMAIL PROTECTED] @minus
[EMAIL PROTECTED] m4_builtin
[EMAIL PROTECTED] m4_changecom
[EMAIL PROTECTED] m4_changequote
[EMAIL PROTECTED] m4_debugfile
[EMAIL PROTECTED] m4_debugmode
[EMAIL PROTECTED] m4_decr
[EMAIL PROTECTED] m4_define
[EMAIL PROTECTED] m4_divnum
[EMAIL PROTECTED] m4_dumpdef
[EMAIL PROTECTED] m4_errprint
[EMAIL PROTECTED] m4_esyscmd
[EMAIL PROTECTED] m4_eval
[EMAIL PROTECTED] m4_format
[EMAIL PROTECTED] m4_ifdef
[EMAIL PROTECTED] m4_incr
[EMAIL PROTECTED] m4_index
[EMAIL PROTECTED] m4_indir
[EMAIL PROTECTED] m4_len
[EMAIL PROTECTED] m4_pushdef
[EMAIL PROTECTED] m4_shift
[EMAIL PROTECTED] m4_substr
[EMAIL PROTECTED] m4_syscmd
[EMAIL PROTECTED] m4_sysval
[EMAIL PROTECTED] m4_traceoff
[EMAIL PROTECTED] m4_traceon
[EMAIL PROTECTED] m4_translit
[EMAIL PROTECTED] itemize
+
Some M4 macros are redefined, and are slightly incompatible with their
native equivalent.
[EMAIL PROTECTED] __file__
[EMAIL PROTECTED] __line__
[EMAIL PROTECTED] __file__
[EMAIL PROTECTED] __line__
+All M4 macros starting with @samp{__} retain their original name: for
+example, no @code{m4__file__} is defined.
[EMAIL PROTECTED] defmac
+
[EMAIL PROTECTED] __oline__
[EMAIL PROTECTED] __oline__
+This is not technically a macro, but a feature of Autom4te. The
+sequence @code{__oline__} can be used similarly to the other m4sugar
+location macros, but rather than expanding to the location of the input
+file, it is translated to the line number where it appears in the output
+file after all other M4 expansions.
[EMAIL PROTECTED] defmac
+
@defmac dnl
[EMAIL PROTECTED]
[EMAIL PROTECTED] dnl
This macro kept its original name: no @code{m4_dnl} is defined.
@end defmac
[EMAIL PROTECTED] m4_bpatsubst (@var{string}, @var{regexp}, @ovar{replacement})
[EMAIL PROTECTED]
+This macro corresponds to @code{patsubst}. The name @code{m4_patsubst}
+is kept for future versions of M4sugar, once @acronym{GNU} M4 2.0 is
+released and supports extended regular expression syntax.
[EMAIL PROTECTED] defmac
+
[EMAIL PROTECTED] m4_bregexp (@var{string}, @var{regexp}, @ovar{replacement})
[EMAIL PROTECTED]
+This macro corresponds to @code{regexp}. The name @code{m4_regexp}
+is kept for future versions of M4sugar, once @acronym{GNU} M4 2.0 is
+released and supports extended regular expression syntax.
[EMAIL PROTECTED] defmac
+
@defmac m4_defn (@var{macro})
@msindex{defn}
Unlike the M4 builtin, this macro fails if @var{macro} is not
-defined. See @code{m4_undefine}.
+defined. Also, while newer M4 can concatenate multiple definitions,
+this version currently only supports a single @var{macro}. See
[EMAIL PROTECTED]
@end defmac
[EMAIL PROTECTED] FIXME: Need to document m4_divert, m4_undivert,
m4_divert_push,
[EMAIL PROTECTED] m4_divert_pop, m4_divert_text, m4_divert_once
[EMAIL PROTECTED] m4_divert (@var{diversion})
[EMAIL PROTECTED]
+M4sugar relies heavily on diversions, so rather than behaving as a
+primitive, @code{m4_divert} behaves like:
[EMAIL PROTECTED]
+m4_divert_pop()m4_divert_push([EMAIL PROTECTED])
[EMAIL PROTECTED] example
[EMAIL PROTECTED]
[EMAIL PROTECTED] support}, for more details about the use of the
+diversion stack.
[EMAIL PROTECTED] defmac
@defmac m4_exit (@var{exit-status})
@msindex{exit}
@@ -10174,30 +10249,19 @@ and both have the secure semantics regardless of
which macro the
underlying M4 provides.
@end defmac
[EMAIL PROTECTED] m4_bpatsubst (@var{string}, @var{regexp}, @ovar{replacement})
[EMAIL PROTECTED]
-This macro corresponds to @code{patsubst}. The name @code{m4_patsubst}
-is kept for future versions of M4sugar, once @acronym{GNU} M4 2.0 is
-released and supports extended regular expression syntax.
[EMAIL PROTECTED] defmac
-
@defmac m4_popdef (@var{macro})
@msindex{popdef}
Unlike the M4 builtin, this macro fails if @var{macro} is not
-defined. See @code{m4_undefine}.
[EMAIL PROTECTED] defmac
-
[EMAIL PROTECTED] m4_bregexp (@var{string}, @var{regexp}, @ovar{replacement})
[EMAIL PROTECTED]
-This macro corresponds to @code{regexp}. The name @code{m4_regexp}
-is kept for future versions of M4sugar, once @acronym{GNU} M4 2.0 is
-released and supports extended regular expression syntax.
+defined. Also, while newer M4 can pop multiple definitions at once,
+this version currently only supports a single @var{macro}. See
[EMAIL PROTECTED]
@end defmac
@defmac m4_undefine (@var{macro})
@msindex{undefine}
Unlike the M4 builtin, this macro fails if @var{macro} is not
-defined. Use
+defined. Also, while newer M4 can undefine multiple definitions at
+once, this version currently only supports a single @var{macro}. Use
@example
m4_ifdef([EMAIL PROTECTED], [m4_undefine([EMAIL PROTECTED])])
@@ -10207,6 +10271,15 @@ m4_ifdef([EMAIL PROTECTED], [m4_undefine([EMAIL
PROTECTED])])
to recover the behavior of the builtin.
@end defmac
[EMAIL PROTECTED] m4_undivert (@var{diversion})
[EMAIL PROTECTED]
+Unlike the M4 builtin, only one diversion can be undiverted per
+invocation. Also, since the M4sugar diversion stack prefers named
+diversions, the use of @code{m4_undivert} to include files is risky.
[EMAIL PROTECTED] support}, for more details about the use of the
+diversion stack.
[EMAIL PROTECTED] defmac
+
@defmac m4_wrap (@var{text})
@msindex{wrap}
This macro corresponds to @code{m4wrap}.
@@ -10234,14 +10307,160 @@ m4_wrap([foo])
@end defmac
[EMAIL PROTECTED] Diagnostic Macros
[EMAIL PROTECTED] Diagnostic messages from M4sugar
[EMAIL PROTECTED] Messages, from @command{M4sugar}
+
+When macros statically diagnose abnormal situations, benign or fatal,
+they should report them using these macros. For issuing dynamic issues,
+i.e., when @command{configure} is run, see @ref{Printing Messages}.
+
[EMAIL PROTECTED] m4_assert (@var{expression}, @dvar{exit-status, 1})
[EMAIL PROTECTED]
+Assert that the arithmetic @var{expression} evaluates to non-zero.
+Otherwise, issue a fatal error, and exit @command{autom4te} with
[EMAIL PROTECTED]
[EMAIL PROTECTED] defmac
+
[EMAIL PROTECTED] m4_errprintn (@var{message})
[EMAIL PROTECTED]
+Similar to the builtin @code{m4_errprint}, except that a newline is
+guaranteed after @var{message}.
[EMAIL PROTECTED] defmac
+
[EMAIL PROTECTED]
[EMAIL PROTECTED] m4_fatal
[EMAIL PROTECTED]
+Report a severe error @var{message} prefixed with the current location,
+and have @command{autom4te} die.
[EMAIL PROTECTED] defmac
+
[EMAIL PROTECTED] m4_location
[EMAIL PROTECTED]
+Useful as a prefix in a message line. Short for:
[EMAIL PROTECTED]
+__file__:__line__
[EMAIL PROTECTED] example
[EMAIL PROTECTED] defmac
+
[EMAIL PROTECTED]
[EMAIL PROTECTED] m4_warn (@var{category}, @var{message})
[EMAIL PROTECTED]
+Report @var{message} as a warning (or as an error if requested by the
+user) if warnings of the @var{category} are turned on. If the message
+is emitted, it is prefixed with the current location, and followed by a
+call trace of all macros defined via @code{AC_DEFUN} used to get to the
+current expansion. You are encouraged to use standard categories, which
+currently include:
+
[EMAIL PROTECTED] @samp
[EMAIL PROTECTED] all
+messages that don't fall into one of the following categories. Use of an
+empty @var{category} is equivalent.
+
[EMAIL PROTECTED] cross
+related to cross compilation issues.
+
[EMAIL PROTECTED] obsolete
+use of an obsolete construct.
+
[EMAIL PROTECTED] syntax
+dubious syntactic constructs, incorrectly ordered macro calls.
[EMAIL PROTECTED] table
[EMAIL PROTECTED] defmac
+
+
[EMAIL PROTECTED] Diversion support
[EMAIL PROTECTED] Diversion support
+
+M4sugar makes heavy use of diversions, because it is often the case that
+text that must appear early in the output is not discovered until late
+in the input. Additionally, some of the topological sorting algorithms
+used in resolving macro dependencies use diversions. Therefore, most
+macros should not need to change diversions directly, but rather rely on
+higher-level M4sugar macros to manage diversions transparently.
+
+To make diversion management easier, M4sugar uses the concept of named
+diversions. Rather than using diversion numbers directly, it is nicer
+to associate a name with each diversion; the diversion number associated
+with a particular diversion name is an implementation detail, so you
+should only use diversion names.
+
+M4sugar defines two named diversions.
[EMAIL PROTECTED] @code
[EMAIL PROTECTED] KILL
+Text written to this diversion is discarded. This is the default
+diversion once M4sugar is initialized.
[EMAIL PROTECTED] GROW
+This diversion is used behind the scenes by topological sorting macros,
+such as @code{AC_REQUIRE}.
[EMAIL PROTECTED] table
+
+M4sh adds several more named diversions.
[EMAIL PROTECTED] @code
[EMAIL PROTECTED] BINSH
+This diversion is reserved for the @samp{#!} interpreter line.
[EMAIL PROTECTED] HEADER-REVISION
+This diversion holds text from @code{AC_REVISION}.
[EMAIL PROTECTED] HEADER-COMMENT
+This diversion holds comments about the purpose of a file.
[EMAIL PROTECTED] HEADER-COPYRIGHT
+This diversion is managed by @code{AC_COPYRIGHT}.
[EMAIL PROTECTED] M4SH-SANITIZE
+This diversion contains M4sh sanitization code, used to ensure M4sh is
+executing in a reasonable shell environment.
[EMAIL PROTECTED] M4SH-INIT
+This diversion contains M4sh initialization code, initializing variables
+that are required by other M4sh macros.
[EMAIL PROTECTED] BODY
+This diversion contains the body of the shell code, and is the default
+diversion once M4sh is initialized.
[EMAIL PROTECTED] table
+
+For now, the named diversions of Autoconf, Autoheader, and Autotest are
+not documented.
+
[EMAIL PROTECTED] m4_divert_once (@var{diversion}, @ovar{content})
[EMAIL PROTECTED]
+Similar to @code{m4_divert_text}, except that @var{content} is only
+output to @var{diversion} if this is the first time that
[EMAIL PROTECTED] has been called with its particular arguments.
[EMAIL PROTECTED] defmac
+
[EMAIL PROTECTED] m4_divert_pop (@ovar{diversion})
[EMAIL PROTECTED]
+If provided, check that the current diversion is indeed @var{diversion}.
+Then change to the diversion located earlier on the stack, giving an
+error if an attempt is made to pop beyond the initial m4sugar diversion
+of @code{KILL}.
[EMAIL PROTECTED] defmac
+
[EMAIL PROTECTED] m4_divert_push (@var{diversion})
[EMAIL PROTECTED]
+Remember the former diversion on the diversion stack, and output
+subsequent text into @var{diversion}. M4sugar maintains a diversion
+stack, and issues an error if there is not a matching pop for every
+push.
[EMAIL PROTECTED] defmac
+
[EMAIL PROTECTED] m4_divert_text (@var{diversion}, @ovar{content})
[EMAIL PROTECTED]
+Output @var{content} and a newline into @var{diversion}, without
+affecting the current diversion. Shorthand for:
[EMAIL PROTECTED]
+m4_divert_push([EMAIL PROTECTED])@var{content}
+m4_divert_pop([EMAIL PROTECTED])dnl
[EMAIL PROTECTED] example
[EMAIL PROTECTED] defmac
+
@node Conditional constructs
@subsection Conditional constructs
The following macros provide additional conditional contructs, as
convenience wrappers around @code{m4_if}.
[EMAIL PROTECTED] m4_bmatch (@var{string}, @var{regex-1}, @var{value-1},
@dots{}, @
- @ovar{default})
[EMAIL PROTECTED] m4_bmatch (@var{string}, @var{regex-1}, @var{value-1}, @
+ @ovar{regex-2}, @ovar{value-2}, @dots{}, @ovar{default})
@msindex{bmatch}
The string @var{string} is repeatedly compared against a series of
@var{regex} arguments; if a match is found, the expansion is the
@@ -10250,7 +10469,8 @@ corresponding @var{value}, otherwise, the macro moves
on to the next
@var{default}, or nothing.
@end defmac
[EMAIL PROTECTED] m4_bpatsubsts (@var{string}, @var{regex-1}, @var{subst-1},
@dots{})
[EMAIL PROTECTED] m4_bpatsubsts (@var{string}, @var{regex-1}, @var{subst-1}, @
+ @ovar{regex-2}, @ovar{subst-2}, @dots{})
@msindex{bpatsubsts}
The string @var{string} is altered by @var{regex-1} and @var{subst-1},
as if by:
@@ -10269,8 +10489,8 @@ will line up with the extra quotations, and not the
characters of the
original string.
@end defmac
[EMAIL PROTECTED] m4_case (@var{string}, @var{value-1}, @var{if-value-1},
@dots{}, @
- @ovar{default})
[EMAIL PROTECTED] m4_case (@var{string}, @var{value-1}, @var{if-value-1}, @
+ @ovar{value-2}, @ovar{if-value-2}, @dots{}, @ovar{default})
@msindex{case}
Test @var{string} against multiple @var{value} possibilities, resulting
in the first @var{if-value} for a match, or in the optional
@@ -10283,13 +10503,14 @@ m4_if([EMAIL PROTECTED], [EMAIL PROTECTED], [EMAIL
PROTECTED]
1}],
@end defmac
@defmac m4_cond (@var{test-1}, @var{value-1}, @var{if-value-1}, @
- @var{test-2}, @var{value-2}, @var{if-value-2}, @dots{}, @ovar{default})
+ @ovar{test-2}, @ovar{value-2}, @ovar{if-value-2}, @dots{}, @ovar{default})
@msindex{cond}
-Similar to @code{m4_if}, except that each @var{test} is expanded only
-when it is encountered. This is useful for short-circuiting expensive
-tests; while @code{m4_if} requires all its strings to be expanded up
-front before doing comparisons, @code{m4_cond} only expands a @var{test}
-when all earlier tests have failed.
+This macro was introduced in Autoconf 2.62. Similar to @code{m4_if},
+except that each @var{test} is expanded only when it is encountered.
+This is useful for short-circuiting expensive tests; while @code{m4_if}
+requires all its strings to be expanded up front before doing
+comparisons, @code{m4_cond} only expands a @var{test} when all earlier
+tests have failed.
For an example, these two sequences give the same result, but in the
case where @samp{$1} does not contain a backslash, the @code{m4_cond}
@@ -10419,8 +10640,8 @@ fewer @code{dnl} to result in the same expansion.
@code{m4_shiftn} performs @var{count} iterations of @code{m4_shift},
along with validation that enough arguments were passed in to match the
shift count. @code{m4_shift2} and @code{m4_shift3} are specializations
-of @code{m4_shiftn} that are more efficient for two and three shifts,
-respectively.
+of @code{m4_shiftn}, introduced in Autoconf 2.62, and are more efficient
+for two and three shifts, respectively.
@end defmac
@@ -10473,42 +10694,12 @@ mkargs
@end example
-
@node Text processing Macros
@subsection Text processing Macros
The following macros may be used to manipulate strings in M4.
They are not intended for casual use.
[EMAIL PROTECTED] m4_re_escape (@var{string})
[EMAIL PROTECTED]
-Backslash-escape all characters in @var{string} that are active in
-regexps.
[EMAIL PROTECTED] defmac
-
[EMAIL PROTECTED] m4_tolower (@var{string})
[EMAIL PROTECTED] m4_toupper (@var{string})
[EMAIL PROTECTED]
[EMAIL PROTECTED]
-Return @var{string} with letters converted to upper or lower case,
-respectively.
[EMAIL PROTECTED] defmac
-
[EMAIL PROTECTED] m4_split (@var{string}, @ovar{regexp})
[EMAIL PROTECTED]
-Split @var{string} into an M4 list of elements quoted by @samp{[} and
[EMAIL PROTECTED], while keeping white space at the beginning and at the end.
-If @var{regexp} is given, use it instead of @samp{[\t ]+} for splitting.
-If @var{string} is empty, the result is an empty list.
[EMAIL PROTECTED] defmac
-
[EMAIL PROTECTED] m4_normalize (@var{string})
[EMAIL PROTECTED]
-Remove leading and trailing spaces and tabs, sequences of
-backslash-then-newline, and replace multiple spaces and tabs with a
-single space.
[EMAIL PROTECTED] defmac
-
@defmac m4_append (@var{macro-name}, @var{string}, @ovar{separator})
@defmacx m4_append_uniq (@var{macro-name}, @var{string}, @ovar{separator} @
@ovar{if-uniq}, @ovar{if-duplicate})
@@ -10558,12 +10749,112 @@ list2
m4_dquote(list2)
@result{}[one, two, three]
@end example
+
[EMAIL PROTECTED] m4_flatten (@var{string})
[EMAIL PROTECTED]
+Flatten @var{string} into a single line. Delete all backslash-newline
+pairs, and replace all remaining newlines with a space. The result is
+still a quoted string.
[EMAIL PROTECTED] defmac
+
[EMAIL PROTECTED] m4_join (@ovar{separator}, @[EMAIL PROTECTED])
[EMAIL PROTECTED]
+Concatenate each @var{arg}, separated by @var{separator}. The result is
+a quoted string.
[EMAIL PROTECTED] defmac
+
[EMAIL PROTECTED] m4_newline
[EMAIL PROTECTED]
+This macro was introduced in Autoconf 2.62, and expands to a newline.
+It is primarily useful for maintaining macro formatting, and ensuring
+that M4 does not discard leading whitespace during argument collection.
[EMAIL PROTECTED] defmac
+
[EMAIL PROTECTED] m4_normalize (@var{string})
[EMAIL PROTECTED]
+Remove leading and trailing spaces and tabs, sequences of
+backslash-then-newline, and replace multiple spaces, tabs, and newlines
+with a single space. This is a combination of @code{m4_flatten} and
[EMAIL PROTECTED]
[EMAIL PROTECTED] defmac
+
[EMAIL PROTECTED] m4_re_escape (@var{string})
[EMAIL PROTECTED]
+Backslash-escape all characters in @var{string} that are active in
+regexps.
[EMAIL PROTECTED] defmac
+
[EMAIL PROTECTED] m4_split (@var{string}, @dvar{regexp, [\t ]+})
[EMAIL PROTECTED]
+Split @var{string} into an M4 list of elements quoted by @samp{[} and
[EMAIL PROTECTED], while keeping white space at the beginning and at the end.
+If @var{regexp} is given, use it instead of @samp{[\t ]+} for splitting.
+If @var{string} is empty, the result is an empty list.
[EMAIL PROTECTED] defmac
+
[EMAIL PROTECTED] m4_strip (@var{string})
[EMAIL PROTECTED]
+Strip whitespace from @var{string}. Sequences of space and tab are
+reduced to a single space, then leading and trailing spaces are
+removed. The result is still a quoted string.
[EMAIL PROTECTED] defmac
+
[EMAIL PROTECTED] m4_text_box (@var{message}, @dvar{frame, -})
[EMAIL PROTECTED]
+Add a text box around @var{message}, using @var{frame} as the border
+character above and below the message. The frame correctly accounts for
+the subsequent expansion of @var{message}. For example:
[EMAIL PROTECTED]
+m4_define([macro], [abc])dnl
+m4_text_box([macro])
[EMAIL PROTECTED] --- ##
[EMAIL PROTECTED] abc ##
[EMAIL PROTECTED] --- ##
[EMAIL PROTECTED] example
[EMAIL PROTECTED] defmac
+
[EMAIL PROTECTED] m4_text_wrap (@var{string}, @ovar{prefix}, @
+ @dvar{prefix1, @var{prefix}}, @dvar{width, 79})
[EMAIL PROTECTED]
+Break @var{string} into a series of whitespace-separated words, then
+format those words to wrap within @var{width} columns, and without
+trailing whitespace. If given, @var{prefix1} is prepended to the first
+line, and @var{prefix} is prepended to each continuation line. As a
+special case, if @var{prefix1} is longer than @var{prefix}, the first
+line will consist solely of @var{prefix1}.
+
+For some examples:
[EMAIL PROTECTED]
+m4_text_wrap([Short string */], [@ @ @ ], [/* ], [20])
[EMAIL PROTECTED]/* Short string */
+m4_text_wrap([Much longer string */], [@ @ @ ], [/* ], [20])
[EMAIL PROTECTED]/* Much longer
[EMAIL PROTECTED]@ @ @ string */
+m4_text_wrap([Short doc.], [@ @ @ @ @ @ @ @ @ @ ], [@ @ --short ], [30])
[EMAIL PROTECTED]@ @ --short Short doc.
+m4_text_wrap([Short doc.], [@ @ @ @ @ @ @ @ @ @ ], [@ @ --too-wide ], [30])
[EMAIL PROTECTED]@ @ --too-wide
[EMAIL PROTECTED]@ @ @ @ @ @ @ @ @ @ Short doc.
+m4_text_wrap([Super long documentation.], [@ @ @ @ @ ],
+ [@ @ --too-wide ], 30)
[EMAIL PROTECTED]@ @ --too-wide
[EMAIL PROTECTED]@ @ @ @ @ Super long
[EMAIL PROTECTED]@ @ @ @ @ documentation.
[EMAIL PROTECTED] example
[EMAIL PROTECTED] defmac
+
[EMAIL PROTECTED] m4_tolower (@var{string})
[EMAIL PROTECTED] m4_toupper (@var{string})
[EMAIL PROTECTED]
[EMAIL PROTECTED]
+Return @var{string} with letters converted to upper or lower case,
+respectively.
@end defmac
@anchor{m4_version_compare}
@defmac m4_version_compare (@var{version-1}, @var{version-2})
@msindex{version_compare}
-Introduced in autoconf 2.53. Compare the version strings
+This macro was introduced in Autoconf 2.53. Compare the version strings
@var{version-1} and @var{version-2}, and expand to @samp{-1} if
@var{version-1} is smaller, @samp{0} if they are the same, or @samp{1}
@var{version-2} is smaller. Version strings must be a list of elements
@@ -10583,6 +10874,8 @@ m4_version_compare([1.2], [1.1.1a])
@result{}1
m4_version_compare([1.0], [1])
@result{}0
+m4_version_compare([1.1a], [1,10])
[EMAIL PROTECTED]
@end example
@end defmac
@@ -10992,46 +11285,57 @@ macro does. For example, @code{AC_PATH_X} has
internal macros
@section Reporting Messages
@cindex Messages, from @command{autoconf}
-When macros statically diagnose abnormal situations, benign or fatal,
-they should report them using these macros. For dynamic issues, i.e.,
-when @command{configure} is run, see @ref{Printing Messages}.
+When macros statically diagnose abnormal situations, benign or fatal, it
+is possible to make @command{autoconf} detect the problem, and refuse to
+create @file{configure} in the case of an error. The macros in this
+section are considered obsolescent, and new code should use M4sugar
+macros for this purpose, see @ref{Diagnostic Macros}.
+
+On the other hand, it is possible to want to detect errors when
[EMAIL PROTECTED] is run, which are dependent on the environment of
+the user rather than the maintainer. For dynamic diagnostics, see
[EMAIL PROTECTED] Messages}.
@defmac AC_DIAGNOSE (@var{category}, @var{message})
@acindex{DIAGNOSE}
Report @var{message} as a warning (or as an error if requested by the
-user) if warnings of the @var{category} are turned on. You are
-encouraged to use standard categories, which currently include:
-
[EMAIL PROTECTED] @samp
[EMAIL PROTECTED] all
-messages that don't fall into one of the following categories. Use of an
-empty @var{category} is equivalent.
-
[EMAIL PROTECTED] cross
-related to cross compilation issues.
-
[EMAIL PROTECTED] obsolete
-use of an obsolete construct.
-
[EMAIL PROTECTED] syntax
-dubious syntactic constructs, incorrectly ordered macro calls.
[EMAIL PROTECTED] table
+user) if warnings of the @var{category} are turned on. This macro is
+obsolescent; you are encouraged to use:
[EMAIL PROTECTED]
+m4_warn([EMAIL PROTECTED], [EMAIL PROTECTED])
[EMAIL PROTECTED] example
[EMAIL PROTECTED]
+instead. @xref{m4_warn}, for more details, including valid
[EMAIL PROTECTED] names.
@end defmac
@defmac AC_WARNING (@var{message})
@acindex{WARNING}
-Equivalent to @samp{AC_DIAGNOSE([syntax], @var{message})}, but you are
-strongly encouraged to use a finer grained category.
+Report @var{message} as a syntax warning. This macro is obsolescent;
+you are encouraged to use:
[EMAIL PROTECTED]
+m4_warn([syntax], [EMAIL PROTECTED])
[EMAIL PROTECTED] example
[EMAIL PROTECTED]
+instead. @xref{m4_warn}, for more details, as well as better
+finer-grained categories of warnings (not all problems have to do with
+syntax).
@end defmac
@defmac AC_FATAL (@var{message})
@acindex{FATAL}
Report a severe error @var{message}, and have @command{autoconf} die.
+This macro is obsolescent; you are encouraged to use:
[EMAIL PROTECTED]
+m4_fatal([EMAIL PROTECTED])
[EMAIL PROTECTED] example
[EMAIL PROTECTED]
+instead. @xref{m4_fatal}, for more details.
@end defmac
When the user runs @samp{autoconf -W error}, warnings from
[EMAIL PROTECTED] and @code{AC_WARNING} are reported as error, see
[EMAIL PROTECTED] Invocation}.
[EMAIL PROTECTED] (and thus @code{AC_DIAGNOSE} and @code{AC_WARNING}) are
+reported as errors, see @ref{autoconf Invocation}.
@node Dependencies Between Macros
@section Dependencies Between Macros
diff --git a/lib/m4sugar/m4sugar.m4 b/lib/m4sugar/m4sugar.m4
index 9904bb1..677695b 100644
--- a/lib/m4sugar/m4sugar.m4
+++ b/lib/m4sugar/m4sugar.m4
@@ -574,34 +574,6 @@ m4_define([m4_popdef],
[m4_builtin([popdef], [$1])])
-# m4_quote(ARGS)
-# --------------
-# Return ARGS as a single argument. Any whitespace after unquoted commas
-# is stripped.
-#
-# It is important to realize the difference between `m4_quote(exp)' and
-# `[exp]': in the first case you obtain the quoted *result* of the
-# expansion of EXP, while in the latter you just obtain the string
-# `exp'.
-m4_define([m4_quote], [[$*]])
-
-
-# m4_dquote(ARGS)
-# ---------------
-# Return ARGS as a quoted list of quoted arguments.
-m4_define([m4_dquote], [EMAIL PROTECTED])
-
-
-# m4_noquote(STRING)
-# ------------------
-# Return the result of ignoring all quotes in STRING and invoking the
-# macros it contains. Amongst other things, this is useful for enabling
-# macro invocations inside strings with [] blocks (for instance regexps
-# and help-strings).
-m4_define([m4_noquote],
-[m4_changequote(-=<{,}>=-)$1-=<{}>=-m4_changequote([,])])
-
-
# m4_shiftn(N, ...)
# -----------------
# Returns ... shifted N times. Useful for recursive "varargs" constructs.
@@ -634,8 +606,40 @@ m4_define([m4_undefine],
[m4_builtin([undefine], [$1])])
+## ------------------------- ##
+## 7. Quoting manipulation. ##
+## ------------------------- ##
+
+# m4_quote(ARGS)
+# --------------
+# Return ARGS as a single argument. Any whitespace after unquoted commas
+# is stripped.
+#
+# It is important to realize the difference between `m4_quote(exp)' and
+# `[exp]': in the first case you obtain the quoted *result* of the
+# expansion of EXP, while in the latter you just obtain the string
+# `exp'.
+m4_define([m4_quote], [[$*]])
+
+
+# m4_dquote(ARGS)
+# ---------------
+# Return ARGS as a quoted list of quoted arguments.
+m4_define([m4_dquote], [EMAIL PROTECTED])
+
+
+# m4_noquote(STRING)
+# ------------------
+# Return the result of ignoring all quotes in STRING and invoking the
+# macros it contains. Amongst other things, this is useful for enabling
+# macro invocations inside strings with [] blocks (for instance regexps
+# and help-strings).
+m4_define([m4_noquote],
+[m4_changequote(-=<{,}>=-)$1-=<{}>=-m4_changequote([,])])
+
+
## -------------------------- ##
-## 7. Implementing m4 loops. ##
+## 8. Implementing m4 loops. ##
## -------------------------- ##
@@ -801,7 +805,7 @@ m4_define([m4_foreach_w],
## --------------------------- ##
-## 8. More diversion support. ##
+## 9. More diversion support. ##
## --------------------------- ##
@@ -889,14 +893,15 @@ m4_define([m4_divert_once],
# m4_undivert(DIVERSION-NAME)
# ---------------------------
-# Undivert DIVERSION-NAME.
+# Undivert DIVERSION-NAME. Unlike the M4 version, this only takes a single
+# diversion identifier, and should not be used to undivert files.
m4_define([m4_undivert],
[m4_builtin([undivert], _m4_divert([$1]))])
-## -------------------------------------------- ##
-## 8. Defining macros with bells and whistles. ##
-## -------------------------------------------- ##
+## --------------------------------------------- ##
+## 10. Defining macros with bells and whistles. ##
+## --------------------------------------------- ##
# `m4_defun' is basically `m4_define' but it equips the macro with the
# needed machinery for `m4_require'. A macro must be m4_defun'd if
@@ -1288,9 +1293,9 @@ m4_define([m4_pattern_forbid], [])
m4_define([m4_pattern_allow], [])
-## ----------------------------- ##
-## Dependencies between macros. ##
-## ----------------------------- ##
+## --------------------------------- ##
+## 11. Dependencies between macros. ##
+## --------------------------------- ##
# m4_before(THIS-MACRO-NAME, CALLED-MACRO-NAME)
@@ -1396,9 +1401,9 @@ m4_define([m4_provide_if],
[$2], [$3])])
-## -------------------- ##
-## 9. Text processing. ##
-## -------------------- ##
+## --------------------- ##
+## 12. Text processing. ##
+## --------------------- ##
# m4_cr_letters
@@ -1829,7 +1834,7 @@ m4_define([m4_qdelta],
## ----------------------- ##
-## 10. Number processing. ##
+## 13. Number processing. ##
## ----------------------- ##
# m4_cmp(A, B)
@@ -1895,7 +1900,7 @@ m4_define([m4_sign],
## ------------------------ ##
-## 11. Version processing. ##
+## 14. Version processing. ##
## ------------------------ ##
@@ -1954,7 +1959,7 @@ m4_define([m4_version_prereq],
## ------------------- ##
-## 12. File handling. ##
+## 15. File handling. ##
## ------------------- ##
@@ -1976,7 +1981,7 @@ m4_if(m4_sysval, [0], [],
## ------------------------ ##
-## 13. Setting M4sugar up. ##
+## 16. Setting M4sugar up. ##
## ------------------------ ##
--
1.5.3.2
