[groff] 09/12: [docs]: Improve intro to device and font files.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 7173468d984d13bc8d03c40905a9d47bc75338f8
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon May 24 22:57:35 2021 +1000

    [docs]: Improve intro to device and font files.
    
    * doc/groff.texi (Device and Font Files): Tweak introductory paragraph,
      mainly to clarify the otherwise confusing way we refer to font
      description file names, which are completely free-form but follow a
      convention of classic Murray Hill Unix room terseness.  Also refer to
      "groff" instead of "GNU troff" when we're referring to the system
      rather than the formatter executable.
    
    * man/groff_font.5.man: Sync with the foregoing.
---
 doc/groff.texi       | 27 +++++++++++++++++----------
 man/groff_font.5.man | 47 +++++++++++++++++++++++++++++++++++++----------
 2 files changed, 54 insertions(+), 20 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 49ecd6a..1e3d246 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -17520,20 +17520,27 @@ follow quite naturally.
 
 @c =====================================================================
 
-@c BEGIN Keep parallel with groff_font(7).
+@c BEGIN Keep parallel with groff_font(5).
 @node Device and Font Files,  , gtroff Output, File formats
 @section Device and Font Files
 @cindex font files
 @cindex files, font
 
-The GNU @code{troff} 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, GNU @code{troff} 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
-device @var{name} are stored in a directory @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}}.
+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} (@sc{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
 * DESC File Format::
@@ -17923,7 +17930,7 @@ sequence of lines of the form:
 This means that when glyph @var{c1} appears next to glyph @var{c2} the
 space between them should be increased by@tie{}@var{n}.  Most entries in
 the kernpairs section have a negative value for@tie{}@var{n}.
-@c END Keep parallel with groff_font(7).
+@c END Keep parallel with groff_font(5).
 
 
 @c =====================================================================
diff --git a/man/groff_font.5.man b/man/groff_font.5.man
index 8e38378..6fb5c60 100644
--- a/man/groff_font.5.man
+++ b/man/groff_font.5.man
@@ -31,7 +31,7 @@ groff_font \- GNU roff device and font description files
 .SH Description
 .\" ====================================================================
 .
-.\" BEGIN Keep parallel with groff.texi node "Font 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
@@ -43,25 +43,52 @@ In distinction to the AT&T implementation,
 .I groff
 lacks a binary format;
 all files are text files.
+.
 (Plan\~9
 .I troff \" Plan 9
-has also abandoned the binary format.}
+has also abandoned the binary format.)
 .
-The font files for device
+The font description files for a device
 .I name
-are stored in a directory
+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\~F.
+.RI font \~f ,
+a font file called
+.RI \[lq] f \[rq],
+where
+.I f
+is usually an abbreviation of a font's name and/or style.
 .
-These are text files;
-unlike the ditroff font format,
-there is no associated binary format.
+For example,
+the
+.B ps
+(PostScript)
+device has
+.I groff
+font description files for Times roman
+.RB ( TR )
+and Zapf Chancery Medium italic
+.RB ( ZCMI ),
+among many others,
+while the
+.B utf8
+device
+(for terminal emulators)
+has only font descriptions for the roman,
+italic,
+bold,
+and bold-italic styles
+.RB ( R ,
+.BR I ,
+.BR B ,
+and
+.BR BI ,
+respectively).
 .
 .
 .\" ====================================================================
@@ -719,7 +746,7 @@ the space between them should be increased by\~\c
 .
 Most entries in kernpairs section have a negative value for\~\c
 .IR n .
-.\" END Keep parallel with groff.texi node "Font Files".
+.\" END Keep parallel with groff.texi node "Device and Font Files".
 .
 .
 .\" ====================================================================