[groff] 15/18: roff(1): Fix content and style nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 81a9f53501bad085c5bfe5bb46879048be695c08
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Apr 7 14:22:46 2022 +1000

    roff(1): Fix content and style nits.
    
    Content:
    * Replace reference to "normal parsing" with what it actually means.
    * Add streams as an object type in the groff language (albeit a
      neglected one).
    * Correct explanation of vtroff's origin, thanks to Clem Cole of TUHS.
      It even segues better into the origins of device-independent troff.
    * Refer to \(dq as a _neutral_ double quote, for consistency with other
      groff documentation and to avoid confusion with directional
      typographer's quotes.
    
    Style:
    * Supply Kernighan and Ritchie's given names on first occurrence (only).
    * Fix verb tense in reference the K&R 2nd ed and APUE; we can't pretend
      these are _recent_ publications.
    * Fix orphaned word.
    * Clarify saucy remark about monocase file systems of old.
    * Stop referring to McIlroy's RUNOFF descendant as "roff" before
      presenting how that moniker came about.
    * Tighten wording.
    * Use active voice more.
---
 man/roff.7.man | 68 +++++++++++++++++++++++++++++++++++++---------------------
 1 file changed, 43 insertions(+), 25 deletions(-)

diff --git a/man/roff.7.man b/man/roff.7.man
index 3b18ad63..431c4f7a 100644
--- a/man/roff.7.man
+++ b/man/roff.7.man
@@ -55,13 +55,13 @@ system.
 The manual pages on Unix systems
 (\[lq]man\~pages\[rq])
 and bestselling books on software engineering,
-including Kernighan and Ritchie's
+including Brian Kernighan and Dennis Ritchie's
 .I The C Programming Language
 and W.\& Richard Stevens's
 .I Advvanced Programming in the Unix Environment
-are written using a
+have been written using
 .I roff
-system.
+systems.
 .
 GNU
 .IR roff \[em] groff \[em]is
@@ -201,8 +201,8 @@ escape sequences whose purpose is to obtain glyphs that are 
not easily
 typed at the keyboard,
 or which have special meaning to the formatter
 (like
-.B \[rs]
-itself).
+.BR \[rs] ).
+.\" slack wording: itself).
 .
 .
 .P
@@ -591,7 +591,9 @@ is
 .I interpolated,
 as if typed at its call site.
 .
-Its contents are then parsed normally.
+Its contents are then parsed for further request invocations,
+macro calls,
+and escape sequences.
 .
 .
 .P
@@ -706,6 +708,14 @@ see
 .MR groff_char @MAN7EXT@ .
 .
 .
+.P
+.I groff
+offers
+.IR streams ,
+identifiers for writable files,
+but for security reasons this feature is disabled by default.
+.
+.
 .\" BEGIN Keep roughly parallel with first paragraphs of groff.texi node
 .\" "Deferring Output".
 .P
@@ -798,7 +808,7 @@ The program is generally referred to in full capitals,
 both to distinguish it from its many descendants,
 and because bits were expensive in those days;
 five- and six-bit character encodings were still in widespread usage,
-and mixed-case alphabetics seen as a luxury.
+and mixed-case alphabetics in file names seen as a luxury.
 .
 .I RUNOFF
 introduced a syntax of inlining formatting directives amid document
@@ -909,9 +919,8 @@ you had to backspace and underscore in the input yourself).
 .B .fi
 to enable filling of output lines got the name it retains to this day.
 .
-.I roff
-also featured a heuristic system for automatically placing hyphenation
-points,
+McIlroy's program also featured a heuristic system for automatically
+placing hyphenation points,
 designed and implemented by Molly Wagner.
 .
 It furthermore introduced numeric variables,
@@ -940,7 +949,7 @@ McIlroy's
 .I roff
 was one of the first Unix programs.
 .
-in Dennis Ritchie's term,
+In Ritchie's term,
 it was \[lq]transliterated\[rq] from BCPL to DEC PDP-7 assembly language
 .\" see "The Evolution of the Unix Time-Sharing System", Ritchie, 1984
 for the fledgling Unix operating system.
@@ -969,9 +978,8 @@ would call diversions were available via \[lq]footnote\[rq] 
requests.
 .
 This
 .I roff
-indirectly funded operating systems research at Murray Hill,
-for it was used to prepare patent applications for AT&T to the U.S.\&
-government.
+indirectly funded operating systems research at Murray Hill;
+AT&T prepared patent applications to the U.S.\& government with it.
 .
 This arrangement enabled the group to acquire a PDP-11;
 .I roff
@@ -986,7 +994,7 @@ and paper terminals such as the IBM 2471
 (based on the Selectric line of typewriters)
 and the Teletype Corporation Model 37.
 .
-Proportionally-spaced type was unknown.
+Proportionally-spaced type was unavailable.
 .
 .
 .\" ====================================================================
@@ -1109,7 +1117,7 @@ phototypesetter,
 and with it came the necessity of expanding the capabilities of a
 .I roff
 system to cope with proportionally-spaced type,
-multiple type sizes,
+multiple sizes,
 and a variety of fonts.
 .
 Ossanna wrote a parallel implementation of
@@ -1145,7 +1153,7 @@ empowered with multiple type sizes,
 italics,
 and a symbol font specially commissioned by Bell Labs from
 Graphic Systems,
-Brian Kernighan and Lorinda Cherry implemented
+Kernighan and Lorinda Cherry implemented
 .I eqn \" AT&T
 for typesetting mathematics.
 .
@@ -1228,6 +1236,22 @@ featured in volume 2,
 edited by Kernighan.
 .
 .
+.\" Thanks to Clem Cole for the following account.
+.\" https://minnie.tuhs.org/pipermail/tuhs/2022-January/025143.html
+.P
+Meanwhile,
+.I troff
+proved popular even at Unix sites that lacked a C/A/T device.
+.
+Tom Ferrin of the University of California at San Francisco combined it
+with Allen Hershey's popular vector fonts to produce
+.IR vtroff ,
+which translated
+.IR troff 's
+output to the command language used by Versatec and Benson-Varian
+plotters.
+.
+.
 .P
 Ossanna had passed away unexpectedly in 1977,
 and after the release of Version 7,
@@ -1270,13 +1294,7 @@ Ossanna's
 with its tight coupling to the capabilities of the C/A/T,
 remained in parallel distribution with device-independent
 .I troff
-throughout the 1980s,
-leading some developers to contrive translators for C/A/T-formatted
-documents to other devices.
-.
-An example was
-.I vtroff
-for Versatec and Benson-Varian plotters.
+throughout the 1980s.
 .
 Today,
 however,
@@ -1858,7 +1876,7 @@ quote to achieve both aims.
 .
 .I groff
 cuts this knot by supporting a special character escape sequence for the
-double quote,
+neutral double quote,
 .RB \[lq] \[rs][dq] \[rq] ,
 which never performs quoting in the typesetting language,
 but is simply a glyph,