[groff] 18/30: [docs]: Fix content, style, and markup nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit e3639240f47f67c5823c62ee0efb69e055737940
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Jun 15 01:31:49 2022 -0500

    [docs]: Fix content, style, and markup nits.
    
    Content:
    * Say simply "automatic break" instead of "automatic line break", since
      we are at pains elsewhere to declaim that an unqualified "break" is an
      (output) line break.
    * Relatedly, stop speaking of newline usage in the input as "breaking".
    * Drop overgeneralization: spaces and newlines are not interchangeable
      in input (when filling is enabled); the equivalence applies only to
      sequences of unit length.
    
    Style:
    * Drop extraneous word.
    * Tighten wording.
    * Drop extraneous punctuation from non-sentential foonote.
    * Shift a cross reference from a footnote to a parenthetical.
    * Fix typo.
    
    Markup:
    * In a comment, note when the `c.` register came to troff.
---
 doc/groff.texi | 57 ++++++++++++++++++++++++++++-----------------------------
 man/roff.7.man | 18 +++++++-----------
 2 files changed, 35 insertions(+), 40 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 742f4ced..924a4343 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -780,8 +780,8 @@ and @acronym{PDF}.
 @cindex installation
 
 Installation procedures are documented by the files @file{INSTALL},
-@file{INSTALL.extra}, and file @file{INSTALL.REPO} in the @code{groff}
-source distribution.
+@file{INSTALL.extra}, and @file{INSTALL.REPO} in the @code{groff} source
+distribution.
 
 
 @c =====================================================================
@@ -5110,8 +5110,8 @@ This is discussed in @ref{Manipulating Filling and 
Adjustment}.
 @subsection Adjustment
 
 @cindex extra spaces between words
