[groff] 07/39: doc/groff.texi: Revise and recast.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 6d9a2ca651d294fdce7f17fd63deb44d58c0b520
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun May 29 11:53:44 2022 -0500

    doc/groff.texi: Revise and recast.
    
    * doc/groff.texi (Requests and Macros): Simplify and tighten discussion.
      Stop mentioning configurability of control characters in this
      introductory node.  Move a footnote about where control characters are
      recognized from here...
    
      (Formatter Instructions): ...to here.  Generalize discussion from GNU
      troff to roff programs when covering common features.  Include more
      examples of the most common applications of escape sequences.
    
      (Requests): Move a footnote about Plan 9 troff behavior to here...
    
      (Request and Macro Arguments): ...from here.  Say "escape sequence"
      instead of "escape", and stop annotating it with Texinfo @dfn command
      since the term has already been defined supra.
---
 doc/groff.texi | 56 +++++++++++++++++++++++++++-----------------------------
 1 file changed, 27 insertions(+), 29 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 50f1565b..b5a91335 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -5069,15 +5069,11 @@ We have now encountered almost all of the syntax there 
is in the
 @cindex control character, no-break
 @cindex no-break control character
 A @dfn{request} is an instruction to the formatter that occurs after a
-control character.  A @dfn{control character} must occur at the
-beginning of an input line to be recognized.@footnote{A control
-character can also occur in arguments to @code{if}, @code{ie},
-@code{el}, @code{nop}, and @code{while} requests.}  The regular control
-character has a counterpart, the @dfn{no-break control character}, which
-suppresses the break that is implied by some requests.  The default
-control characters are the dot (@code{.}) and the neutral apostrophe
-(@code{'}), the latter being the no-break control character.  These
-characters were chosen because it is uncommon for lines of text in
+@dfn{control character}, which is recognized at the beginning of an
+input line.  The regular control character is a dot (@code{.}).  Its
+counterpart, the @dfn{no-break control character}, a neutral apostrophe
+(@code{'}), suppresses the break that is implied by some requests.
+These characters were chosen because it is uncommon for lines of text in
 natural languages to begin with them.  If you require a formatted period
 or apostrophe (closing single quotation mark) where GNU @code{troff} is
 expecting a control character, prefix the dot or neutral apostrophe with
@@ -6275,22 +6271,24 @@ emitted!  The contents of the first macro definition 
are lost.
 
 To support documents that require more than filling, automatic line
 breaking and hyphenation, adjustment, and supplemental inter-sentence
-space, GNU @code{troff} allows instructions to the formatter to be
-embedded into the text.  This is done in two ways.
+space, a @code{roff} program offers two means of embedding instructions
+to the formatter.
 
 One is a @dfn{request}, which begins with a control character and takes
-up an entire input line.  Requests often perform relatively large-scale
-operations such as setting the page length, breaking a line, or starting
-a new page.
+up the remainder of the input line.@footnote{A control character can
+also occur in arguments to @code{if}, @code{ie}, @code{el}, @code{nop},
+and @code{while} requests.}  Requests often perform relatively
+large-scale operations such as setting the page length, breaking a line,
+or starting a new page.
 
 The other is an @dfn{escape sequence}, which begins with the escape
-character and can usually be embedded anywhere in the text, even in
-arguments to requests and other escape sequences.  Escape sequences
-often implement relatively minor operations like sub- and superscripting
-or interpolating a symbol.
+character and can be embedded anywhere in the input, even in arguments
+to requests and other escape sequences.  Escape sequences often
+implement relatively minor operations like sub- and superscripting or
+interpolation of special characters, strings, or register contents.
 
-Some operations are available via both requests and escape sequences,
-such as font selection and type size alteration.
+Some operations, such as font selection and type size alteration, are
+available via both requests and escape sequences.
 
 @menu
 * Requests::
@@ -6313,8 +6311,10 @@ single quote (@samp{'}, the @dfn{no-break control 
character}) or a
 period (@samp{.}, the normal @dfn{control character}).  These can be
 changed; see @ref{Character Translations}, for details.  After this
 there may be optional tabs or spaces followed by an identifier, which is
-the name of the request.  This may be followed by any number of
-space-separated arguments (@emph{no} tabs here).
+the name of the request.  If the request is given arguments, they must
+be separated from the request name and each other by spaces; GNU
+@code{troff} does not allow tabs for argument
+separation.@footnote{Plan@tie{}9 @code{troff} does.}
 
 @cindex structuring source code of documents or macro packages
 @cindex documents, structuring the source of
@@ -6421,17 +6421,15 @@ end macro (@pxref{Writing Macros}).
 @cindex tabs, and macro arguments
 @cindex macro arguments, and tabs
 @cindex arguments to macros, and tabs
-Arguments to requests and macros are separated by space
-characters.@footnote{Plan@tie{}9 @code{troff} also allows tabs for
-argument separation---GNU @code{troff} intentionally doesn't support
-this.}  Only one space between arguments is necessary; additional ones
-are harmless and ignored.
+Arguments to requests and macros are separated by space characters.
+Only one space between arguments is necessary; additional ones are
+ignored.
 
 @cindex spaces, in a macro argument
 A macro argument that must contain space characters can either be
 enclosed in double quotes---this is @emph{not} true of requests---or one
-of several varieties of @dfn{escape} with a spacing function can be used
-instead.
+of several varieties of escape sequence with a spacing function can be
+used instead.
 
 Consider calls to a hypothetical macro @code{uh}: