[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
fyi-document-m4sugar.patch
|
From: |
Akim Demaille |
|
Subject: |
fyi-document-m4sugar.patch |
|
Date: |
Sun, 17 Jun 2001 20:15:53 +0200 |
Index: ChangeLog
from Akim Demaille <address@hidden>
* doc/autoconf.texi (ms): New index.
(Macro Index): Rename as...
(Autoconf Macro Index): this.
(M4 Macro Index): New appendix.
(Programming in M4): New chapter.
Define M4sugar, M4sh, m4_pattern_forbid, and m4_pattern_allow.
(Quoting): Rename as...
(M$ Quotation): this.
Be part of `Programming in M4).
Index: doc/Makefile.am
--- doc/Makefile.am Mon, 04 Jun 2001 18:29:01 +0200 akim (ace/b/22_Makefile.a
1.5 644)
+++ doc/Makefile.am Sun, 17 Jun 2001 19:49:10 +0200 akim (ace/b/22_Makefile.a
1.5 644)
@@ -28,7 +28,7 @@
# Files from texi2dvi that should be removed, but which Automake does
# not know.
CLEANFILES = autoconf.cvs autoconf.ev autoconf.evs autoconf.ma autoconf.mas \
- autoconf.ov autoconf.ovs autoconf.tmp
+ autoconf.ov autoconf.ovs autoconf.ms autoconf.mss autoconf.tmp
# The documentation
Index: doc/autoconf.texi
--- doc/autoconf.texi Sun, 17 Jun 2001 16:00:27 +0200 akim (ace/16_autoconf.t
1.61.2.110 644)
+++ doc/autoconf.texi Sun, 17 Jun 2001 20:08:15 +0200 akim (ace/16_autoconf.t
1.61.2.110 644)
@@ -114,8 +114,10 @@
@defcodeindex ov
@c Define a CPP variable index.
@defcodeindex cv
address@hidden Define a macro index that @@defmac doesn't write to.
address@hidden Define an Autoconf macro index that @defmac doesn't write to.
@defcodeindex ma
address@hidden Define an M4sugar macro index that @defmac doesn't write to.
address@hidden ms
@node Top, Introduction, (dir), (dir)
@comment node-name, next, previous, up
@@ -138,7 +140,8 @@ @node Top, Introduction, (dir), (dir)
* Existing Tests:: Macros that check for particular features
* Writing Tests:: How to write new feature checks
* Results:: What to do with results from feature checks
-* Writing Macros:: Adding new macros to Autoconf
+* Programming in M4:: Layers on top of which Autoconf is written
+* Writing Autoconf Macros:: Adding new macros to Autoconf
* Manual Configuration:: Selecting features that can't be guessed
* Site Configuration:: Local defaults for @code{configure}
* Running configure scripts:: How to use the Autoconf output
@@ -149,17 +152,17 @@ @node Top, Introduction, (dir), (dir)
* Environment Variable Index:: Index of environment variables used
* Output Variable Index:: Index of variables set in output files
* Preprocessor Symbol Index:: Index of C preprocessor symbols defined
-* Macro Index:: Index of Autoconf macros
+* Autoconf Macro Index:: Index of Autoconf macros
+* M4 Macro Index:: Index of M4, M4sugar, and M4sh macros
* Concept Index:: General index
address@hidden
- --- The Detailed Node Listing ---
address@hidden --- The Detailed Node Listing ---
The GNU build system
-* Automake::
-* Libtool::
-* Pointers::
+* Automake:: Escaping Makefile hell
+* Libtool:: Building libraries portably
+* Pointers:: More info on the GNU build system
Making @code{configure} Scripts
@@ -295,23 +298,31 @@ @node Top, Introduction, (dir), (dir)
* Cache Files:: Files @code{configure} uses for caching
* Cache Checkpointing:: Loading and saving the cache file
-Writing Macros
+Programming in M4
-* Macro Definitions:: Basic format of an Autoconf macro
-* Macro Names:: What to call your new macros
-* Quoting:: Protecting macros from unwanted expansion
-* Reporting Messages:: Notifying @code{autoconf} users
-* Dependencies Between Macros:: What to do when macros depend on other macros
-* Obsoleting Macros:: Warning about old ways of doing things
-* Coding Style:: Writing Autoconf macros @`a la Autoconf
+* M4 Quotation:: Protecting macros from unwanted expansion
+* Programming in M4sugar:: Convenient pure M4 macros
-Quoting
+M4 Quotation
* Active Characters:: Characters that change the behavior of m4
* One Macro Call:: Quotation and one macro call
* Quotation and Nested Macros:: Macros calling macros
* Quotation Rule Of Thumb:: One parenthesis, one quote
+Programming in M4sugar
+
+* Forbidden Patterns:: Catching unexpanded macros
+
+Writing Autoconf Macros
+
+* Macro Definitions:: Basic format of an Autoconf macro
+* Macro Names:: What to call your new macros
+* Reporting Messages:: Notifying @code{autoconf} users
+* Dependencies Between Macros:: What to do when macros depend on other macros
+* Obsoleting Macros:: Warning about old ways of doing things
+* Coding Style:: Writing Autoconf macros @`a la Autoconf
+
Dependencies Between Macros
* Prerequisite Macros:: Ensuring required information
@@ -1069,7 +1080,7 @@ @node autoconf Invocation, autoreconf In
contains the distributed Autoconf macro files, and for the optional file
@file{aclocal.m4} in the current directory. Those files can contain
your site's or the package's own Autoconf macro definitions
-(@pxref{Writing Macros}, for more information). If a macro is defined
+(@pxref{Writing Autoconf Macros}, for more information). If a macro is defined
in more than one of the files that @code{autoconf} reads, the last
definition it reads overrides the earlier ones.
@@ -4849,7 +4860,7 @@ @node Writing Tests, Results, Existing T
When you write a feature test that could be applicable to more than one
software package, the best thing to do is encapsulate it in a new macro.
address@hidden Macros}, for how to do that.
address@hidden Autoconf Macros}, for how to do that.
@menu
* Examining Declarations:: Detecting header files and declarations
@@ -6863,7 +6874,7 @@ @node Language Choice, , Multiple Cases
@c ====================================================== Results of Tests.
address@hidden Results, Writing Macros, Writing Tests, Top
address@hidden Results, Programming in M4, Writing Tests, Top
@chapter Results of Tests
Once @code{configure} has determined whether a feature exists, what can
@@ -7405,142 +7416,26 @@ @node Printing Messages, , Caching Resu
address@hidden ==========================================================
Writing Macros.
address@hidden ======================================================
Programming in M4.
address@hidden Writing Macros, Manual Configuration, Results, Top
address@hidden Writing Macros
address@hidden Programming in M4, Writing Autoconf Macros, Results, Top
address@hidden Programming in M4
-When you write a feature test that could be applicable to more than one
-software package, the best thing to do is encapsulate it in a new macro.
-Here are some instructions and guidelines for writing Autoconf macros.
+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}.
@menu
-* Macro Definitions:: Basic format of an Autoconf macro
-* Macro Names:: What to call your new macros
-* Quoting:: Protecting macros from unwanted expansion
-* Reporting Messages:: Notifying @code{autoconf} users
-* Dependencies Between Macros:: What to do when macros depend on other macros
-* Obsoleting Macros:: Warning about old ways of doing things
-* Coding Style:: Writing Autoconf macros @`a la Autoconf
+* M4 Quotation:: Protecting macros from unwanted expansion
+* Programming in M4sugar:: Convenient pure M4 macros
@end menu
address@hidden Macro Definitions, Macro Names, Writing Macros, Writing Macros
address@hidden Macro Definitions
-
address@hidden DEFUN
-Autoconf macros are defined using the @code{AC_DEFUN} macro, which is
-similar to the M4 builtin @code{define} macro. In addition to defining
-a macro, @code{AC_DEFUN} adds to it some code that is used to constrain
-the order in which macros are called (@pxref{Prerequisite Macros}).
-
-An Autoconf macro definition looks like this:
-
address@hidden
-AC_DEFUN(@var{macro-name}, @var{macro-body})
address@hidden example
-
-You can refer to any arguments passed to the macro as @samp{$1},
address@hidden, etc. @xref{Definitions,, How to define new macros, m4.info,
-GNU m4}, for more complete information on writing M4 macros.
-
-Be sure to properly quote both the @var{macro-body} @emph{and} the
address@hidden to avoid any problems if the macro happens to have
-been previously defined.
-
-Each macro should have a header comment that gives its prototype, and a
-brief description. When arguments have default values, display them in
-the prototype. For example:
-
address@hidden
-# AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1])
-# --------------------------------------
-define([AC_MSG_ERROR],
address@hidden _AC_ECHO([configure: error: $1], 2); exit m4_default([$2], 1);
@}])
address@hidden example
-
-Comments about the macro should be left in the header comment. Most
-other comments will make their way into @file{configure}, so just keep
-using @samp{#} to introduce comments.
-
address@hidden @code{dnl}
-If you have some very special comments about pure M4 code, comments
-that make no sense in @file{configure} and in the header comment, then
-use the builtin @code{dnl}: it causes @code{m4} to discard the text
-through the next newline.
-
-Keep in mind that @code{dnl} is rarely needed to introduce comments;
address@hidden is more useful to get rid of the newlines following macros
-that produce no output, such as @code{AC_REQUIRE}.
-
-
address@hidden Macro Names, Quoting, Macro Definitions, Writing Macros
address@hidden Macro Names
-
-All of the Autoconf macros have all-uppercase names starting with
address@hidden to prevent them from accidentally conflicting with other
-text. All shell variables that they use for internal purposes have
-mostly-lowercase names starting with @samp{ac_}. To ensure that your
-macros don't conflict with present or future Autoconf macros, you should
-prefix your own macro names and any shell variables they use with some
-other sequence. Possibilities include your initials, or an abbreviation
-for the name of your organization or software package.
-
-Most of the Autoconf macros' names follow a structured naming convention
-that indicates the kind of feature check by the name. The macro names
-consist of several words, separated by underscores, going from most
-general to most specific. The names of their cache variables use the
-same convention (@pxref{Cache Variable Names}, for more information on
-them).
-
-The first word of the name after @samp{AC_} usually tells the category
-of feature being tested. Here are the categories used in Autoconf for
-specific test macros, the kind of macro that you are more likely to
-write. They are also used for cache variables, in all-lowercase. Use
-them where applicable; where they're not, invent your own categories.
-
address@hidden @code
address@hidden C
-C language builtin features.
address@hidden DECL
-Declarations of C variables in header files.
address@hidden FUNC
-Functions in libraries.
address@hidden GROUP
address@hidden group owners of files.
address@hidden HEADER
-Header files.
address@hidden LIB
-C libraries.
address@hidden PATH
-The full path names to files, including programs.
address@hidden PROG
-The base names of programs.
address@hidden MEMBER
-Members of aggregates.
address@hidden SYS
-Operating system features.
address@hidden TYPE
-C builtin or declared types.
address@hidden VAR
-C variables in libraries.
address@hidden table
-
-After the category comes the name of the particular feature being
-tested. Any further words in the macro name indicate particular aspects
-of the feature. For example, @code{AC_FUNC_UTIME_NULL} checks the
-behavior of the @code{utime} function when called with a @code{NULL}
-pointer.
-
-An internal macro should have a name that starts with an underscore;
-Autoconf internals should therefore start with @samp{_AC_}.
-Additionally, a macro that is an internal subroutine of another macro
-should have a name that starts with an underscore and the name of that
-other macro, followed by one or more words saying what the internal
-macro does. For example, @code{AC_PATH_X} has internal macros
address@hidden and @code{_AC_PATH_X_DIRECT}.
-
address@hidden Quoting, Reporting Messages, Macro Names, Writing Macros
address@hidden Quoting
address@hidden M4 Quotation, Programming in M4sugar, Programming in M4,
Programming in M4
address@hidden M4 Quotation
@cindex quotation
@c FIXME: Grmph, yet another quoting myth: quotation has *never*
@@ -7560,7 +7455,7 @@ @node Quoting, Reporting Messages, Macro
* Quotation Rule Of Thumb:: One parenthesis, one quote
@end menu
address@hidden Active Characters, One Macro Call, Quoting, Quoting
address@hidden Active Characters, One Macro Call, M4 Quotation, M4 Quotation
@subsection Active Characters
To fully understand where proper quotation is important, you first need
@@ -7609,7 +7504,7 @@ @node Active Characters, One Macro Call,
@code{defn}.}?
address@hidden One Macro Call, Quotation and Nested Macros, Active Characters,
Quoting
address@hidden One Macro Call, Quotation and Nested Macros, Active Characters,
M4 Quotation
@subsection One Macro Call
Let's proceed on the interaction between active characters and macros
@@ -7687,7 +7582,7 @@ @node One Macro Call, Quotation and Nest
address@hidden
address@hidden Quotation and Nested Macros, Quotation Rule Of Thumb, One Macro
Call, Quoting
address@hidden Quotation and Nested Macros, Quotation Rule Of Thumb, One Macro
Call, M4 Quotation
@subsection Quotation and Nested Macros
The examples below use the following macros:
@@ -7816,7 +7711,7 @@ @node Quotation and Nested Macros, Quota
Also, because @code{qar} behaves differently from the other macros,
it's an exception that should be avoided in Autoconf.
address@hidden Quotation Rule Of Thumb, , Quotation and Nested Macros, Quoting
address@hidden Quotation Rule Of Thumb, , Quotation and Nested Macros, M4
Quotation
@subsection Quotation Rule Of Thumb
To conclude, the quotation rule of thumb is:
@@ -7905,7 +7800,184 @@ @node Quotation Rule Of Thumb, , Quotat
by doing @samp{grep AC_ configure}.
address@hidden Reporting Messages, Dependencies Between Macros, Quoting,
Writing Macros
address@hidden Programming in M4sugar, , M4 Quotation, Programming in M4
address@hidden Programming in M4sugar
+
address@hidden M4sugar
+M4 by itself provides only a small, but sufficient, set of all-purpose
+macros. M4sugar introduces additional generic macros. Its name was
+coined by Lars J. Aas: ``Readability And Greater Understanding Stands 4
+M4sugar''.
+
address@hidden
+* Forbidden Patterns:: Catching unexpanded macros
address@hidden menu
+
address@hidden Forbidden Patterns, , Programming in M4sugar, Programming in
M4sugar
address@hidden Forbidden Patterns
+
+M4sugar provides a means to define suspicious patterns, patterns
+describing tokens which should not be found in the output. For
+instance, if an Autoconf @file{configure} script includes tokens such as
address@hidden, or @samp{dnl}, then most probably something went
+wrong (typically a macro was not evaluated because of over quotation).
+
+M4sugar forbids all the tokens matching @samp{^m4_} and @samp{^dnl$}.
+
address@hidden m4_pattern_forbid (@var{pattern})
address@hidden pattern_forbid
+Declare no token matching @var{pattern} must be found in the output.
+Comments are not checked; this can be a problem if, for instance, you
+have some macro left unexpanded after an @samp{#include}. No consensus
+is currently found in the Autoconf community, as some people consider it
+should be valid to name macros in comments (which doesn't makes sense to
+the author of this documentation, as @samp{#}-comments should document
+the output, not the input, documented vy @samp{dnl}-comments).
address@hidden defmac
+
+Of course, you might encounter exceptions to these generic rules, for
+instance you might have to refer to @samp{$m4_flags}.
+
address@hidden m4_pattern_allow (@var{pattern})
address@hidden pattern_allow
+Any token matching @var{pattern} is allowed, including if it matches an
address@hidden pattern.
address@hidden defmac
+
address@hidden Writing Autoconf Macros.
+
address@hidden Writing Autoconf Macros, Manual Configuration, Programming in
M4, Top
address@hidden Writing Autoconf Macros
+
+When you write a feature test that could be applicable to more than one
+software package, the best thing to do is encapsulate it in a new macro.
+Here are some instructions and guidelines for writing Autoconf macros.
+
address@hidden
+* Macro Definitions:: Basic format of an Autoconf macro
+* Macro Names:: What to call your new macros
+* Reporting Messages:: Notifying @code{autoconf} users
+* Dependencies Between Macros:: What to do when macros depend on other macros
+* Obsoleting Macros:: Warning about old ways of doing things
+* Coding Style:: Writing Autoconf macros @`a la Autoconf
address@hidden menu
+
address@hidden Macro Definitions, Macro Names, Writing Autoconf Macros, Writing
Autoconf Macros
address@hidden Macro Definitions
+
address@hidden DEFUN
+Autoconf macros are defined using the @code{AC_DEFUN} macro, which is
+similar to the M4 builtin @code{define} macro. In addition to defining
+a macro, @code{AC_DEFUN} adds to it some code that is used to constrain
+the order in which macros are called (@pxref{Prerequisite Macros}).
+
+An Autoconf macro definition looks like this:
+
address@hidden
+AC_DEFUN(@var{macro-name}, @var{macro-body})
address@hidden example
+
+You can refer to any arguments passed to the macro as @samp{$1},
address@hidden, etc. @xref{Definitions,, How to define new macros, m4.info,
+GNU m4}, for more complete information on writing M4 macros.
+
+Be sure to properly quote both the @var{macro-body} @emph{and} the
address@hidden to avoid any problems if the macro happens to have
+been previously defined.
+
+Each macro should have a header comment that gives its prototype, and a
+brief description. When arguments have default values, display them in
+the prototype. For example:
+
address@hidden
+# AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1])
+# --------------------------------------
+define([AC_MSG_ERROR],
address@hidden _AC_ECHO([configure: error: $1], 2); exit m4_default([$2], 1);
@}])
address@hidden example
+
+Comments about the macro should be left in the header comment. Most
+other comments will make their way into @file{configure}, so just keep
+using @samp{#} to introduce comments.
+
address@hidden @code{dnl}
+If you have some very special comments about pure M4 code, comments
+that make no sense in @file{configure} and in the header comment, then
+use the builtin @code{dnl}: it causes @code{m4} to discard the text
+through the next newline.
+
+Keep in mind that @code{dnl} is rarely needed to introduce comments;
address@hidden is more useful to get rid of the newlines following macros
+that produce no output, such as @code{AC_REQUIRE}.
+
+
address@hidden Macro Names, Reporting Messages, Macro Definitions, Writing
Autoconf Macros
address@hidden Macro Names
+
+All of the Autoconf macros have all-uppercase names starting with
address@hidden to prevent them from accidentally conflicting with other
+text. All shell variables that they use for internal purposes have
+mostly-lowercase names starting with @samp{ac_}. To ensure that your
+macros don't conflict with present or future Autoconf macros, you should
+prefix your own macro names and any shell variables they use with some
+other sequence. Possibilities include your initials, or an abbreviation
+for the name of your organization or software package.
+
+Most of the Autoconf macros' names follow a structured naming convention
+that indicates the kind of feature check by the name. The macro names
+consist of several words, separated by underscores, going from most
+general to most specific. The names of their cache variables use the
+same convention (@pxref{Cache Variable Names}, for more information on
+them).
+
+The first word of the name after @samp{AC_} usually tells the category
+of feature being tested. Here are the categories used in Autoconf for
+specific test macros, the kind of macro that you are more likely to
+write. They are also used for cache variables, in all-lowercase. Use
+them where applicable; where they're not, invent your own categories.
+
address@hidden @code
address@hidden C
+C language builtin features.
address@hidden DECL
+Declarations of C variables in header files.
address@hidden FUNC
+Functions in libraries.
address@hidden GROUP
address@hidden group owners of files.
address@hidden HEADER
+Header files.
address@hidden LIB
+C libraries.
address@hidden PATH
+The full path names to files, including programs.
address@hidden PROG
+The base names of programs.
address@hidden MEMBER
+Members of aggregates.
address@hidden SYS
+Operating system features.
address@hidden TYPE
+C builtin or declared types.
address@hidden VAR
+C variables in libraries.
address@hidden table
+
+After the category comes the name of the particular feature being
+tested. Any further words in the macro name indicate particular aspects
+of the feature. For example, @code{AC_FUNC_UTIME_NULL} checks the
+behavior of the @code{utime} function when called with a @code{NULL}
+pointer.
+
+An internal macro should have a name that starts with an underscore;
+Autoconf internals should therefore start with @samp{_AC_}.
+Additionally, a macro that is an internal subroutine of another macro
+should have a name that starts with an underscore and the name of that
+other macro, followed by one or more words saying what the internal
+macro does. For example, @code{AC_PATH_X} has internal macros
address@hidden and @code{_AC_PATH_X_DIRECT}.
+
address@hidden Reporting Messages, Dependencies Between Macros, Macro Names,
Writing Autoconf Macros
@section Reporting Messages
@cindex Messages, from @code{autoconf}
@@ -7950,7 +8022,7 @@ @node Reporting Messages, Dependencies B
@code{AC_DIAGNOSE} and @code{AC_WARNING} are reported as error, see
@ref{autoconf Invocation}.
address@hidden Dependencies Between Macros, Obsoleting Macros, Reporting
Messages, Writing Macros
address@hidden Dependencies Between Macros, Obsoleting Macros, Reporting
Messages, Writing Autoconf Macros
@section Dependencies Between Macros
Some Autoconf macros depend on other macros having been called first in
@@ -8099,7 +8171,7 @@ @node Suggested Ordering, , Prerequisit
that it has been called.
@end defmac
address@hidden Obsoleting Macros, Coding Style, Dependencies Between Macros,
Writing Macros
address@hidden Obsoleting Macros, Coding Style, Dependencies Between Macros,
Writing Autoconf Macros
@section Obsoleting Macros
Configuration and portability technology has evolved over the years.
@@ -8125,7 +8197,7 @@ @node Obsoleting Macros, Coding Style, D
@var{message} is then printed.
@end defmac
address@hidden Coding Style, , Obsoleting Macros, Writing Macros
address@hidden Coding Style, , Obsoleting Macros, Writing Autoconf Macros
@section Coding Style
The Autoconf macros follow a strict coding style. You are encouraged to
@@ -8133,7 +8205,7 @@ @node Coding Style, , Obsoleting Macros
either by contributing it to Autoconf itself, or via other means.
The first requirement is to pay great attention to the quotation, for
-more details, see @ref{Autoconf Language}, and @ref{Quoting}.
+more details, see @ref{Autoconf Language}, and @ref{M4 Quotation}.
Do not try to invent new interfaces. It is likely that there is a macro
in Autoconf that resembles the macro you are defining: try to stick to
@@ -8332,7 +8404,7 @@ AC_DEFUN(_AC_EMXOS2,
@c ================================================== Manual Configuration
address@hidden Manual Configuration, Site Configuration, Writing Macros, Top
address@hidden Manual Configuration, Site Configuration, Writing Autoconf
Macros, Top
@chapter Manual Configuration
A few kinds of features can't be guessed automatically by running test
@@ -10653,7 +10725,7 @@ @node Output Variable Index, Preprocesso
@printindex ov
address@hidden Preprocessor Symbol Index, Macro Index, Output Variable Index,
Top
address@hidden Preprocessor Symbol Index, Autoconf Macro Index, Output Variable
Index, Top
@unnumbered Preprocessor Symbol Index
This is an alphabetical list of the C preprocessor symbols that the
@@ -10662,15 +10734,24 @@ @node Preprocessor Symbol Index, Macro I
@printindex cv
address@hidden Macro Index, Concept Index, Preprocessor Symbol Index, Top
address@hidden Macro Index
address@hidden Autoconf Macro Index, M4 Macro Index, Preprocessor Symbol Index,
Top
address@hidden Autoconf Macro Index
This is an alphabetical list of the Autoconf macros. To make the list
easier to use, the macros are listed without their preceding @samp{AC_}.
@printindex ma
address@hidden Concept Index, , Macro Index, Top
address@hidden M4 Macro Index, Concept Index, Autoconf Macro Index, Top
address@hidden M4 Macro Index
+
+This is an alphabetical list of the M4, M4sugar, and M4sh macros. To
+make the list easier to use, the macros are listed without their
+preceding @samp{m4_} or @samp{AS_}.
+
address@hidden ms
+
address@hidden Concept Index, , M4 Macro Index, Top
@unnumbered Concept Index
@c FIXME: Find some nice wording to introduce this section.
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- fyi-document-m4sugar.patch,
Akim Demaille <=