[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
more m4sugar documentation
|
From: |
Eric Blake |
|
Subject: |
more m4sugar documentation |
|
Date: |
Fri, 12 Oct 2007 22:21:50 +0000 (UTC) |
|
User-agent: |
Loom/3.14 (http://gmane.org/) |
I've been busy documenting quite a few m4sugar macros. Applied:
From: Eric Blake <address@hidden>
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 <address@hidden>
---
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 <address@hidden>
+ 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
address@hidden Messages}.
address@hidden 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,
address@hidden 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}
address@hidden
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:
address@hidden @minus
address@hidden m4_builtin
address@hidden m4_changecom
address@hidden m4_changequote
address@hidden m4_debugfile
address@hidden m4_debugmode
address@hidden m4_decr
address@hidden m4_define
address@hidden m4_divnum
address@hidden m4_dumpdef
address@hidden m4_errprint
address@hidden m4_esyscmd
address@hidden m4_eval
address@hidden m4_format
address@hidden m4_ifdef
address@hidden m4_incr
address@hidden m4_index
address@hidden m4_indir
address@hidden m4_len
address@hidden m4_pushdef
address@hidden m4_shift
address@hidden m4_substr
address@hidden m4_syscmd
address@hidden m4_sysval
address@hidden m4_traceoff
address@hidden m4_traceon
address@hidden m4_translit
address@hidden itemize
+
Some M4 macros are redefined, and are slightly incompatible with their
native equivalent.
address@hidden __file__
address@hidden __line__
address@hidden __file__
address@hidden __line__
+All M4 macros starting with @samp{__} retain their original name: for
+example, no @code{m4__file__} is defined.
address@hidden defmac
+
address@hidden __oline__
address@hidden __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.
address@hidden defmac
+
@defmac dnl
address@hidden
address@hidden dnl
This macro kept its original name: no @code{m4_dnl} is defined.
@end defmac
address@hidden m4_bpatsubst (@var{string}, @var{regexp}, @ovar{replacement})
address@hidden
+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.
address@hidden defmac
+
address@hidden m4_bregexp (@var{string}, @var{regexp}, @ovar{replacement})
address@hidden
+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.
address@hidden 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
address@hidden
@end defmac
address@hidden FIXME: Need to document m4_divert, m4_undivert, m4_divert_push,
address@hidden m4_divert_pop, m4_divert_text, m4_divert_once
address@hidden m4_divert (@var{diversion})
address@hidden
+M4sugar relies heavily on diversions, so rather than behaving as a
+primitive, @code{m4_divert} behaves like:
address@hidden
+m4_divert_pop()m4_divert_push(address@hidden)
address@hidden example
address@hidden
address@hidden support}, for more details about the use of the
+diversion stack.
address@hidden 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
address@hidden m4_bpatsubst (@var{string}, @var{regexp}, @ovar{replacement})
address@hidden
-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.
address@hidden 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}.
address@hidden defmac
-
address@hidden m4_bregexp (@var{string}, @var{regexp}, @ovar{replacement})
address@hidden
-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
address@hidden
@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(address@hidden, [m4_undefine(address@hidden)])
@@ -10207,6 +10271,15 @@ m4_ifdef(address@hidden, [m4_undefine(address@hidden)])
to recover the behavior of the builtin.
@end defmac
address@hidden m4_undivert (@var{diversion})
address@hidden
+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.
address@hidden support}, for more details about the use of the
+diversion stack.
address@hidden defmac
+
@defmac m4_wrap (@var{text})
@msindex{wrap}
This macro corresponds to @code{m4wrap}.
@@ -10234,14 +10307,160 @@ m4_wrap([foo])
@end defmac
address@hidden Diagnostic Macros
address@hidden Diagnostic messages from M4sugar
address@hidden 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}.
+
address@hidden m4_assert (@var{expression}, @dvar{exit-status, 1})
address@hidden
+Assert that the arithmetic @var{expression} evaluates to non-zero.
+Otherwise, issue a fatal error, and exit @command{autom4te} with
address@hidden
address@hidden defmac
+
address@hidden m4_errprintn (@var{message})
address@hidden
+Similar to the builtin @code{m4_errprint}, except that a newline is
+guaranteed after @var{message}.
address@hidden defmac
+
address@hidden
address@hidden m4_fatal
address@hidden
+Report a severe error @var{message} prefixed with the current location,
+and have @command{autom4te} die.
address@hidden defmac
+
address@hidden m4_location
address@hidden
+Useful as a prefix in a message line. Short for:
address@hidden
+__file__:__line__
address@hidden example
address@hidden defmac
+
address@hidden
address@hidden m4_warn (@var{category}, @var{message})
address@hidden
+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:
+
address@hidden @samp
address@hidden all
+messages that don't fall into one of the following categories. Use of an
+empty @var{category} is equivalent.
+
address@hidden cross
+related to cross compilation issues.
+
address@hidden obsolete
+use of an obsolete construct.
+
address@hidden syntax
+dubious syntactic constructs, incorrectly ordered macro calls.
address@hidden table
address@hidden defmac
+
+
address@hidden Diversion support
address@hidden 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.
address@hidden @code
address@hidden KILL
+Text written to this diversion is discarded. This is the default
+diversion once M4sugar is initialized.
address@hidden GROW
+This diversion is used behind the scenes by topological sorting macros,
+such as @code{AC_REQUIRE}.
address@hidden table
+
+M4sh adds several more named diversions.
address@hidden @code
address@hidden BINSH
+This diversion is reserved for the @samp{#!} interpreter line.
address@hidden HEADER-REVISION
+This diversion holds text from @code{AC_REVISION}.
address@hidden HEADER-COMMENT
+This diversion holds comments about the purpose of a file.
address@hidden HEADER-COPYRIGHT
+This diversion is managed by @code{AC_COPYRIGHT}.
address@hidden M4SH-SANITIZE
+This diversion contains M4sh sanitization code, used to ensure M4sh is
+executing in a reasonable shell environment.
address@hidden M4SH-INIT
+This diversion contains M4sh initialization code, initializing variables
+that are required by other M4sh macros.
address@hidden BODY
+This diversion contains the body of the shell code, and is the default
+diversion once M4sh is initialized.
address@hidden table
+
+For now, the named diversions of Autoconf, Autoheader, and Autotest are
+not documented.
+
address@hidden m4_divert_once (@var{diversion}, @ovar{content})
address@hidden
+Similar to @code{m4_divert_text}, except that @var{content} is only
+output to @var{diversion} if this is the first time that
address@hidden has been called with its particular arguments.
address@hidden defmac
+
address@hidden m4_divert_pop (@ovar{diversion})
address@hidden
+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}.
address@hidden defmac
+
address@hidden m4_divert_push (@var{diversion})
address@hidden
+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.
address@hidden defmac
+
address@hidden m4_divert_text (@var{diversion}, @ovar{content})
address@hidden
+Output @var{content} and a newline into @var{diversion}, without
+affecting the current diversion. Shorthand for:
address@hidden
+m4_divert_push(address@hidden)@var{content}
+m4_divert_pop(address@hidden)dnl
address@hidden example
address@hidden defmac
+
@node Conditional constructs
@subsection Conditional constructs
The following macros provide additional conditional contructs, as
convenience wrappers around @code{m4_if}.
address@hidden m4_bmatch (@var{string}, @var{regex-1}, @var{value-1}, @dots{}, @
- @ovar{default})
address@hidden 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
address@hidden m4_bpatsubsts (@var{string}, @var{regex-1}, @var{subst-1},
@dots{})
address@hidden 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
address@hidden m4_case (@var{string}, @var{value-1}, @var{if-value-1}, @dots{},
@
- @ovar{default})
address@hidden 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(address@hidden, address@hidden, address@hidden
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.
address@hidden m4_re_escape (@var{string})
address@hidden
-Backslash-escape all characters in @var{string} that are active in
-regexps.
address@hidden defmac
-
address@hidden m4_tolower (@var{string})
address@hidden m4_toupper (@var{string})
address@hidden
address@hidden
-Return @var{string} with letters converted to upper or lower case,
-respectively.
address@hidden defmac
-
address@hidden m4_split (@var{string}, @ovar{regexp})
address@hidden
-Split @var{string} into an M4 list of elements quoted by @samp{[} and
address@hidden, 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.
address@hidden defmac
-
address@hidden m4_normalize (@var{string})
address@hidden
-Remove leading and trailing spaces and tabs, sequences of
-backslash-then-newline, and replace multiple spaces and tabs with a
-single space.
address@hidden 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
+
address@hidden m4_flatten (@var{string})
address@hidden
+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.
address@hidden defmac
+
address@hidden m4_join (@ovar{separator}, @address@hidden)
address@hidden
+Concatenate each @var{arg}, separated by @var{separator}. The result is
+a quoted string.
address@hidden defmac
+
address@hidden m4_newline
address@hidden
+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.
address@hidden defmac
+
address@hidden m4_normalize (@var{string})
address@hidden
+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
address@hidden
address@hidden defmac
+
address@hidden m4_re_escape (@var{string})
address@hidden
+Backslash-escape all characters in @var{string} that are active in
+regexps.
address@hidden defmac
+
address@hidden m4_split (@var{string}, @dvar{regexp, [\t ]+})
address@hidden
+Split @var{string} into an M4 list of elements quoted by @samp{[} and
address@hidden, 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.
address@hidden defmac
+
address@hidden m4_strip (@var{string})
address@hidden
+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.
address@hidden defmac
+
address@hidden m4_text_box (@var{message}, @dvar{frame, -})
address@hidden
+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:
address@hidden
+m4_define([macro], [abc])dnl
+m4_text_box([macro])
address@hidden --- ##
address@hidden abc ##
address@hidden --- ##
address@hidden example
address@hidden defmac
+
address@hidden m4_text_wrap (@var{string}, @ovar{prefix}, @
+ @dvar{prefix1, @var{prefix}}, @dvar{width, 79})
address@hidden
+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:
address@hidden
+m4_text_wrap([Short string */], [@ @ @ ], [/* ], [20])
address@hidden/* Short string */
+m4_text_wrap([Much longer string */], [@ @ @ ], [/* ], [20])
address@hidden/* Much longer
address@hidden@ @ @ string */
+m4_text_wrap([Short doc.], [@ @ @ @ @ @ @ @ @ @ ], [@ @ --short ], [30])
address@hidden@ @ --short Short doc.
+m4_text_wrap([Short doc.], [@ @ @ @ @ @ @ @ @ @ ], [@ @ --too-wide ], [30])
address@hidden@ @ --too-wide
address@hidden@ @ @ @ @ @ @ @ @ @ Short doc.
+m4_text_wrap([Super long documentation.], [@ @ @ @ @ ],
+ [@ @ --too-wide ], 30)
address@hidden@ @ --too-wide
address@hidden@ @ @ @ @ Super long
address@hidden@ @ @ @ @ documentation.
address@hidden example
address@hidden defmac
+
address@hidden m4_tolower (@var{string})
address@hidden m4_toupper (@var{string})
address@hidden
address@hidden
+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])
address@hidden
@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
address@hidden is run, which are dependent on the environment of
+the user rather than the maintainer. For dynamic diagnostics, see
address@hidden 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:
-
address@hidden @samp
address@hidden all
-messages that don't fall into one of the following categories. Use of an
-empty @var{category} is equivalent.
-
address@hidden cross
-related to cross compilation issues.
-
address@hidden obsolete
-use of an obsolete construct.
-
address@hidden syntax
-dubious syntactic constructs, incorrectly ordered macro calls.
address@hidden table
+user) if warnings of the @var{category} are turned on. This macro is
+obsolescent; you are encouraged to use:
address@hidden
+m4_warn(address@hidden, address@hidden)
address@hidden example
address@hidden
+instead. @xref{m4_warn}, for more details, including valid
address@hidden 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:
address@hidden
+m4_warn([syntax], address@hidden)
address@hidden example
address@hidden
+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:
address@hidden
+m4_fatal(address@hidden)
address@hidden example
address@hidden
+instead. @xref{m4_fatal}, for more details.
@end defmac
When the user runs @samp{autoconf -W error}, warnings from
address@hidden and @code{AC_WARNING} are reported as error, see
address@hidden Invocation}.
address@hidden (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], address@hidden)
-
-
-# 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], address@hidden)
+
+
+# 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
- more m4sugar documentation,
Eric Blake <=