Changes to m4/doc/m4.texinfo,v

[Eric Blake]

CVSROOT:        /sources/m4
Module name:    m4
Changes by:     Eric Blake <ericb>      07/05/28 21:48:42

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.103
retrieving revision 1.104
diff -u -b -r1.103 -r1.104
--- doc/m4.texinfo      25 Apr 2007 14:16:21 -0000      1.103
+++ doc/m4.texinfo      28 May 2007 21:48:41 -0000      1.104
@@ -737,7 +737,7 @@
 Make @code{m4} search @var{DIRECTORY} for included files, prior to
 searching the current working directory.  @xref{Search Path}, for more
 details.  This option may be given more than once.  Some other
-implementations of @code{m4} use @code{-B @var{number}} to change their
+implementations of @code{m4} use @option{-B @var{number}} to change their
 hard-coded limits, but that is unnecessary in @acronym{GNU} where the
 only limit is your hardware capability.  So although it is unlikely that
 you will want to include a relative directory whose name is purely
@@ -805,10 +805,11 @@
 Synchronization directives are always given on complete lines by
 themselves.  When a synchronization discrepancy occurs in the middle of
 an output line, the associated synchronization directive is delayed
-until the beginning of the next generated line.  @xref{Syncoutput}, for
-runtime control.  @var{TRUTH} is interpreted the same as the argument to
address@hidden; if @var{TRUTH} is omitted, or @option{--syncoutput}
-is not used, synchronization lines are disabled.
+until the next newline that does not occur in the middle of a quoted
+string or comment.  @xref{Syncoutput}, for runtime control.  @var{TRUTH}
+is interpreted the same as the argument to @code{syncoutput}; if
address@hidden is omitted, or @option{--syncoutput} is not used,
+synchronization lines are disabled.
 
 @item -U @var{NAME}
 @itemx address@hidden
@@ -3316,7 +3317,7 @@
 @samp{s} flags affect the details of the display.  Remember, the
 @samp{q} flag is implied when the @option{--debug} option (@option{-d},
 @pxref{Debugging options, , Invoking m4}) is used in the command line
-without arguments. Also, @code{--debuglen} (@pxref{Debuglen}) can affect
+without arguments. Also, @option{--debuglen} (@pxref{Debuglen}) can affect
 output, by truncating longer strings.
 
 @comment options: -ds -l3
@@ -3443,7 +3444,7 @@
 @result{}blah
 @end example
 
-Tracing even works on builtins.  However, @command{defn} (@pxref{Defn})
+Tracing even works on builtins.  However, @code{defn} (@pxref{Defn})
 does not transfer tracing status.
 
 @example
@@ -4258,7 +4259,7 @@
 with emacs.
 
 @var{resyntax} 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
+not important, and @samp{-} or @samp{ } can be substituted for @samp{_} in
 the given names.  If @var{resyntax} is unrecognized, a warning is
 issued and the default flavor is not changed.
 
@@ -7158,7 +7159,7 @@
 @deffn {Builtin (gnu)} syncoutput (@var{truth})
 If @var{truth} matches the extended regular expression
 @samp{^[1yY]|^([oO][nN])}, it causes @code{m4} to emit sync lines of the
