[groff] 06/17: [docs]: Further improve intro to font files.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 33112cce6690dae32d23d02052ad5c94c0329d7f
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue May 25 13:54:57 2021 +1000

    [docs]: Further improve intro to font files.
    
    Motivation:
    
    When I was first exposed to *roff many years ago, I knew so little that
    the practice of referring to the inscrutably named "font files" "TR",
    "HI", and so forth led me to believe that they were, somehow,  fonts.
    That is, I thought that *roff did its own font rendering, and that these
    weird files somehow provided enough information to do this, which didn't
    seem plausible, but according to Unix fanboy culture, Murray Hill had a
    room full of unimpeachable geniuses so how could I be sure?
    
    It's much kinder to the reader to spend a word and say "description",
    reinforcing the notion (which we should do more work in the "Fonts and
    Symbols" node of our Texinfo manual to implant) that glyph rendering
    remains the responsibility of the device.
    
    A groff "font file" "AR" is simply not remotely the same sort of thing
    that URWGothic-Book.t1 is, and we do readers and learners a grave
    disservice by encouraging them to think that they are.
    
    So I expect to be treating the term "font file" in our documentation
    with some savagery henceforth, injecting the word "description" anywhere
    I think there might otherwise be ambiguity.  I acknowledge that doing so
    will be met with allergic reactions from Thompson disciples who find a
    10-letter word abhorrent to read and even more so to write.
---
 doc/groff.texi       | 29 +++++++++++++++--------------
 man/groff_font.5.man | 28 ++++++++++++++--------------
 2 files changed, 29 insertions(+), 28 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 6c5b6bf..bfb20c4 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -17541,20 +17541,21 @@ follow quite naturally.
 @cindex font files
 @cindex files, font
 
-The @code{groff} font format is a rough superset of the @acronym{AT&T}
-device-independent @code{troff} font format.  In distinction to the
-@acronym{AT&T} implementation, @code{groff} lacks a binary format; all
-files are text files.@footnote{Plan@tie{}9 @code{troff} has also
-abandoned the binary format.}  The font files for a device @var{name} are
-stored in a directory called @file{dev@var{name}}.  There are two types
-of file: a device description file called @file{DESC}, and for each
-font@tie{}@var{f}, a font file called@tie{}@file{@var{f}}, where @var{f}
-is usually an abbreviation of a font's name and/or style.  For example,
-the @samp{ps} (PostScript) device has @code{groff} font description
-files for Times roman (@file{TR}) and Zapf Chancery Medium italic
-(@file{ZCMI}), among many others, while the @samp{utf8} device (for
-terminal emulators) has only font descriptions for the roman, italic,
-bold, and bold-italic styles (@file{R}, @file{I}, @file{B}, and
+The @code{groff} font and output device description formats are slight
+extensions of those used by @acronym{AT&T} device-independent
+@code{troff}.  In distinction to the @acronym{AT&T} implementation,
+@code{groff} lacks a binary format; all files are text
+files.@footnote{Plan@tie{}9 @code{troff} has also abandoned the binary
+format.}  The device and font description files for a device @var{name}
+are stored in a directory called @file{dev@var{name}}.  The device
+description file is called @file{DESC}, and, for each font@tie{}@var{f}
+supported by the device, a font file called@tie{}@file{@var{f}}, where
+@var{f}@tie{}is usually an abbreviation of a font's name and/or style.
+For example, the @samp{ps} (PostScript) device has @code{groff} font
+description files for Times roman (@file{TR}) and Zapf Chancery Medium
+italic (@file{ZCMI}), among many others, while the @samp{utf8} device
+(for terminal emulators) has only font descriptions for the roman,
+italic, bold, and bold-italic styles (@file{R}, @file{I}, @file{B}, and
 @file{BI}, respectively).
 
 @menu
diff --git a/man/groff_font.5.man b/man/groff_font.5.man
index 6fb5c60..c27885d 100644
--- a/man/groff_font.5.man
+++ b/man/groff_font.5.man
@@ -34,10 +34,9 @@ groff_font \- GNU roff device and font description files
 .\" BEGIN Keep parallel with groff.texi node "Device and Font Files".
 The
 .I groff
-font format is a rough superset of the AT&T
-device-independent
-.I troff \" generic
-font format.
+font and output device description formats are slight
+extensions of those used by AT&T device-independent
+.IR troff . \" AT&T
 .
 In distinction to the AT&T implementation,
 .I groff
@@ -48,21 +47,22 @@ all files are text files.
 .I troff \" Plan 9
 has also abandoned the binary format.)
 .
-The font description files for a device
+The device and font description files for a device
 .I name
 are stored in a directory called
 .IR dev name.
 .
-There are two types of file:
-a device description file called
-.I DESC
-and for each
-.RI font \~f ,
-a font file called
-.RI \[lq] f \[rq],
+The device description file is called
+.IR DESC ,
+and,
+for each
+.RI font\~ f
+supported by the device,
+a font file
+.RI called\~\[lq] f \[rq],
 where
-.I f
-is usually an abbreviation of a font's name and/or style.
+.IR f \~is
+usually an abbreviation of a font's name and/or style.
 .
 For example,
 the