[groff] 05/35: [docs]: Fix nits in device/font discussion.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 8c9fa859ca3e026d2a0e848ffa4c48ac0f88b4b0
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Oct 22 12:55:23 2021 +1100

    [docs]: Fix nits in device/font discussion.
    
    * Be more precise regarding how directive overriding works.
    * Say "type size" instead of "point size".
    * In groff_font(5), offer a more useful cross reference to groff(1).
---
 doc/groff.texi       | 15 +++++++++------
 man/groff_font.5.man | 26 +++++++++++++++-----------
 2 files changed, 24 insertions(+), 17 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index d3a4c70..b4deeb2 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -17920,8 +17920,8 @@ italic, bold, and bold-italic styles (@file{R}, 
@file{I}, @file{B}, and
 
 The @file{DESC} file contains a series of directives, one per line.
 Except for the @code{charset} directive, which must come last (if at
-all), the order of the lines is not important.  Later entries in the
-file, however, override previous values.
+all), the order of the lines is not important.  If a directive name is
+duplicated, however, later entries in the file override previous ones.
 @cindex comments in device description files
 @cindex device description files, comments
 @kindex #
@@ -18063,7 +18063,7 @@ directive.
 @item unitwidth @var{n}
 @kindex unitwidth
 Quantities in the font description files are in basic units for fonts
-whose point size is @var{n}@tie{}scaled points.
+whose type size is @var{n}@tie{}scaled points.
 
 @item unscaled_charwidths
 @kindex unscaled_charwidths
@@ -18130,12 +18130,15 @@ is not practical for most purposes, but using it 
enables the quantities
 in the font description files to be expressed as integers.}
 
 A font description file has two sections.  The first is a sequence of
-directives;
+directives, and is parsed similarly to the @file{DESC} file described
+above.  Except for the directive names that begin the second section,
+their ordering is immaterial; later directives of the same name override
+earlier ones;
 @cindex comments in font description files
 @cindex font description files, comments
 @kindex #
-it can contain comments, which start with the @samp{#} character and
-extend to the end of a line.  Empty lines are ignored in both sections.
+and the same comment syntax is supported.  Empty lines are ignored in
+both sections.
 
 @table @code
 @item name @var{f}
diff --git a/man/groff_font.5.man b/man/groff_font.5.man
index a54885e..5d60e57 100644
--- a/man/groff_font.5.man
+++ b/man/groff_font.5.man
@@ -107,9 +107,9 @@ which must come last
 (if at all),
 the order of the lines is not important.
 .
-Later entries in the file,
+If a directive name is duplicated,
 however,
-override previous values.
+later entries in the file override previous ones.
 .
 Comments start with the
 .RB \[lq] # \[rq]
@@ -425,7 +425,7 @@ output devices use this directive.
 .TP
 .BI unitwidth\~ n
 Quantities in the font description files are in basic units for fonts
-whose point size is
+whose type size is
 .IR n \~scaled
 points.
 .
@@ -551,11 +551,15 @@ expressed as integers.)
 .P
 A font description file has two sections.
 .
-The first is a sequence of directives;
-it can contain comments,
-which start with the
-.RB \[lq] # \[rq]
-character and extend to the end of a line.
+The first is a sequence of directives,
+and is parsed similarly to the
+.I DESC
+file described above.
+.
+Except for the directive names that begin the second section,
+their ordering is immaterial;
+later directives of the same name override earlier ones;
+and the same comment syntax is supported.
 .
 Empty lines are ignored in both sections.
 .
@@ -979,9 +983,9 @@ and device-independent output format.
 .
 .
 .P
-Section \[lq]See also\[rq] of
-.MR groff @MAN1EXT@
-lists utilities available for preparing font files in a variety of
+.MR groff @MAN1EXT@ ,
+subsection \[lq]Utilities\[rq],
+lists programs available for preparing font files in a variety of
 formats for use with
 .I groff
 output drivers.