[groff] 01/16: [doc,man]: Revise overview of "grout" syntax.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit ddebd0090d994cb518df22d731ea9931ef614afe
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Dec 11 11:08:41 2024 -0600

    [doc,man]: Revise overview of "grout" syntax.
---
 doc/groff.texi.in   | 118 ++++++++++++++++++++++++++-----------------
 man/groff_out.5.man | 142 ++++++++++++++++++++++++----------------------------
 2 files changed, 136 insertions(+), 124 deletions(-)

diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 9856a173a..983872223 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -18164,9 +18164,7 @@ balance readability and maintainability against severe 
constraints on
 file size and transmission speed to the output device.@footnote{See ``A
 Typesetter-independent TROFF'', Bell Labs CSTR@tie{}#97, 1982.}  A
 decade later, when James Clark wrote @code{groff}, these constraints
-were no longer as tight.  GNU @command{troff} therefore emits
-device-independent output that is more easily interpreted by humans than
-did @acronym{AT&T} @code{troff}.
+were no longer as tight.
 @c END Keep parallel with subsection "Background" of groff_out(5).
 
 @menu
@@ -18199,55 +18197,81 @@ supported output formats.
 @c END Keep parallel with introductory paragraph of groff_out(5).
 
 @menu
-* Separation::
+* Syntax::
 * Argument Units::
 * Document Parts::
 @end menu
 
-@node Separation, Argument Units, Language Concepts, Language Concepts
-@subsubsection Separation
+@node Syntax, Argument Units, Language Concepts, Language Concepts
+@anchor{Separation} @c 1.23.0
+@subsubsection Syntax
 
-@acronym{AT&T} @code{troff} output has strange requirements regarding
-whitespace.  The @command{gtroff} output parser, however, is more
-tolerant, making whitespace maximally optional.  Such characters, i.e.,
-the tab, space, and newline, always have a syntactical meaning.  They
-are never printable because spacing within the output is always done by
-positioning commands.
+@code{roff}'s
+page description language is a sequence of
+@dfn{tokens}:@:
+single-letter commands or their arguments.
+Some commands accept a subcommand as a first argument,
+followed by one or more further arguments.
 
-Any sequence of space or tab characters is treated as a single
-@dfn{syntactical space}.  It separates commands and arguments, but is
-only required when there would occur a clashing between the command code
-and the arguments without the space.  Most often, this happens when
-variable-length command names, arguments, argument lists, or command
-clusters meet.  Commands and arguments with a known, fixed length need
-not be separated by syntactical space.
-
-A line break is a syntactical element, too.  Every command argument can
-be followed by whitespace, a comment, or a newline character.  Thus a
-@dfn{syntactical line break} is defined to consist of optional
-syntactical space that is optionally followed by a comment, and a
-newline character.
-
-The normal commands, those for positioning and text, consist of a single
-letter taking a fixed number of arguments.  For historical reasons, the
-parser allows stacking of such commands on the same line, but
-fortunately, in @command{gtroff}'s intermediate output, every command
-with at least one argument is followed by a line break, thus providing
-excellent readability.
-
-The other commands---those for drawing and device control---have a more
-complicated structure; some recognize long command names, and some take
-a variable number of arguments.  So all @samp{D} and @samp{x} commands
-were designed to request a syntactical line break after their last
-argument.  Only one command, @w{@samp{x X}}, has an argument that can
-span several input lines; all other commands must have all of their
-arguments on the same line as the command, i.e., the arguments may not
-be split by a line break.
-
-Empty lines (these are lines containing only space and/or a comment),
-can occur everywhere.  They are just ignored.
-
-@node Argument Units, Document Parts, Separation, Language Concepts
+AT&T device-independent
+@command{troff} @c AT&T
+used whitespace minimally when producing output.
+GNU
+@command{troff}, @c GNU
+in contrast,
+attempts to make its output more human-readable.
+The whitespace characters---tab,
+space,
+and newline---are always meaningful.
+They are never used to represent spacing in the document;
+that is done with horizontal
+(@code{h}, @code{H})
+and vertical
+(@code{v}, @code{V})
+positioning commands.
+Any sequence of space and/or tab characters is equivalent to a single
+space,
+separating commands from arguments and arguments from each other.
+Space is required only where omitting it would cause ambiguity.
+A line break separates commands.
+The comment character is a pound/hash sign
+(@code{#}),
+and marks the remainder of the line as a comment.
+A line comprising only whitespace after comment removal does nothing but
+separate input tokens.
+
+The positioning commands noted above,
+and the command to write one glyph
+(@code{c}),
+each take a single argument;
+the former a signed integer,
+and the latter a printable ISO@tie{}646/``ASCII'' character.
+A series of such commands could validly occur without spaces
+on an input line,
+but GNU
+@command{troff} @c GNU
+follows each with a newline.
+
+Some commands have a more complex syntax;
+the GNU
+@command{troff} @c GNU
+extension command for writing glyph sequences
+(@code{t})
+accepts a variable number of arguments.
+Those that draw geometric objects
+(@code{D})
+or control the device
+(@code{x})
+furthermore recognize subcommand arguments.
+Such commands thus must end with a newline.
+In GNU
+@command{troff}, @c GNU
+the device extension (sub)command
+@samp{@w{x X}}
+uniquely supports a line continuation syntax;
+all other commands occupy one input line.
+
+@node Argument Units, Document Parts, Syntax, Language Concepts
 @subsubsection Argument Units
 
 Some commands take integer arguments that are assumed to represent
@@ -18686,7 +18710,7 @@ example, @command{gtroff} outputs the initialization 
command
 @w{@samp{x r}} as @w{@samp{x res}}.
 
 In the following, the syntax element @angles{line break} means a
-syntactical line break (@pxref{Separation}).
+syntactical line break (@pxref{Syntax}).
 
 @table @code
 @item xF @var{name}@angles{line break}
diff --git a/man/groff_out.5.man b/man/groff_out.5.man
index a9eedc2f9..3f0cfd847 100644
--- a/man/groff_out.5.man
+++ b/man/groff_out.5.man
@@ -224,107 +224,95 @@ A decade later,
 when James Clark wrote
 .IR groff ,
 these constraints were no longer as tight.
-.
-GNU
-.I troff \" GNU
-therefore emits device-independent output that is more easily
-interpreted by humans than did AT&T
-.IR troff . \" AT&T
 .\" END Keep parallel with paragraphs after the first in the "gtroff
 .\" Output" node in doc/groff.texi.in.
 .
 .
 .\" ====================================================================
-.SS Separation
+.SS Syntax
 .\" ====================================================================
 .
-.I Classical troff output
-had strange requirements on whitespace.
-.
-The
-.I groff
-output parser, however, is smart about whitespace by making it
-maximally optional.
-.
-The whitespace characters, i.e., the
-.IR tab ,
-.IR space ,
-and
-.I newline
-characters, always have a syntactical meaning.
-.
-They are never printable because spacing within the output is always
-done by positioning commands.
+.IR roff 's
+page description language is a sequence of
+.I tokens:
+single-letter commands or their arguments.
+Some commands accept a subcommand as a first argument,
+followed by one or more further arguments.
 .
 .
 .P
-Any sequence of
-.I space
-or
-.I tab
-characters is treated as a single
-.I syntactical
-.IR space .
-.
-It separates commands and arguments, but is only required when there
-would occur a clashing between the command code and the arguments
-without the space.
+AT&T device-independent
+.I troff \" AT&T
+used whitespace minimally when producing output.
 .
-Most often, this happens when variable length command names,
-arguments, argument lists, or command clusters meet.
+GNU
+.IR troff , \" GNU
+in contrast,
+attempts to make its output more human-readable.
 .
-Commands and arguments with a known, fixed length need not be
-separated by
-.I syntactical
-.IR space .
+The whitespace characters\[em]tab,
+space,
+and newline\[em]are always meaningful.
 .
+They are never used to represent spacing in the document;
+that is done with horizontal
+.RB ( h ,\~ H )
+and vertical
+.RB ( v ,\~ V )
+positioning commands.
 .
-.P
-A line break is a syntactical element, too.
+Any sequence of space and/or tab characters is equivalent to a single
+space,
+separating commands from arguments and arguments from each other.
 .
-Every command argument can be followed by whitespace, a comment, or a
-newline character.
+Space is required only where omitting it would cause ambiguity.
 .
-Thus a
-.I syntactical line break
-is defined to consist of optional
-.I syntactical space
-that is optionally followed by a comment, and a newline character.
+A line break separates commands.
 .
+The comment character is a pound/hash sign
+.RB ( # ),
+and marks the remainder of the line as a comment.
 .
-.P
-The normal commands, those for positioning and text, consist of a
-single letter taking a fixed number of arguments.
+A line comprising only whitespace after comment removal does nothing but
+separate input tokens.
 .
-For historical reasons, the parser allows stacking of such commands on
-the same line, but fortunately, in
-.I groff intermediate
-.IR output ,
-every command with at least one argument is followed by a line break,
-thus providing excellent readability.
 .
 .P
-The other commands\[em]those for drawing and device control\[em]have a
-more complicated structure; some recognize long command names, and some
-take a variable number of arguments.
-.
-So all
-.B D
-and
-.B x
-commands were designed to request a
-.I syntactical line break
-after their last argument.
+The positioning commands noted above,
+and the command to write one glyph
+.RB ( c ),
+each take a single argument;
+the former a signed integer,
+and the latter a printable ISO\~646/\[lq]ASCII\[rq] character.
+.
+A series of such commands could validly occur without spaces
+on an input line,
+but GNU
+.I troff \" GNU
+follows each with a newline.
 .
-Only one command,
-.RB \[oq] x\ X \[cq]
-has an argument that can stretch over several lines, all other
-commands must have all of their arguments on the same line as the
-command, i.e., the arguments may not be split by a line break.
 .
 .P
-Lines containing only spaces and/or a comment are treated as empty and
-ignored.
+Some commands have a more complex syntax;
+the GNU
+.I troff \" GNU
+extension command for writing glyph sequences
+.RB ( t )
+accepts a variable number of arguments.
+Those that draw geometric objects
+.RB ( D )
+or control the device
+.RB ( x )
+furthermore recognize subcommand arguments.
+.
+Such commands thus must end with a newline.
+.
+In GNU
+.I troff, \" GNU
+the device extension (sub)command
+.RB \[lq] x\~X \[rq]
+uniquely supports a line continuation syntax;
+all other commands occupy one input line.
 .
 .
 .\" ====================================================================