[groff] 15/15: [docs]: Clarify font, device description formats.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 67c78a92cf161d5bbb92d46ccaf98cce645ba555
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Sep 17 19:13:43 2021 +1000

    [docs]: Clarify font, device description formats.
    
    * Front characterization of `DESC` file content as "directives".
    * Note `DESC` file comment syntax.
    * Be even more clear about non-recursivity of the file name form of an
      argument to `papersize`.
    * Fix missing comma.
    * Update Texinfo concept index entries.
---
 doc/groff.texi       | 22 ++++++++++++++--------
 man/groff_font.5.man | 18 +++++++++++-------
 2 files changed, 25 insertions(+), 15 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 92a7502..e03ee94 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -17865,10 +17865,15 @@ italic, bold, and bold-italic styles (@file{R}, 
@file{I}, @file{B}, and
 @cindex format of font description file
 @pindex DESC@r{ file format}
 
-The @file{DESC} file can contain the following types of 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.  Empty lines are ignored.
+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.
+@cindex comments in device description files
+@cindex device description files, comments
+@kindex #
+Comments start with the @samp{#} character and extend to the end of a
+line.  Empty lines are ignored.
 
 @table @code
 @item family @var{fam}
@@ -17928,7 +17933,8 @@ format.
 
 Finally, the argument can be a file name (e.g., @file{/etc/papersize});
 if the file can be opened, GNU @code{troff} reads the first line and
-attempts to match the above forms.  No comment syntax is supported.
+attempts to match either of the other forms.  No comment syntax is
+supported.
 
 More than one argument can be specified; GNU @code{troff} scans from
 left to right and uses the first valid paper specification.
@@ -18071,7 +18077,7 @@ 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; empty lines are ignored in
-both.  The first section is a sequence of lines each containing a
+both.  The first section is a sequence of lines, each containing a
 sequence of space-delimited words; the first word in the line is a key,
 and subsequent words associate a value with that key.
 
@@ -18115,8 +18121,8 @@ Other directives are ignored by GNU @code{troff} but 
may be used by
 postprocessors to store arbitrary information about the font in the
 file.
 
-@cindex comments in font files
-@cindex font files, comments
+@cindex comments in font description files
+@cindex font description files, comments
 @kindex #
 The first section can contain comments, which start with the @samp{#}
 character and extend to the end of a line.
diff --git a/man/groff_font.5.man b/man/groff_font.5.man
index c5b9436..d662b04 100644
--- a/man/groff_font.5.man
+++ b/man/groff_font.5.man
@@ -97,10 +97,10 @@ respectively).
 .
 The
 .I DESC
-file can contain the following types of line as shown below.
+file contains a series of directives,
+one per line.
 .
-Except
-for the
+Except for the
 .B charset
 directive,
 which must come last
@@ -111,6 +111,10 @@ Later entries in the file,
 however,
 override previous values.
 .
+Comments start with the
+.RB \[lq] # \[rq]
+character and extend to the end of a line.
+.
 Empty lines are ignored.
 .
 .
@@ -249,7 +253,7 @@ the argument can be a file name
 .IR /etc/papersize );
 if the file can be opened,
 .I \%@g@troff
-reads the first line and attempts to match the above forms.
+reads the first line and attempts to match either of the other forms.
 .
 No comment syntax is supported.
 .
@@ -545,8 +549,8 @@ expressed as integers.)
 A font description file has two sections;
 empty lines are ignored in both.
 .
-The first section is a sequence of lines each containing a sequence of
-space-delimited words;
+The first section is a sequence of lines,
+each containing a sequence of space-delimited words;
 the first word in the line is a key,
 and subsequent words associate a value with that key.
 .
@@ -625,7 +629,7 @@ about the font in the file.
 .P
 The first section can contain comments,
 which start with the
-.B #
+.RB \[lq] # \[rq]
 character and extend to the end of a line.
 .
 .