-form: @code{#line <number> ["<file>"]}.
+form: @samp{#line <number> ["<file>"]}.
 
 If @var{truth} is empty, or matches the extended regular expression
 @samp{^[0nN]|^([oO][fF])}, it causes @code{m4} to turn sync lines off.
@@ -7173,28 +7174,45 @@
 define(`twoline', `1
 2')
 @result{}
+changecom(`/*', `*/')
address@hidden
+define(`comment', `/*1
+2*/')
address@hidden
 twoline
 @result{}1
 @result{}2
 dnl no line
 syncoutput(`on')
address@hidden 5 "stdin"
address@hidden 8 "stdin"
 @result{}
 twoline
 @result{}1
address@hidden 6
address@hidden 9
 @result{}2
 dnl no line
 hello
address@hidden 8
address@hidden 11
 @result{}hello
+comment
address@hidden/*1
address@hidden/
+one comment `two
+three'
address@hidden 13
address@hidden /*1
address@hidden/ two
address@hidden
+goodbye
address@hidden 15
address@hidden
 syncoutput(`off')
 @result{}
 twoline
 @result{}1
 @result{}2
 syncoutput(`blah')
address@hidden:stdin:11: Warning: syncoutput: unknown directive `blah'
address@hidden:stdin:18: Warning: syncoutput: unknown directive `blah'
 @result{}
 @end example
 
@@ -7281,14 +7299,14 @@
 @end example
 
 @noindent
-with the varying input.  The first call, containing the @code{-F}
+with the varying input.  The first call, containing the @option{-F}
 option, only reads and executes file @file{base.m4}, defining
 various application macros and computing other initializations.
 Once the input file @file{base.m4} has been completely processed, @acronym{GNU}
 @code{m4} produces in @file{base.m4f} a @dfn{frozen} file, that is, a
 file which contains a kind of snapshot of the @code{m4} internal state.
 
-Later calls, containing the @code{-R} option, are able to reload
+Later calls, containing the @option{-R} option, are able to reload
 the internal state of @code{m4}, from @file{base.m4f},
 @emph{prior} to reading any other input files.  This means
 instead of starting with a virgin copy of @code{m4}, input will be
@@ -7299,7 +7317,7 @@
 Only one frozen file may be created or read in any one @code{m4}
 invocation.  It is not possible to recover two frozen files at once.
 However, frozen files may be updated incrementally, through using
address@hidden and @code{-F} options simultaneously.  For example, if
address@hidden and @option{-F} options simultaneously.  For example, if
 some care is taken, the command:
 
 @comment ignore
@@ -7365,7 +7383,7 @@
 These are simple (editable) text files, made up of directives,
 each starting with a capital letter and ending with a newline
 (@key{NL}).  Wherever a directive is expected, the character
address@hidden introduces a comment line, empty lines are also ignored.
address@hidden introduces a comment line, empty lines are also ignored.
 In the following descriptions, @var{length}s always refer to
 corresponding @var{string}s.  Numbers are always expressed in decimal.
 The directives are:
@@ -7394,7 +7412,7 @@
 and loaded.  Modules loaded from a frozen file don't add their builtin entries
 to the symbol table.
 
address@hidden F @var{length} @key{NL} @var{string} @key{ML}
address@hidden F @var{length} @key{NL} @var{string} @key{NL}
 Defines, through @code{pushdef}, a definition for @var{string}
 expanding to the function whose builtin name is also @var{string}. The builtin
 name is searched for among the intrinsic builtin functions only.
@@ -7455,7 +7473,7 @@
 @cindex @env{POSIXLY_CORRECT}
 This version of @code{m4} contains a few facilities that do not exist
 in System V @code{m4}.  These extra facilities are all suppressed by
-using the @samp{-G} command line option, unless overridden by other
+using the @option{-G} command line option, unless overridden by other
 command line options.
 Most of these extensions are compatible with
 @uref{http://www.unix.org/single_unix_specification/,
@@ -7474,7 +7492,7 @@
 @item
 Files included with @code{include} and @code{sinclude} are sought in a
 user specified search path, if they are not found in the working
-directory.  The search path is specified by the @samp{-I} option and the
+directory.  The search path is specified by the @option{-I} option and the
 @samp{M4PATH} environment variable (@pxref{Search Path}).
 
 @item
@@ -7538,7 +7556,7 @@
 @end itemize
 
 Additionally, @acronym{POSIX} only requires support for the command line
-options @samp{-s}, @samp{-D}, and @samp{-U}, so all other options
+options @option{-s}, @option{-D}, and @option{-U}, so all other options
 accepted by @acronym{GNU} M4 are extensions.  @xref{Invoking m4},
 for a description of these options.
 
@@ -7564,10 +7582,33 @@
 @code{undivert} call, whereas GNU @code{m4} regards the diverted text as
 being generated at the time it is diverted.
 
-I expect the sync line option to be used mostly when using @code{m4} as
+The sync line option is used mostly when using @code{m4} as
 a front end to a compiler.  If a diverted line causes a compiler error,
 the error messages should most probably refer to the place where the
-diversion were made, and not where it was inserted again.
+diversion was made, and not where it was inserted again.
+
address@hidden options: -s
address@hidden
+divert(2)2
+divert(1)1
+divert`'0
address@hidden 3 "stdin"
address@hidden
+^D
address@hidden 2 "stdin"
address@hidden
address@hidden 1 "stdin"
address@hidden
address@hidden example
+
address@hidden FIXME - this needs to be fixed before 2.0.
+The current @code{m4} implementation has a limitation that the syncline
+output at the start of each diversion occurs no matter what, even if the
+previous diversion did not end with a newline.  This goes contrary to
+the claim that synclines appear on a line by themselves, so this
+limitation may be corrected in a future version of @code{m4}.  In the
+meantime, when using @option{-s}, it is wisest to make sure all
+diversions end with newline.
 
 @item
 GNU @code{m4} makes no attempt at prohibiting self-referential definitions