Re: RFC: rename symbols to m4symbols

[Eric Blake]

Hi Gary,

> Hi Eric!
> 
> On 18 Sep 2006, at 14:09, Eric Blake wrote:
>>> "symbols" is an English word, but was added to m4-1.4o as a macro that
>>> takes 0 arguments (even worse, the 1.4o manual documented the new macro,
>>> but NEWS did not).  This has the potential to break preprocessing of
>>> English text that used to work with m4 1.4.x, when someone upgrades and
>>> makes no changes to their command line.  I propose renaming the macro to
>>> "m4symbols" (and we should probably document a policy that any future
>>> macro added in the gnu module that take 0 arguments either be in the "m4"
>>> or "__" namespace, such as the __program__ macro added in m4 1.4.6).
>>> m4sugar currently handles this case by mapping symbols to "m4_symbols",
>>> consistent with the other remappings it handles, so a rename visible
>>> in m4
>>> 2.0 would slightly impact autoconf; there are other macros that m4sugar
>>> still needs to pick up from CVS M4, such as changeresyntax.
> 
> Agreed.  "symbols" has only been present in alpha releases thus far, so
> I think changing it now rather than feeling the pain of having not done it
> later is the best course of action.  Besides, one or two of the GNU M4
> maintainers also have a commit bit for Autoconf ;-)

OK, here's the M4 patch, and I'll follow up with an autoconf patch in the
near future.

> 
> I suppose that it makes sense to do that with the "modules" builtin by
> virtue of your english words with 0 arguments rule above, but I see no
> compelling reason to change load or unload when they are perfectly in
> keeping with the style of many SUSv3 builtin names.
> 

OK, since load/unload were already blind, they did not have the problem
(English text has the nice property, when properly puncutated :), that an
m4 macro is distinguishable from correct grammar).  So after changing
symbols and modules, the only English word left is divert, which
POSIX/SUSv3 require to behave that way (and the manual documents accordingly).

2006-09-18  Eric Blake  <address@hidden>

        * modules/load.c (modules): Rename to...
        (m4modules): ...this, since it is an English word with 0
        arguments.
        * modules/gnu.c (symbols, m4symbols): Likewise.
        * doc/m4.texinfo (Listing Modules): Rename to...
        (M4modules): ...this.
        (Symbols): Rename to...
        (M4symbols): ...this.
        (Load, Foreach, Trace, Answers): Update to new spellings.
        * NEWS: Document this.

-- 
Life is short - so eat dessert first!

Eric Blake             address@hidden

Hi Gary,

> Hi Eric!
>
> On 18 Sep 2006, at 14:09, Eric Blake wrote:
>>> "symbols" is an English word, but was added to m4-1.4o as a macro that
>>> takes 0 arguments (even worse, the 1.4o manual documented the new macro,
>>> but NEWS did not).  This has the potential to break preprocessing of
>>> English text that used to work with m4 1.4.x, when someone upgrades and
>>> makes no changes to their command line.  I propose renaming the macro to
>>> "m4symbols" (and we should probably document a policy that any future
>>> macro added in the gnu module that take 0 arguments either be in the "m4"
>>> or "__" namespace, such as the __program__ macro added in m4 1.4.6).
>>> m4sugar currently handles this case by mapping symbols to "m4_symbols",
>>> consistent with the other remappings it handles, so a rename visible
>>> in m4
>>> 2.0 would slightly impact autoconf; there are other macros that m4sugar
>>> still needs to pick up from CVS M4, such as changeresyntax.
>
> Agreed.  "symbols" has only been present in alpha releases thus far, so
> I think changing it now rather than feeling the pain of having not done it
> later is the best course of action.  Besides, one or two of the GNU M4
> maintainers also have a commit bit for Autoconf ;-)

OK, here's the M4 patch, and I'll follow up with an autoconf patch in the
near future.

>
> I suppose that it makes sense to do that with the "modules" builtin by
> virtue of your english words with 0 arguments rule above, but I see no
> compelling reason to change load or unload when they are perfectly in
> keeping with the style of many SUSv3 builtin names.
>

OK, since load/unload were already blind, they did not have the problem
(English text has the nice property, when properly puncutated :), that an
m4 macro is distinguishable from correct grammar).  So after changing
symbols and modules, the only English word left is divert, which
POSIX/SUSv3 require to behave that way (and the manual documents accordingly).

2006-09-18  Eric Blake  <address@hidden>

        * modules/load.c (modules): Rename to...
        (m4modules): ...this, since it is an English word with 0
        arguments.
        * modules/gnu.c (symbols, m4symbols): Likewise.
        * doc/m4.texinfo (Listing Modules): Rename to...
        (M4modules): ...this.
        (Symbols): Rename to...
        (M4symbols): ...this.
        (Load, Foreach, Trace, Answers): Update to new spellings.
        * NEWS: Document this.

-- 
Life is short - so eat dessert first!

Eric Blake             address@hidden

Index: HACKING
===================================================================
RCS file: /sources/m4/m4/HACKING,v
retrieving revision 1.3
diff -u -p -r1.3 HACKING
--- HACKING     22 Aug 2006 22:36:28 -0000      1.3
+++ HACKING     19 Sep 2006 03:45:48 -0000
@@ -26,6 +26,10 @@ and is not part of a release distributio
 
 * Changes with user-visible effects must be mentioned in NEWS.
 
+* New macros must be blind, or else prefixed with `m4' or `__', in
+  order to minimize backward compatibility issues with previous
+  releases of M4 when processing English text.
+
 * GNU Coding Standards should be followed:
     http://www.gnu.org/prep/standards/
   Additionally, while GNU M4 is not yet POSIX compliant, we are trying
Index: NEWS
===================================================================
RCS file: /sources/m4/m4/NEWS,v
retrieving revision 1.14
diff -u -p -r1.14 NEWS
--- NEWS        18 Sep 2006 13:16:43 -0000      1.14
+++ NEWS        19 Sep 2006 03:45:48 -0000
@@ -75,6 +75,13 @@ promoted to 2.0.
   affects only debugmode and traceon output; we should probably deprecate
   the --error-output, and rename it something like --trace-output.
 
+* The builtins `modules' and `symbols', introduced in previous betas,
+  have been renamed `m4modules' and `m4symbols', in order to minimize
+  problems when upgrading from 1.4.x and processing English text.  To
+  prevent future problems, any future macro added as a GNU extension will
+  either be blind (ie. be unrecognized without arguments), or begin with
+  the prefix `m4' or `__'.
+
 * FIXME: `m4wrap' semantics need an update to FIFO.
 
 * FIXME: include the (long) list of changes in 1.4.x that were not already
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.45
diff -u -p -r1.45 m4.texinfo
--- doc/m4.texinfo      18 Sep 2006 13:16:43 -0000      1.45
+++ doc/m4.texinfo      19 Sep 2006 03:45:49 -0000
@@ -177,7 +177,7 @@ How to define new macros
 
 * Indir::                       Indirect call of macros
 * Builtin::                     Indirect call of builtins
-* Symbols::                     Getting the defined macro names
+* M4symbols::                   Getting the defined macro names
 
 Conditionals, loops, and recursion
 
@@ -217,7 +217,7 @@ Diverting and undiverting output
 
 Extending M4 with dynamic runtime modules
 
-* Listing Modules::             Listing loaded modules
+* M4modules::                   Listing loaded modules
 * Load::                        Loading additional modules
 * Unload::                      Removing loaded modules
 * Standard Modules::            Standard bundled modules
@@ -1360,7 +1360,7 @@ value, and bring back the original value
 
 * Indir::                       Indirect call of macros
 * Builtin::                     Indirect call of builtins
-* Symbols::                     Getting the defined macro names
+* M4symbols::                   Getting the defined macro names
 @end menu
 
 @node Define
@@ -2128,26 +2128,26 @@ indir(`index')
 @result{}0
 @end example
 
address@hidden Symbols
address@hidden M4symbols
 @section Getting the defined macro names
 
 @cindex macro names
 @cindex @acronym{GNU} extensions
 The name of the currently defined macros can be accessed by
address@hidden:
address@hidden:
 
address@hidden {Builtin (gnu)} symbols (@address@hidden)
-Without arguments, @samp{symbols} expands to a sorted list of quoted
address@hidden {Builtin (gnu)} m4symbols (@address@hidden)
+Without arguments, @code{m4symbols} expands to a sorted list of quoted
 strings, separated by commas.  This contrasts with @code{dumpdef}
 (@pxref{Dumpdef}), whose output cannot be accessed by @code{m4}
 programs.
 
