CVSROOT: /sources/m4
Module name: m4
Changes by: Eric Blake <ericb> 06/12/23 00:02:21
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.84
retrieving revision 1.85
diff -u -b -r1.84 -r1.85
--- doc/m4.texinfo 22 Dec 2006 21:42:42 -0000 1.84
+++ doc/m4.texinfo 23 Dec 2006 00:02:20 -0000 1.85
@@ -3663,18 +3663,22 @@
@cindex changing the quote delimiters
@cindex quote delimiters, changing the
[EMAIL PROTECTED] {Builtin (m4)} changequote (@ovar{start}, @ovar{end})
The default quote delimiters can be changed with the builtin
[EMAIL PROTECTED], where @var{start} is the new start-quote delimiter
-and @var{end} is 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]:
+
[EMAIL PROTECTED] {Builtin (m4)} 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 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
@example
-changequote([, ])
+changequote(`[', `]')
@result{}
define([foo], [Macro [foo].])
@result{}
@@ -3682,34 +3686,50 @@
@result{}Macro foo.
@end example
+The quotation strings can safely contain eight-bit characters.
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([[, ]])
+changequote(`[[[', `]]]')
@result{}
-define([[foo]], [[Macro [[[foo]]].]])
+define([[[foo]]], [[[Macro [[[[[foo]]]]].]]])
@result{}
foo
[EMAIL PROTECTED] [foo].
[EMAIL PROTECTED] [[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
-left quote, except using @code{changequote} to change the current
+begin-quote, except using @code{changequote} to change the current
quotes.
If the quotes should be changed from, say, @samp{[} to @samp{[[},
@@ -3717,25 +3737,126 @@
calls of @code{changequote} must be made, one for the temporary quotes
and one for the new quotes.
-Neither quote string should start with a letter or @samp{_} (underscore),
-as they will be confused with names in the input. Doing so disables
-the quoting mechanism.
+Macros are recognized in preference to the begin-quote string, so if a
+prefix of @var{start} can be recognized as part of a potential macro
+name, the quoting mechanism is effectively disabled. Unless you use
[EMAIL PROTECTED] (@pxref{Changesyntax}), this means that @var{start}
+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.
+
[EMAIL PROTECTED]
+define(`echo', `$@@')
[EMAIL PROTECTED]
+define(`hi', `HI')
[EMAIL PROTECTED]
+changequote(`q', `Q')
[EMAIL PROTECTED]
+q hi Q hi
[EMAIL PROTECTED] HI Q HI
+echo(hi)
[EMAIL PROTECTED]
+changequote
[EMAIL PROTECTED]
+changequote(`-', `EOF')
[EMAIL PROTECTED]
+- hi EOF hi
[EMAIL PROTECTED] hi HI
+changequote
[EMAIL PROTECTED]
+changequote(`1', `2')
[EMAIL PROTECTED]
+hi1hi2
[EMAIL PROTECTED]
+hi 1hi2
[EMAIL PROTECTED] hi
[EMAIL PROTECTED] example
+
+Quotes are recognized in preference to argument collection. In
+particular, if @var{start} is a single @samp{(}, then argument
+collection is effectively disabled. For portability with other
+implementations, it is a good idea to avoid @samp{(}, @samp{,}, and
[EMAIL PROTECTED])} as the first character in @var{start}.
+
[EMAIL PROTECTED]
+define(`echo', `$#:$@@:')
[EMAIL PROTECTED]
+define(`hi', `HI')
[EMAIL PROTECTED]
+changequote(`(',`)')
[EMAIL PROTECTED]
+echo(hi)
[EMAIL PROTECTED]::hi
+changequote
[EMAIL PROTECTED]
+changequote(`((', `))')
[EMAIL PROTECTED]
+echo(hi)
[EMAIL PROTECTED]:HI:
+echo((hi))
[EMAIL PROTECTED]::hi
+changequote
[EMAIL PROTECTED]
+changequote(`,', `)')
[EMAIL PROTECTED]
+echo(hi,hi)bye)
[EMAIL PROTECTED]:HIhibye:
[EMAIL PROTECTED] example
+
+If @var{end} is a prefix of @var{start}, the end-quote will be
+recognized in preference to a nested begin-quote. In particular,
+changing the quotes to have the same string for @var{start} and
[EMAIL PROTECTED] disables nesting of quotes. When quote nesting is disabled,
+it is impossible to double-quote strings across macro expansions, so
+using the same string is not done very often.
+
[EMAIL PROTECTED]
+define(`hi', `HI')
[EMAIL PROTECTED]
+changequote(`""', `"')
[EMAIL PROTECTED]
+""hi"""hi"
[EMAIL PROTECTED]
+""hi" ""hi"
[EMAIL PROTECTED] hi
+""hi"" "hi"
[EMAIL PROTECTED]" "HI"
+changequote
[EMAIL PROTECTED]
+`hi`hi'hi'
[EMAIL PROTECTED]'hi
+changequote(`"', `"')
[EMAIL PROTECTED]
+"hi"hi"hi"
[EMAIL PROTECTED]
[EMAIL PROTECTED] example
+
+It is an error if the end of file occurs within a quoted string.
+
[EMAIL PROTECTED] status: 1
[EMAIL PROTECTED]
+`hello world'
[EMAIL PROTECTED] world
+`dangling quote
+^D
[EMAIL PROTECTED]:stdin:2: end of file in string
[EMAIL PROTECTED] example
@node Changecom
@section Changing the comment delimiters
@cindex changing comment delimiters
@cindex comment delimiters, changing
[EMAIL PROTECTED] {Builtin (m4)} changecom (@ovar{start}, @ovar{end})
The default comment delimiters can be changed with the builtin
-macro @code{changecom}, where @var{start} is the new start-comment
-delimiter and @var{end} is the new end-comment delimiter. If any of the
-arguments are void, the default comment delimiters (@code{#} and
-newline) are used instead of the void arguments. The comment delimiters
-can be of any length.
+macro @code{changecom}:
-Calling @code{changecom} without any arguments disables the commenting
-mechanism completely.
[EMAIL PROTECTED] {Builtin (m4)} 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
@@ -3758,6 +3879,15 @@
strings. If you want the text inside a comment expanded, quote the
start comment delimiter.
+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')
@result{}
@@ -3765,41 +3895,126 @@
@result{}
# Not a comment anymore
@result{}# Not a COMMENT anymore
+changecom(`#', `')
[EMAIL PROTECTED]
+# comment again
[EMAIL PROTECTED] comment again
@end example
[EMAIL PROTECTED] Changeresyntax
[EMAIL PROTECTED] Changing the regular expression syntax
+The comment strings can safely contain eight-bit characters.
+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.
[EMAIL PROTECTED] regular expression syntax, changing
[EMAIL PROTECTED] GNU extensions
[EMAIL PROTECTED] {Builtin (gnu)} changeresyntax (@var{resyntax})
-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}).
-
-The @code{changeresyntax} macro expands to nothing, but changes the
-default regular expression syntax used by M4 according to the value of
[EMAIL PROTECTED], equivalent to passing @var{resyntax} as the argument to
[EMAIL PROTECTED] when invoking @code{m4}. @xref{Operation
-modes, , Invoking m4}, for more details. If @var{resyntax} is empty or
-omitted the default settings are reverted to emacs style.
[EMAIL PROTECTED] deffn
-
-Any one of the values below, case is not important, and optionally
-with @kbd{-} or @kbd{ } substituted for @kbd{_} in the given names,
-will set the default regular expression syntax as described in the
-table below. For example the following are all equivalent to
[EMAIL PROTECTED]:
+Macros and quotes are recognized in preference to comments, so if a
+prefix of @var{start} can be recognized as part of a potential macro
+name, or confused with a quoted string, the comment mechanism is
+effectively disabled. Unless you use @code{changesyntax}
+(@pxref{Changesyntax}), this means that @var{start} should not begin
+with a letter, digit, or @samp{_} (underscore), and that neither the
+start-quote nor the start-comment string should be a prefix of the
+other.
@example
-changeresyntax(`gnu m4')
+define(`hi', `HI')
@result{}
-changeresyntax(`GNU-m4')
+define(`hi1hi2', `hello')
@result{}
-changeresyntax(`Gnu_M4')
+changecom(`q', `Q')
[EMAIL PROTECTED]
+q hi Q hi
[EMAIL PROTECTED] HI Q HI
+changecom(`1', `2')
[EMAIL PROTECTED]
+hi1hi2
[EMAIL PROTECTED]
+hi 1hi2
[EMAIL PROTECTED] 1hi2
+changecom(`[[', `]]')
[EMAIL PROTECTED]
+changequote(`[[[', `]]]')
[EMAIL PROTECTED]
+[hi]
[EMAIL PROTECTED]
+[[hi]]
[EMAIL PROTECTED]
+[[[hi]]]
[EMAIL PROTECTED]
+changequote
[EMAIL PROTECTED]
+changecom(`[[[', `]]]')
[EMAIL PROTECTED]
+changequote(`[[', `]]')
[EMAIL PROTECTED]
+[[hi]]
[EMAIL PROTECTED]
+[[[hi]]]
[EMAIL PROTECTED]
[EMAIL PROTECTED] example
+
+Comments are recognized in preference to argument collection. In
+particular, if @var{start} is a single @samp{(}, then argument
+collection is effectively disabled. For portability with other
+implementations, it is a good idea to avoid @samp{(}, @samp{,}, and
[EMAIL PROTECTED])} as the first character in @var{start}.
+
[EMAIL PROTECTED]
+define(`echo', `$#:$@@:')
[EMAIL PROTECTED]
+define(`hi', `HI')
[EMAIL PROTECTED]
+changecom(`(',`)')
[EMAIL PROTECTED]
+echo(hi)
[EMAIL PROTECTED]::(hi)
+changecom
@result{}
+changecom(`((', `))')
[EMAIL PROTECTED]
+echo(hi)
[EMAIL PROTECTED]:HI:
+echo((hi))
[EMAIL PROTECTED]::((hi))
+changecom(`,', `)')
[EMAIL PROTECTED]
+echo(hi,hi)bye)
[EMAIL PROTECTED]:HI,hi)bye:
@end example
+It is an error if the end of file occurs within a comment.
+
[EMAIL PROTECTED] status: 1
[EMAIL PROTECTED]
+changecom(`/*', `*/')
[EMAIL PROTECTED]
+/*dangling comment
+^D
[EMAIL PROTECTED]:stdin:2: end of file in comment
[EMAIL PROTECTED] example
+
[EMAIL PROTECTED] Changeresyntax
[EMAIL PROTECTED] Changing the regular expression syntax
+
[EMAIL PROTECTED] regular expression syntax, changing
[EMAIL PROTECTED] @acronym{GNU} extensions
+The @acronym{GNU} extensions @code{patsubst}, @code{regexp}, and more
+recently, @code{renamesyms} each deal with regular expressions. There
+are multiple flavors of regular expressions, so the
[EMAIL PROTECTED] builtin exists to allow choosing the default
+flavor:
+
[EMAIL PROTECTED] {Builtin (gnu)} changeresyntax (@var{resyntax})
+Changes the default regular expression syntax used by M4 according to
+the value of @var{resyntax}, equivalent to passing @var{resyntax} as the
+argument to the command line option @option{--regexp-syntax}
+(@pxref{Operation modes, , Invoking m4}). If @var{resyntax} is empty,
+the default flaver is reverted to emacs style.
+
[EMAIL PROTECTED] can be any one of the values in the table below. Case is
+not important, and @kbd{-} or @kbd{ } can be substituted for @kbd{_} in
+the given names. If @var{resyntax} is unrecognized, a warning is
+issued and the default flavor is not changed.
+
@table @dfn
@item AWK
@xref{awk regular expression syntax}, for details.
@@ -3811,12 +4026,6 @@
@xref{posix-basic regular expression syntax}, for details.
@item BSD_M4
[EMAIL PROTECTED] regular expression syntax}, for details.
-
[EMAIL PROTECTED] EMACS
[EMAIL PROTECTED] GNU_EMACS
[EMAIL PROTECTED] regular expression syntax}, for details.
-
@item EXTENDED
@itemx POSIX_EXTENDED
@xref{posix-extended regular expression syntax}, for details.
@@ -3830,7 +4039,10 @@
@xref{egrep regular expression syntax}, for details.
@item GNU_M4
[EMAIL PROTECTED] regular expression syntax}, for details.
[EMAIL PROTECTED] EMACS
[EMAIL PROTECTED] GNU_EMACS
[EMAIL PROTECTED] regular expression syntax}, for details. This is the
+default regular expression flavor.
@item GREP
@xref{grep regular expression syntax}, for details.
@@ -3847,13 +4059,52 @@
@xref{posix-egrep regular expression syntax}, for details.
@end table
+The expansion of @code{changeresyntax} is void.
+The macro @code{changeresyntax} is recognized only with parameters.
+This macro was added in M4 2.0.
[EMAIL PROTECTED] deffn
+
+For an example of how @var{resyntax} is recognized, the first three
+usages select the @samp{GNU_M4} regular expression flavor:
+
[EMAIL PROTECTED]
+changeresyntax(`gnu m4')
[EMAIL PROTECTED]
+changeresyntax(`GNU-m4')
[EMAIL PROTECTED]
+changeresyntax(`Gnu_M4')
[EMAIL PROTECTED]
+changeresyntax(`unknown')
[EMAIL PROTECTED]:stdin:4: Warning: changeresyntax: bad syntax-spec: `unknown'
[EMAIL PROTECTED]
[EMAIL PROTECTED] example
+
+Using @code{changeresyntax} makes it possible to omit the optional
[EMAIL PROTECTED] parameter to other macros, while still using a different
+regular expression flavor.
+
[EMAIL PROTECTED]
+patsubst(`ab', `a|b', `c')
[EMAIL PROTECTED]
+patsubst(`ab', `a\|b', `c')
[EMAIL PROTECTED]
+patsubst(`ab', `a|b', `c', `EXTENDED')
[EMAIL PROTECTED]
+changeresyntax(`EXTENDED')
[EMAIL PROTECTED]
+patsubst(`ab', `a|b', `c')
[EMAIL PROTECTED]
+patsubst(`ab', `a\|b', `c')
[EMAIL PROTECTED]
[EMAIL PROTECTED] example
+
@node Changesyntax
@section Changing the lexical structure of the input
@cindex lexical structure of the input
@cindex input, lexical structure of the
@cindex syntax table
[EMAIL PROTECTED] GNU extensions
[EMAIL PROTECTED] @acronym{GNU} extensions
@quotation
The macro @code{changesyntax} and all associated functionality is
experimental (@pxref{Experiments}). The functionality might change in
@@ -3861,13 +4112,13 @@
do for bugs.
@end quotation
-The input to @code{m4} is read character per character, and these
+The input to @code{m4} is read character by character, and these
characters are grouped together to form input tokens (such as macro
names, strings, comments, etc.).
Each token is parsed according to certain rules. For example, a macro
-name starts with a letter or @kbd{_} and consists of the longest
-possible string of letters, @kbd{_} and digits. But who is to decide
+name starts with a letter or @samp{_} and consists of the longest
+possible string of letters, @samp{_} and digits. But who is to decide
what characters are letters, digits, quotes, white space? Earlier the
operating system decided, now you do.
@@ -3875,81 +4126,107 @@
@table @dfn
@item Letters
-Characters that start a macro name. The default is the letters as
-defined by the operating system and the character @kbd{_}.
+Characters that start a macro name. Defaults to the letters as defined
+by the locale, and the character @samp{_}.
@item Digits
Characters that, together with the letters, form the remainder of a
-macro name. The default is the ten digits @[EMAIL PROTECTED]@kbd{9}.
+macro name. Defaults to the ten digits @[EMAIL PROTECTED]@samp{9}, and any
+other digits defined by the locale.
@item White space
-Characters that should be trimmed from the beginning of each
-argument to a macro call. The default is @kbd{SPC}, @kbd{TAB},
[EMAIL PROTECTED] and possibly others as defined by the operating system.
+Characters that should be trimmed from the beginning of each argument to
+a macro call. The defaults are space, tab, newline, carriage return,
+form feed, and vertical tab, and any others as defined by the locale.
@item Open parenthesis
-Characters that open the argument list of a macro call. Default
-is @kbd{(}.
+Characters that open the argument list of a macro call. The default is
+the single character @samp{(}.
@item Close parenthesis
-Characters that close the argument list of a macro call. Default is
[EMAIL PROTECTED])}.
+Characters that close the argument list of a macro call. The default
+is the single character @samp{)}.
@item Argument separator
-Characters that separate the arguments of a macro call. Default
-is @kbd{,}.
+Characters that separate the arguments of a macro call. The default is
+the single character @samp{,}.
@item Dollar
Characters that can introduce an argument reference in the body of a
-macro. Default is @kbd{$}.
+macro. The default is the single character @samp{$}.
+
[EMAIL PROTECTED] Left quote
+The set of characters that can start a single-character quoted string.
+The default is the single character @samp{`}. For multiple-character
+quote delimiters, use @code{changequote} (@pxref{Changequote}).
+
[EMAIL PROTECTED] Begin comment
+The set of characters that can start a single-character comment. The
+default is the single character @samp{#}. For multiple-character
+comment delimiters, use @code{changecom} (@pxref{Changecom}).
@item Other
Characters that have no special syntactical meaning to @code{m4}.
-Default is all characters except those in the categories above.
+Defaults to all characters except those in the categories above.
@item Active
-Characters that themselves, alone, form macro names. No default.
+Characters that themselves, alone, form macro names. This is a
[EMAIL PROTECTED] extension, and active characters have lower precedence
+than comments. By default, no characters are active.
@item Escape
-Characters that must precede macro names for them to be recognized. No
-default.
-
+Characters that must precede macro names for them to be recognized.
+This is a @acronym{GNU} extension. When an escape character is defined,
+then macros are not recognized unless the escape character is present;
+however, the macro name, visible by @samp{$0} in macro definitions, does
+not include the escape character. By default, no characters are
+escapes.
+
[EMAIL PROTECTED] FIXME - we should also consider supporting:
[EMAIL PROTECTED] @item Ignore - characters that are ignored if they appear in
[EMAIL PROTECTED] the input; perhaps defaulting to '\0', category 'I'.
[EMAIL PROTECTED] @item Assign -character used in macro definitions for default
[EMAIL PROTECTED] variables, category '='.
@end table
@noindent
Each character can, besides the basic syntax category, have some syntax
-attributes. These are:
+attributes. One reason these are attributes rather than categories is
+that end delimiters are never recognized except when searching for the
+end of a token triggered by a start delimiter; the end delimiter can
+have syntax properties of its own when it appears in isolation. These
+attributes are:
@table @dfn
[EMAIL PROTECTED] Left quote
-The characters that start a quoted string. Default is @kbd{`}. Basic
-syntax category is `Other'.
-
@item Right quote
-The characters that end a quoted string. Default is @kbd{'}. Basic
-syntax category is `Other'.
-
[EMAIL PROTECTED] Begin comment
-The characters that begin a comment. Default is @kbd{#}. Basic syntax
-category is `Other'.
+The set of characters that can end a single-character quoted string.
+The default is the single character @samp{'}. For multiple-character
+quote delimiters, use @code{changequote} (@pxref{Changequote}). Note
+that @samp{'} also defaults to the syntax category `Other', when it
+appears in isolation.
@item End comment
-The characters that end a comment. Default is @kbd{newline}. Basic
-syntax category is `White space'.
+The set of characters that can end a single-character commet. The
+default is the single character @kbd{newline}. For multiple-character
+comment delimiters, use @code{changecom} (@pxref{Changecom}). Note that
+newline also defaults to the syntax category `White space', when it
+appears in isolation.
@end table
[EMAIL PROTECTED]
-
The builtin macro @code{changesyntax} is used to change the way
@code{m4} parses the input stream into tokens.
@deffn {Builtin (gnu)} changesyntax (@var{syntax-spec}, @dots{})
-The @var{syntax-spec} is a string, whose first character determines the
-syntax category of the other characters. Character ranges are expanded
-as for @ref{Translit}. If there are no other
-characters, @emph{all} characters are given the syntax code.
-
-The characters for the syntax categories are:
+Each @var{syntax-spec} is a two-part string. The first part is a
+command, consisting of a single character describing a syntax category,
+and an optional one-character action. The action can be @samp{-} to
+remove the listed characters from that category and reassign them to the
+`Other' category, @samp{=} to set the category to the listed characters
+and reassign all other characters previously in that category to
+`Other', or @samp{+} to add the listed characters to the category
+without affecting other characters. If an action is not specified, but
+additional characters are present, then @samp{=} is assumed. The
+case-insensitive characters for the syntax categories are:
@table @kbd
@item W
@@ -3980,32 +4257,54 @@
Begin comment
@item E
End comment
[EMAIL PROTECTED]
[EMAIL PROTECTED] @item I
[EMAIL PROTECTED] Ignore
[EMAIL PROTECTED] @item =
[EMAIL PROTECTED] Assign
@end table
-The expansion of @code{changesyntax} is void.
+The remaining characters of each @var{syntax-spec} form the set of
+characters to perform the action on for that syntax category. Character
+ranges are expanded as for @code{translit} (@pxref{Translit}). To start
+the character set with @samp{-}, @samp{+}, or @samp{=}, an action must
+be specified.
+
+If @var{syntax-spec} is just a category, and no action or characters
+were specified, then all characters in that category are reset to their
+default state. A warning is issued if the category character is not
+valid. If @var{syntax-spec} is the empty string, then all categories
+are reset to their default state.
-The builtin macro @code{changesyntax} is recognized only when given
-arguments.
+The expansion of @code{changesyntax} is void.
+The macro @code{changesyntax} is recognized only with parameters. Use
+this macro with caution, as it is possible to change the syntax in such
+a way that no further macros can be recognized by @code{m4}.
+This macro was added in M4 2.0.
@end deffn
[EMAIL PROTECTED]
-With @code{changesyntax} we can modify the meaning of a word.
+With @code{changesyntax} we can modify what characters form a word.
@example
define(`test.1', `TEST ONE')
@result{}
__file__
@result{}stdin
-changesyntax(`O_', `W.')
+test.1
[EMAIL PROTECTED]
+changesyntax(`W+.', `W-_')
@result{}
__file__
@result{}__file__
test.1
@result{}TEST ONE
+changesyntax(`W')
[EMAIL PROTECTED]
+__file__
[EMAIL PROTECTED]
+test.1
[EMAIL PROTECTED]
@end example
[EMAIL PROTECTED]
Another possibility is to change the syntax of a macro call.
@example
@@ -4013,7 +4312,7 @@
@result{}
test(a, b, c)
@result{}3
-changesyntax(`(<', `,|', `)>', `O(,)')
+changesyntax(`(<', `,|', `)>')
@result{}
test(a, b, c)
@result{}0(a, b, c)
@@ -4021,22 +4320,21 @@
@result{}3
@end example
[EMAIL PROTECTED]
Leading spaces are always removed from macro arguments in @code{m4}, but
-by changing the syntax categories we can avoid it.
+by changing the syntax categories we can avoid it. The use of
[EMAIL PROTECTED] is an alternative to using a literal tab character.
@example
define(`test', `$1$2$3')
@result{}
test(`a', `b', `c')
@result{}abc
-changesyntax(`O ')
+changesyntax(`O 'format(`%c', `9'))
@result{}
test(a, b, c)
@result{}a b c
@end example
[EMAIL PROTECTED]
It is possible to redefine the @samp{$} used to indicate macro arguments
in user defined macros.
@@ -4065,7 +4363,7 @@
@end example
Macro calls can be given a @TeX{} or Texinfo like syntax using an
-escape. If one or more characters are defined as escapes macro names
+escape. If one or more characters are defined as escapes, macro names
are only recognized if preceded by an escape character.
If the escape is not followed by what is normally a word (a letter
@@ -4118,35 +4416,37 @@
There is obviously an overlap with @code{changecom} and
@code{changequote}. Comment delimiters and quotes can now be defined in
two different ways. To avoid incompatibilities, if the quotes are set
-with @code{changequote}, all characters marked in the syntax table as
-quotes will be unmarked, leaving only one set of defined quotes as
-before. Since the quotes are syntax attributes rather than syntax
-categories, the old quotes simply revert to their old category. If the
-quotes are set with @code{changesyntax}, other characters marked as
-quotes are left untouched, resulting in at least two sets of quotes.
-This applies to comment delimiters as well, @emph{mutatis mutandis}.
+with @code{changequote}, all other characters marked in the syntax table
+as quotes will revert to their normal syntax categories, leaving only
+one set of defined quotes as before. If the quotes are set with
[EMAIL PROTECTED], it is possible to result in multiple sets of
+quotes. This applies to comment delimiters as well, @emph{mutatis
+mutandis}.
@example
define(`test', `TEST')
@result{}
-changesyntax(`L<', `R>')
+changesyntax(`L+<', `R+>')
@result{}
<test>
@result{}test
-`test>
+`test'
@result{}test
+[test]
[EMAIL PROTECTED]
changequote(<[>, `]')
@result{}
<test>
@result{}<TEST>
+`test'
[EMAIL PROTECTED]'
[test]
@result{}test
@end example
[EMAIL PROTECTED]
-If categories, that form single character tokens, contain several
-characters, all are treated as equal. Any open parenthesis will match
-any close parenthesis, etc.
+If several characters are assigned to a category that forms single
+character tokens, all such characters are treated as equal. Any open
+parenthesis will match any close parenthesis, etc.
@example
changesyntax(`(@{<', `)@}>', `,;:', `O(,)')
@@ -4155,9 +4455,9 @@
@result{}00001111
@end example
[EMAIL PROTECTED]
-This is not so for long quotes, which cannot be matched by single
-character quote and vice versa. The same goes for comment delimiters.
+On the other hand, a multi-character start-quote sequence, which can
+only be created by @code{changequote}, will only be matched by the
+corresponding end-quote sequence. The same goes for comment delimiters.
@example
define(`test', `==$1==')