-After GNU @code{troff} performs an automatic line break, it then tries
-to @dfn{adjust} the line: inter-word spaces are widened until the text
+After GNU @code{troff} performs an automatic break, it then tries to
+@dfn{adjust} the line: inter-word spaces are widened until the text
 reaches the right margin.  Extra spaces between words are preserved.
 Leading and trailing spaces are handled as noted above.  Text can be
 aligned to the left or right margins or centered; see @ref{Manipulating
@@ -5466,25 +5466,24 @@ traditions have accrued in service of these goals.
 
 @itemize @bullet
 @item
-Follow sentence endings in input with newlines to ease their
-recognition (@pxref{Sentences}).  It is frequently convenient to break
-after colons and semicolons as well, as these typically precede
-independent clauses.  Consider breaking after commas; they often occur
-in lists that become easy to scan when itemized by line, or constitute
-supplements to the sentence that are added, deleted, or updated to
-clarify it.  Parenthetical and quoted phrases are also good candidates
-for placement on input lines by themselves.  In filled text, spaces and
-newlines are interchangeable; place breaks where it aids your purpose.
+Follow sentence endings in the input with newlines to ease their
+recognition (@pxref{Sentences}).  It is frequently convenient to end
+input lines after colons and semicolons as well, as these typically
+precede independent clauses.  Consider doing so after commas; they often
+occur in lists that become easy to scan when itemized by line, or
+constitute supplements to the sentence that are added, deleted, or
+updated to clarify it.  Parenthetical and quoted phrases are also good
+candidates for placement on input lines by themselves.
 
 @item
 Set your text editor's line length to 72 characters or
 fewer.@footnote{Emacs: @code{fill-column: 72}; Vim: @code{textwidth=72}}
-This limit, combined with the previous advice regarding breaking around
-punctuation, makes it less common that an input line will wrap in your
-text editor, and thus will help you perceive excessively long
-constructions in your text.  Recall that natural languages originate in
-speech, not writing, and that punctuation is correlated with pauses for
-breathing and changes in prosody.
+This limit, combined with the previous item of advice, makes it less
+common that an input line will wrap in your text editor, and thus will
+help you perceive excessively long constructions in your text.  Recall
+that natural languages originate in speech, not writing, and that
+punctuation is correlated with pauses for breathing and changes in
+prosody.
 
 @item
 Use @code{\&} after @samp{!}, @samp{?}, and @samp{.} if they are
@@ -7552,9 +7551,9 @@ This document was formatted in \n(y4.
 @vindex c.
 @cindex input line number register (@code{.c}, @code{c.})
 @cindex line number, input, register (@code{.c}, @code{c.})
-The current @emph{input} line number.  @samp{c.} (a @code{groff}
-extension) is also writable, affecting subsequent interpolations of both
-@samp{.c} and @samp{c.}.
+The current @emph{input} line number.  @samp{c.} is a writable synonym,
+@c introduced in AT&T device-independent troff (CSTR #54, 1981-01)
+affecting subsequent interpolations of both @samp{.c} and @samp{c.}.
 
 @item \n[ln]
 @vindex ln
@@ -11685,7 +11684,7 @@ necessarily the same.  For the @code{dvi}, @code{html}, 
@code{pdf},
 automatically loads a macro file defining many color names at startup.
 By the same mechanism, the devices supported by @code{grotty} recognize
 the eight standard ISO@tie{}6429/EMCA-48 color names.@footnote{also
-known vulgarly as ``ANSI colors''.}
+known vulgarly as ``ANSI colors''}
 
 @DefreqList {gcolor, [@Var{color}]}
 @DefescItemx {\\m, , c, }
@@ -12735,8 +12734,8 @@ definition ends with the control line @samp{..} (two 
dots).
 Alternatively, @var{end} identifies a macro whose call syntax at the
 start of a control line ends the definition of @var{name}; @var{end} is
 then called normally.  A macro definition must end in the same
-conditional block (if any) in which it began.@footnote{@xref{Conditional
-Blocks}}  Spaces or tabs are permitted after the control character in
+conditional block (if any) in which it began (@pxref{Conditional
+Blocks}).  Spaces or tabs are permitted after the control character in
 the line containing this ending token (either @samp{.} or
 @samp{@var{end}}), but a tab immediately after the token prevents its
 recognition as the end of a macro definition.  The macro @var{end} can
@@ -12776,10 +12775,10 @@ unique end macro.
 
 An end macro need not be defined until it is called.  This fact enables
 a nested macro definition to begin inside one macro and end inside
-another.  Consider the following example.@footnote{The structure of this
-example is adapted from, and isomorphic to, part of a solution by Tadziu
-Hoffman to the problem of reflowing text multiple times to find an
-optimal configuration for it.
+another.  Consider the following example.@footnote{Its structure is
+adapted from, and isomorphic to, part of a solution by Tadziu Hoffman to
+the problem of reflowing text multiple times to find an optimal
+configuration for it.
 @uref{https://lists.gnu.org/archive/html/groff/2008-12/msg00006.html}}
 
 @Example
diff --git a/man/roff.7.man b/man/roff.7.man
index 8ca005f2..9387c92b 100644
--- a/man/roff.7.man
+++ b/man/roff.7.man
@@ -58,7 +58,7 @@ and bestselling books on software engineering,
 including Brian Kernighan and Dennis Ritchie's
 .I The C Programming Language
 and W.\& Richard Stevens's
-.I Advvanced Programming in the Unix Environment
+.I Advanced Programming in the Unix Environment
 have been written using
 .I roff
 systems.
@@ -298,7 +298,7 @@ The end of input causes a break.
 .
 .
 .P
-After the formatter performs an automatic line break,
+After the formatter performs an automatic break,
 it then tries to
 .I adjust
 the line:
@@ -2027,14 +2027,14 @@ Several traditions have accrued in service of these 
goals.
 .
 .
 .IP \[bu] 2n
-Follow sentence endings in input with newlines to ease their
+Follow sentence endings in the input with newlines to ease their
 recognition.
 .\" Texinfo: (@pxref{Sentences}).
-It is frequently convenient to break after colons and semicolons as
-well,
+It is frequently convenient to end input lines after colons and
+semicolons as well,
 as these typically precede independent clauses.
 .
-Consider breaking after commas;
+Consider doing so after commas;
 they often occur in lists that become easy to scan when itemized by
 line,
 or constitute supplements to the sentence that are added,
@@ -2044,10 +2044,6 @@ or updated to clarify it.
 Parenthetical and quoted phrases are also good candidates for placement
 on input lines by themselves.
 .
-In filled text,
-spaces and newlines are interchangeable;
-place breaks where it aids your purpose.
-.
 .
 .IP \[bu]
 Set your text editor's line length to 72 characters or fewer;
@@ -2056,7 +2052,7 @@ see the subsections below.
 .\" @footnote{Emacs: @code{fill-column: 72}; Vim: @code{textwidth=72}}
 .
 This limit,
-combined with the previous advice regarding breaking around punctuation,
+combined with the previous item of advice,
 makes it less common that an input line will wrap in your text editor,
 and thus will help you perceive excessively long constructions in your
 text.