-When given arguments, @code{symbols} returns the sorted subset of the
+When given arguments, @code{m4symbols} returns the sorted subset of the
 @var{names} currently defined, and silently ignores the rest.
 @end deffn
 
 @example
-symbols(`ifndef', `ifdef', `define', `undef')
+m4symbols(`ifndef', `ifdef', `define', `undef')
 @result{}define,ifdef
 @end example
 
@@ -2514,12 +2514,13 @@ define(`_foreach',
                                               `$3')')')dnl
 define(`dquote', ``$@@'')
 @result{}
-foreach(`macro', (dquote(symbols)), `regexp(macro, `.*if.*', ``\&',')')
+foreach(`macro', (dquote(m4symbols)),
+        `regexp(macro, `.*if.*', ``\&',')')
 @result{}ifdef,ifelse,shift,
 @end example
 
 The example had to use a helper @code{quote} to ensure that the output
-from @code{symbols} was double quoted; without it, the macro would have
+from @code{m4symbols} was double quoted; without it, the macro would have
 gone into an infinite loop thanks to macros being reinvoked during the
 rescanning.  Choosing @samp{()} as the list delimiters made this
 example rather awkward in terms of proper quoting.  (A different
@@ -2756,18 +2757,18 @@ However, @acronym{GNU} M4 1.4.7 and earl
 semantics, where @code{traceon} without arguments only affected symbols
 that were defined at that moment, and @code{traceoff} without arguments
 stopped all tracing, even when tracing was requested by macro name.  The
-addition of the macro @code{symbols} (@pxref{Symbols}) in 2.0 makes it
+addition of the macro @code{m4symbols} (@pxref{M4symbols}) in 2.0 makes it
 possible to write a file that approximates the older semantics
 regardless of which version of @acronym{GNU} M4 is in use.
 
 @comment options: -d-V
 @example
 $ @kbd{m4}
-ifdef(`symbols',
-  `define(`traceon', `ifelse(`$#', `0', `builtin(`traceon', symbols)',
+ifdef(`m4symbols',
+  `define(`traceon', `ifelse(`$#', `0', `builtin(`traceon', m4symbols)',
     `builtin(`traceon', $@@)')')dnl
 define(`traceoff', `ifelse(`$#', `0',
-    `builtin(`traceoff')builtin(`traceoff', symbols)',
+    `builtin(`traceoff')builtin(`traceoff', m4symbols)',
     `builtin(`traceoff', $@@)')')')dnl
 define(`a', `1')
 @result{}
@@ -2792,7 +2793,7 @@ traceoff # stops tracing b, even though 
 @error{}m4trace: -1- traceoff
 @error{}m4trace: -1- ifelse
 @error{}m4trace: -1- builtin
address@hidden: -2- symbols
address@hidden: -2- m4symbols
 @error{}m4trace: -1- builtin
 @result{} # stops tracing b, even though it was traced by name
 a b
@@ -3133,7 +3134,7 @@ changecom
 @cindex regular expression syntax, changing
 @cindex GNU extensions
 @deffn {Builtin (gnu)} changeresyntax (@var{resyntax})
-By default, the @sc{gnu} extensions @code{patsubst}, @code{regexp} and
+By default, the @acronym{GNU} extensions @code{patsubst}, @code{regexp} and
 more recently @code{renamesyms} continue to use emacs style regular
 expression syntax (@pxref{Regular expression syntax}).
 
@@ -3920,7 +3921,7 @@ should try to see if you can find it and
 @chapter Extending M4 with dynamic runtime modules
 
 @cindex modules
address@hidden m4-1.4.x had a monolithic architecture.  All of its
address@hidden M4 1.4.x had a monolithic architecture.  All of its
 functionality was contained in a single binary, and additional macros
 could be added only by writing more code in the M4 language, or at the
 extreme by hacking the sources and recompiling the whole thing to make
@@ -3991,7 +3992,7 @@ setenv(`PATH', `/sbin:/bin:/usr/sbin:/us
 
 Also, at build time, you can choose which modules to build into
 the core (so that they will be available without dynamic loading).
-SUSv3 M4 functionality is contained in the module @samp{m4}, @sc{gnu}
+SUSv3 M4 functionality is contained in the module @samp{m4}, @acronym{GNU}
 extensions in the module @samp{gnu}, the @code{load} builtin in the
 module @samp{load} and so on.
 
@@ -4000,47 +4001,48 @@ preloaded into the installed M4 binary, 
 a @emph{thinner} binary minus GNU extensions, for example, by
 configuring the distribution with @samp{./configure
 --with-modules=m4}.  For a binary built with that option to understand
-code that uses @sc{gnu} extensions, you must then run @samp{m4
+code that uses @acronym{GNU} extensions, you must then run @samp{m4
 --load-module=gnu}.  It is also possible to build a @emph{fatter}
 binary with additional modules preloaded: adding, say, the @code{load}
 builtin using @samp{./configure --with-modules="m4 gnu load"}.
 
-GNU M4 now has a facility for defining additional builtins without
address@hidden M4 now has a facility for defining additional builtins without
 recompiling the sources.  In actual fact, all of the builtins provided
-by GNU M4 are loaded from such modules.  All of the builtin
+by @acronym{GNU} M4 are loaded from such modules.  All of the builtin
 descriptions in this manual are annotated with the module from which
 they are loaded -- mostly from the module @samp{m4}.
 
-When you start GNU M4, the modules @samp{m4} and @samp{gnu} are
+When you start @acronym{GNU} M4, the modules @samp{m4} and @samp{gnu} are
 loaded by default.  If you supply the @option{-G} option at startup, the
 module @samp{traditional} is loaded instead of @samp{gnu}.
 @xref{Compatibility}, for more details on the differences between these
 two modes of startup.
 
 @menu
-* Listing Modules::             Listing loaded modules
+* M4modules::                   Listing loaded modules
 * Load::                        Loading additional modules
 * Unload::                      Removing loaded modules
 * Standard Modules::            Standard bundled modules
 @end menu
 
address@hidden Listing Modules
address@hidden M4modules
 @section Listing loaded modules
 
address@hidden {Builtin (load)} modules
address@hidden expands to an ordered list of currently loaded modules,
address@hidden {Builtin (load)} m4modules
+Expands to a quoted ordered list of currently loaded modules,
 with the most recently loaded module at the front of the list.  Loading
 a module multiple times will not affect the order of this list, the
 position depends on when the module was @emph{first} loaded.
 @end deffn
 
-For example, if GNU @code{m4} is started with the @option{-mload}
-option to load the module @samp{load} and make this builtin available,
address@hidden will yield the following:
+For example, if @acronym{GNU} @code{m4} is started with the
address@hidden option to load the module @samp{load} and make this
+builtin available, @code{m4modules} will yield the following:
 
address@hidden ignore
address@hidden options: -m load
 @example
-modules
+$ @kbd{m4 -m load}
+m4modules
 @result{}load,gnu,m4
 @end example
 
@@ -4062,11 +4064,11 @@ option.
 
 @comment ignore
 @example
-modules
+m4modules
 @result{}load,gnu,m4
 load(`mymodule')
 @result{}
-modules
+m4modules
 @result{}mymodule,load,gnu,m4
 @end example
 
@@ -4205,7 +4207,7 @@ index(`gnus, gnats, and armadillos', `da
   @ovar{replacement}, @ovar{resyntax})
 Searching for regular expressions is done with the builtin
 @code{regexp}, which searches for @var{regexp} in @var{string}.  The
-syntax of regular expressions is similar to that of Perl, @sc{gnu} Awk
+syntax of regular expressions is similar to that of Perl, @acronym{GNU} Awk
 and Egrep: so called ``Extended Regular Expression''.
 
 If @var{replacement} is omitted, @code{regexp} expands to the index of
@@ -5098,7 +5100,7 @@ strings.
 
 @item R @var{length} @key{NL} @var{string} @key{NL}
 Sets the default regexp syntax, where @var{string} encodes one of the
-regular expression syntaxes supported by @sc{gnu} M4.
+regular expression syntaxes supported by @acronym{GNU} M4.
 @xref{Changeresyntax}, for more details.
 
 @item M @var{length} @key{NL} @var{string} @key{NL}
@@ -5207,9 +5209,9 @@ by the @code{regexp} (@pxref{Regexp}) an
 @item
 The syntax of regular expressions in M4 has never clearly formalized.
 While Open BSD M4 uses extended regular expressions for @code{regexp}
-and @code{patsubst}, @sc{gnu} M4 uses basic regular expression.  Use
+and @code{patsubst}, @acronym{GNU} M4 uses basic regular expression.  Use
 @code{changeresyntax} (@pxref{Changeresyntax}) to change the regular
-expression syntax used by @sc{gnu} M4.
+expression syntax used by @acronym{GNU} M4.
 
 @item
 The output of shell commands can be read into @code{m4} with
@@ -5387,7 +5389,7 @@ define(`_foreach',
                                               `$3')')')dnl
 define(`dquote', ``$@@'')
 @result{}
-foreach(`macro', (dquote(symbols)), `regexp(macro, `shift', `\&')')
+foreach(`macro', (dquote(m4symbols)), `regexp(macro, `shift', `\&')')
 @result{}shift
 traceon(`shift')
 @result{}
@@ -5414,7 +5416,7 @@ each iteration operates on a shorter lis
 long lists.  Another way of viewing these semantics is that the
 outermost quotes delineates the list, then each element of the list must
 be quoted as though the list delimiters were not present.  Notice the
-difference when iterating over @code{symbols}; we must use
+difference when iterating over @code{m4symbols}; we must use
 @code{dquote_elt} instead of @code{dquote} to get the necessary quoting.
 
 @comment FIXME - include(foreach.m4),include(quote.m4)
@@ -5432,7 +5434,8 @@ define(`_foreach',
                `define(`$1',
                        `_arg1($2)')$3`'_foreach(`$1', _rest($2),
                                                 `$3')')')dnl
-foreach(`macro', `dquote_elt(symbols)', `regexp(macro, `shift', `\&')')
+foreach(`macro', `dquote_elt(m4symbols)',
+        `regexp(macro, `shift', `\&')')
 @result{}shift
 traceon(`shift')
 @result{}
Index: modules/gnu.c
===================================================================
RCS file: /sources/m4/m4/modules/gnu.c,v
retrieving revision 1.55
diff -u -p -r1.55 gnu.c
--- modules/gnu.c       15 Sep 2006 03:37:54 -0000      1.55
+++ modules/gnu.c       19 Sep 2006 03:45:49 -0000
@@ -59,7 +59,7 @@
   BUILTIN (patsubst,   false,  true,   true,   2,      4  )    \
   BUILTIN (regexp,     false,  true,   true,   2,      4  )    \
   BUILTIN (renamesyms, false,  true,   false,  2,      3  )    \
-  BUILTIN (symbols,    false,  false,  false,  0,      -1 )    \
+  BUILTIN (m4symbols,  false,  false,  false,  0,      -1 )    \
   BUILTIN (syncoutput, false,  true,   false,  1,      1  )    \
 
 
@@ -691,13 +691,13 @@ M4BUILTIN_HANDLER (renamesyms)
 }
 
 
-/* Implementation of "symbols".  It builds up a table of pointers to
+/* Implementation of "m4symbols".  It builds up a table of pointers to
    symbols, sorts it and ships out the symbol names.  */
 
 /**
- * symbols([...])
+ * m4symbols([...])
  **/
-M4BUILTIN_HANDLER (symbols)
+M4BUILTIN_HANDLER (m4symbols)
 {
   M4_MODULE_IMPORT (m4, m4_dump_symbols);
 
Index: modules/load.c
===================================================================
RCS file: /sources/m4/m4/modules/load.c,v
retrieving revision 1.18
diff -u -p -r1.18 load.c
--- modules/load.c      25 Aug 2006 22:06:42 -0000      1.18
+++ modules/load.c      19 Sep 2006 03:45:49 -0000
@@ -34,7 +34,7 @@
 
           function     macros  blind   side    minargs maxargs */
 #define builtin_functions                                      \
-  BUILTIN (modules,    false,  false,  false,  0,      0  )    \
+  BUILTIN (m4modules,  false,  false,  false,  0,      0  )    \
   BUILTIN (load,       false,  true,   false,  1,      1  )    \
   BUILTIN (unload,     false,  true,   false,  1,      1  )    \
 
@@ -87,9 +87,9 @@ M4INIT_HANDLER (load)
    of the m4 builtins declared in `m4_builtin_table[]' above.  */
 
 /**
- * modules()
+ * m4modules()
  **/
-M4BUILTIN_HANDLER (modules)
+M4BUILTIN_HANDLER (m4modules)
 {
   /* The expansion of this builtin is a comma separated list of
      loaded modules.  */