CVSROOT: /sources/m4
Module name: m4
Branch: branch-1_4
Changes by: Eric Blake <ericb> 06/10/29 15:22:42
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.1.1.1.2.94
retrieving revision 1.1.1.1.2.95
diff -u -b -r1.1.1.1.2.94 -r1.1.1.1.2.95
--- doc/m4.texinfo 26 Oct 2006 04:45:31 -0000 1.1.1.1.2.94
+++ doc/m4.texinfo 29 Oct 2006 15:22:42 -0000 1.1.1.1.2.95
@@ -2795,11 +2795,12 @@
@code{changequote}:
@deffn Builtin changequote (@dvar{start, `}, @dvar{end, '})
-This sets @var{start} as the new begin-quote delimiter and @var{end} as the
-new end-quote delimiter. If any of the arguments are missing, the default
-quotes (@code{`} and @code{'}) are used instead of the void arguments.
[EMAIL PROTECTED] FIXME POSIX requires that with one argument, the closing quote
[EMAIL PROTECTED] be set to newline, not '.
+This sets @var{start} as the new begin-quote delimiter and @var{end} as
+the new end-quote delimiter. If both arguments are missing, the default
+quotes (@code{`} and @code{'}) are used. If @var{start} is void, then
+quoting is disabled. Otherwise, if @var{end} is missing or void, the
+default end-quote delimiter (@code{'}) is used. The quote delimiters
+can be of any length.
The expansion of @code{changequote} is void.
@end deffn
@@ -2831,7 +2832,8 @@
@end example
@end ignore
If no single character is appropriate, @var{start} and @var{end} can be
-of any length.
+of any length. Other implementations cap the delimiter length to five
+characters, but @acronym{GNU} has no inherent limit.
@example
changequote(`[[[', `]]]')
@@ -2842,18 +2844,32 @@
@result{}Macro [[foo]].
@end example
-Changing the quotes to the empty strings will effectively disable the
-quoting mechanism, leaving no way to quote text.
+Calling @code{changequote} with @var{start} as the empty string will
+effectively disable the quoting mechanism, leaving no way to quote text.
+However, using an empty string is not portable, as some other
+implementations of @code{m4} revert to the default quoting, while others
+preserve the prior non-empty delimiter. If @var{start} is not empty,
+then an empty @var{end} will use the default end-quote delimiter of
[EMAIL PROTECTED]'}, as otherwise, it would be impossible to end a quoted
string.
+Again, this is not portable, as some other @code{m4} implementations
+reuse @var{start} as the end-quote delimiter, while others preserve the
+previous non-empty value. Omitting both arguments restores the default
+begin-quote and end-quote delimiters; fortunately this behavior is
+portable to all implementations of @code{m4}.
@example
define(`foo', `Macro `FOO'.')
@result{}
-changequote(, )
+changequote(`', `')
@result{}
foo
@result{}Macro `FOO'.
`foo'
@result{}`Macro `FOO'.'
+changequote(`,)
[EMAIL PROTECTED]
+foo
[EMAIL PROTECTED] FOO.
@end example
There is no way in @code{m4} to quote a string containing an unmatched
@@ -2866,24 +2882,39 @@
and one for the new quotes.
Macros are recognized in preference to the begin-quote string, so if a
-prefix of @var{start} can be recognized as a potential macro name, the
-quoting mechanism is effectively disabled. Unless you use
+prefix of @var{start} can be recognized as part of a potential macro
+name, the quoting mechanism is effectively disabled. Unless you use
@code{changeword} (@pxref{Changeword}), this means that @var{start}
-should not begin with a letter or @samp{_} (underscore).
+should not begin with a letter, digit, or @samp{_} (underscore).
+However, even though quoted strings are not recognized, the quote
+characters can still be discerned in macro expansion and in trace
+output.
@example
+define(`echo', `$@@')
[EMAIL PROTECTED]
define(`hi', `HI')
@result{}
changequote(`q', `Q')
@result{}
q hi Q hi
@result{}q HI Q HI
+echo(hi)
[EMAIL PROTECTED]
changequote
@result{}
changequote(`-', `EOF')
@result{}
- hi EOF hi
@result{} hi HI
+changequote
[EMAIL PROTECTED]
+changequote(`1', `2')
[EMAIL PROTECTED]
+hi1hi2
[EMAIL PROTECTED]
+hi 1hi2
[EMAIL PROTECTED] hi
@end example
Quotes are recognized in preference to argument collection. In
@@ -2963,12 +2994,12 @@
The default comment delimiters can be changed with the builtin
macro @code{changecom}:
[EMAIL PROTECTED] Builtin changecom (@ovar{start}, @ovar{end})
-This sets @var{start} as the new begin-comment delimiter and @var{end} as
-the new end-comment delimiter. If only one argument is provided,
-newline becomes the new end-comment delimiter. The comment delimiters
-can be of any length. Omitting the first argument, or using the empty
-string as the first argument, disables comments.
[EMAIL PROTECTED] Builtin changecom (@ovar{start}, @dvar{end, @key{NL}})
+This sets @var{start} as the new begin-comment delimiter and @var{end}
+as the new end-comment delimiter. If both arguments are missing, or
[EMAIL PROTECTED] is void, then comments are disabled. Otherwise, if
[EMAIL PROTECTED] is missing or void, the default end-comment delimiter of
+newline is used. The comment delimiters can be of any length.
The expansion of @code{changecom} is void.
@end deffn
@@ -2991,10 +3022,14 @@
strings. If you want the text inside a comment expanded, quote the
begin-comment delimiter.
-Calling @code{changecom} without any arguments, or with an empty string
-for the first argument, disables the commenting mechanism completely.
-To restore the original comment start of @samp{#}, you must explicitly
-ask for it.
+Calling @code{changecom} without any arguments, or with @var{start} as
+the empty string, will effectively disable the commenting mechanism. To
+restore the original comment start of @samp{#}, you must explicitly ask
+for it. If @var{start} is not empty, then an empty @var{end} will use
+the default end-comment delimiter of newline, as otherwise, it would be
+impossible to end a comment. However, this is not portable, as some
+other @code{m4} implementations preserve the previous non-empty
+delimiters instead.
@example
define(`comment', `COMMENT')
@@ -3003,7 +3038,7 @@
@result{}
# Not a comment anymore
@result{}# Not a COMMENT anymore
-changecom(`#')
+changecom(`#', `')
@result{}
# comment again
@result{}# comment again
@@ -3026,21 +3061,33 @@
@result{}«a»
@end example
@end ignore
+If no single character is appropriate, @var{start} and @var{end} can be
+of any length. Other implementations cap the delimiter length to five
+characters, but @acronym{GNU} has no inherent limit.
Comments are recognized in preference to macros. However, this is not
compatible with other implementations, where macros and even quoting
takes precedence over comments, so it may change in a future release.
For portability, this means that @var{start} should not begin with a
-letter or @samp{_} (underscore), and that neither the start-quote nor
-the start-comment string should be a prefix of the other.
+letter, digit, or @samp{_} (underscore), and that neither the
+start-quote nor the start-comment string should be a prefix of the
+other.
@example
define(`hi', `HI')
@result{}
+define(`hi1hi2', `hello')
[EMAIL PROTECTED]
changecom(`q', `Q')
@result{}
q hi Q hi
@result{}q hi Q HI
+changecom(`1', `2')
[EMAIL PROTECTED]
+hi1hi2
[EMAIL PROTECTED]
+hi 1hi2
[EMAIL PROTECTED] 1hi2
@end example
Comments are recognized in preference to argument collection. In
@@ -5368,20 +5415,36 @@
semantics.
@item
[EMAIL PROTECTED] requires @code{changequote(@var{arg})}
-(@pxref{Changequote}) to use newline as the close quote, but @acronym{GNU}
[EMAIL PROTECTED] uses @samp{'} as the close quote. Meanwhile, some
-traditional implementations use @var{arg} as the close quote, making it
-impossible to nest quotes. For predictable results, never call
-changequote with just one argument.
+At one point, @acronym{POSIX} required @code{changequote(@var{arg})}
+(@pxref{Changequote}) to use newline as the close quote, but this was a
+bug, and the next version of @acronym{POSIX} is anticipated to state
+that using empty strings or just one argument is unspecified.
+Meanwhile, the @acronym{GNU} @code{m4} behavior of treating an empty
+end-quote delimiter as @samp{'} is not portable, as Solaris treats it as
+repeating the start-quote delimiter, and BSD treats it as leaving the
+previous end-quote delimiter unchanged. For predictable results, never
+call changequote with just one argument, or with empty strings for
+arguments.
+
[EMAIL PROTECTED]
+At one point, @acronym{POSIX} required @code{changecom(@var{arg},)}
+(@pxref{Changecom}) to make it impossible to end a comment, but this is
+a bug, and the next version of @acronym{POSIX} is anticipated to state
+that using empty strings is unspecified. Meanwhile, the @acronym{GNU}
[EMAIL PROTECTED] behavior of treating an empty end-comment delimiter as newline
+is not portable, as BSD treats it as leaving the previous end-comment
+delimiter unchanged. It is also impossible in BSD implementations to
+disable comments, even though that is required by @acronym{POSIX}. For
+predictable results, never call changecom with empty strings for
+arguments.
@item
-Some implementations of @code{m4} give macros a higher precedence than
+Most implementations of @code{m4} give macros a higher precedence than
comments when parsing, meaning that if the start delimiter given to
@code{changecom} (@pxref{Changecom}) starts with a macro name, comments
are effectively disabled. @acronym{POSIX} does not specify what the
-precedence is, so the @acronym{GNU} @code{m4} parser recognizes comments, then
-macros, then quoted strings.
+precedence is, so the @acronym{GNU} @code{m4} parser recognizes
+comments, then macros, then quoted strings.
@item
Traditional implementations allow argument collection, but not string
