[groff] 08/31: [man pages]: Improve several pages' Files section.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 7347f57da445c19258a7d05297471acc7dd354b8
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Jan 29 22:00:37 2022 +1100

    [man pages]: Improve several pages' Files section.
    
    * man/groff_out.5.man: Drop reference to groff source tree.  Pointing
      people to the source code as a "definitive specification" means there
      _is_ no definitive specification.  If this page were written better,
      maybe it could become one.  So many to-do list items...
    
    * src/devices/grodvi/grodvi.1.man:
    * src/devices/grolbp/grolbp.1.man:
    * src/devices/grolj4/grolj4.1.man:
    * src/devices/gropdf/gropdf.1.man:
    * src/devices/grops/grops.1.man:
    * src/devices/grotty/grotty.1.man: Convert noun phrase sentence
      fragments to sentences.  Improve and parallelize descriptions of
      device and font description files as well as device-supporting macro
      files.  Document that "troffrc" loads the latter automatically.
    
    * src/devices/grolj4/grolj4.1.man:
    * src/devices/grolj4/lj4_font.5.man:
    * src/utils/hpftodit/hpftodit.1.man: Add descriptions of files in
      'generate' subdirectory of device font directory.
    
    * src/devices/grolj4/grolj4.1.man: Document lj4.tmac file.
    
    * src/devices/gropdf/gropdf.1.man: Expand description of U-* font
      description files and how they contrast with those lacking the prefix.
    
    * src/devices/gropdf/gropdf.1.man: Expand descriptions of Foundry file.
      Document pdfpic.tmac here (briefly).
    
    * src/devices/gropdf/gropdf.1.man:
    * src/devices/grops/grops.1.man: Expand descriptions of "download" and
      text.enc files.
    
    * src/devices/grops/grops.1.man: Document generate/textmap.  Expand
      description of psold.tmac.  Recast discussion of temporary files.
    
    * src/preproc/grn/grn.1.man: Sync DESC description with groff_out(5).
    
    * src/utils/afmtodit/afmtodit.1.man: Align file descriptions with
      grops(1).
    
    * src/utils/hpftodit/hpftodit.1.man: Align file descriptions with
      grolj4(1).
    
    * src/utils/tfmtodit/tfmtodit.1.man: Align file descriptions with
      grodvi(1).
    
    Generally:
    * Use hyphenation control and hyphenless break escape sequences to keep
      file name literals from hyphenating or causing 'break' warnings.
---
 man/groff_font.5.man              |  7 ++-
 man/groff_out.5.man               | 18 +-------
 src/devices/grodvi/grodvi.1.man   | 25 ++++++++---
 src/devices/grolbp/grolbp.1.man   | 23 +++++++---
 src/devices/grolj4/grolj4.1.man   | 67 +++++++++++++++++++++++----
 src/devices/grolj4/lj4_font.5.man | 46 ++++++++++++++++---
 src/devices/gropdf/gropdf.1.man   | 86 ++++++++++++++++++++++++++---------
 src/devices/grops/grops.1.man     | 92 ++++++++++++++++++++++++++-----------
 src/devices/grotty/grotty.1.man   | 95 +++++++++++++++++++++------------------
 src/preproc/grn/grn.1.man         |  6 +--
 src/roff/troff/troff.1.man        | 12 ++---
 src/utils/afmtodit/afmtodit.1.man | 27 ++++++++---
 src/utils/hpftodit/hpftodit.1.man | 47 ++++++++++++++++---
 src/utils/tfmtodit/tfmtodit.1.man | 15 ++++---
 14 files changed, 401 insertions(+), 165 deletions(-)

diff --git a/man/groff_font.5.man b/man/groff_font.5.man
index 8567c2f3..66bba570 100644
--- a/man/groff_font.5.man
+++ b/man/groff_font.5.man
@@ -1003,15 +1003,14 @@ Most kerning pairs should have a negative value
 .\" ====================================================================
 .
 .TP
-.IR @FONTDIR@/dev name /DESC
+.IR \%@FONTDIR@/\:\%dev name /\:DESC
 describes the output device
 .IR name .
 .
 .
 .TP
-.IR @FONTDIR@/dev name / F
-describes the font known to
-.I \%@g@troff
+.IR \%@FONTDIR@/\:\%dev name / F
+describes the font known
 .RI as\~ F
 on device
 .IR name .
diff --git a/man/groff_out.5.man b/man/groff_out.5.man
index f6c5f900..dcfd58b3 100644
--- a/man/groff_out.5.man
+++ b/man/groff_out.5.man
@@ -1825,24 +1825,10 @@ are documented in
 .\" ====================================================================
 .
 .TP
-.IR @FONTDIR@/dev name /DESC
-Device description file for device
+.IR \%@FONTDIR@/\:\%dev name /\:DESC
+describes the output device
 .IR name .
 .
-.TP
-.I src/libs/libdriver/input.cpp
-Defines the parser and postprocessor for the
-.I intermediate
-.IR output .
-.
-It is located relative to the top directory of the
-.I groff
-source tree.
-.
-This parser is the definitive specification of the
-.I groff intermediate output
-format.
-.
 .
 .\" ====================================================================
 .SH Authors
diff --git a/src/devices/grodvi/grodvi.1.man b/src/devices/grodvi/grodvi.1.man
index 2248a25d..f4800f60 100644
--- a/src/devices/grodvi/grodvi.1.man
+++ b/src/devices/grodvi/grodvi.1.man
@@ -480,24 +480,37 @@ and
 .
 .TP
 .I \%@FONTDIR@/\:\%devdvi/\:DESC
-Device description file.
+describes the
+.B dvi
+output device.
 .
 .
 .TP
 .IR \%@FONTDIR@/\:\%devdvi/ F
-Font description file for font
-.IR F .
+describes the font known
+.RI as\~ F
+on device
+.BR dvi .
 .
 .
 .TP
 .I \%@MACRODIR@/\:dvi\:.tmac
-Macros for use with
-.IR grodvi .
+defines macros for use with the
+.B dvi
+output device.
+.
+It is automatically loaded by
+.I troffrc
+when the
+.B dvi
+output device is selected.
 .
 .
 .TP
 .I \%@MACRODIR@/\:ec\:.tmac
-Macros to switch to EC fonts.
+invokes requests to employ the EC
+(rather than CM)
+fonts.
 .
 .
 .\" ====================================================================
diff --git a/src/devices/grolbp/grolbp.1.man b/src/devices/grolbp/grolbp.1.man
index 9843a63f..04771433 100644
--- a/src/devices/grolbp/grolbp.1.man
+++ b/src/devices/grolbp/grolbp.1.man
@@ -426,17 +426,30 @@ and
 .
 .TP
 .I \%@FONTDIR@/\:\%devlbp/\:DESC
-Device description file.
+describes the
+.B lbp
+output device.
+.
 .
 .TP
 .IR \%@FONTDIR@/\:\%devlbp/ F
-Font description file for font
-.IR F .
+describes the font known
+.RI as\~ F
+on device
+.BR lbp .
+.
 .
 .TP
 .I \%@MACRODIR@/\:lbp\:.tmac
-Macros for use with
-.BR grolbp .
+defines macros for use with the
+.B lbp
+output device.
+.
+It is automatically loaded by
+.I troffrc
+when the
+.B lbp
+output device is selected.
 .
 .
 .\" ====================================================================
diff --git a/src/devices/grolj4/grolj4.1.man b/src/devices/grolj4/grolj4.1.man
index 01436378..01e110a2 100644
--- a/src/devices/grolj4/grolj4.1.man
+++ b/src/devices/grolj4/grolj4.1.man
@@ -200,30 +200,81 @@ and
 .MR groff_font @MAN5EXT@ .
 .
 .
+.br
 .ne 3v \" Keep section heading and paragraph tag together.
 .\" ====================================================================
 .SH Files
 .\" ====================================================================
 .
 .TP
-.I @FONTDIR@/devlj4/DESC
-Device description file.
+.I \%@FONTDIR@/\:\%devlj4/\:DESC
+describes the
+.B lj4
+output device.
+.
 .
 .TP
-.IR @FONTDIR@/devlj4/ F
-Font description file for font
-.IR F .
+.IR \%@FONTDIR@/\:\%devlj4/ F
+describes the font known
+.RI as\~ F
+on device
+.BR lj4 .
+.
 .
 .TP
-.I @MACRODIR@/lj4.tmac
-Macros for use with
-.BR grolj4 .
+.I \%@FONTDIR@/\:\%devlj4/\:\%generate/\:\%Makefile
+is a
+.MR make 1
+script that uses
+.MR hpftodit @MAN1EXT@
+to prepare the foregoing font description files from HP TFM data;
+in can be used to regenerate the
+.I groff
+font descriptions in the event the TFM files are updated.
+.
+.
+.TP
+.I \%@FONTDIR@/\:\%devlj4/\:\%generate/\:\%special\:.awk
+is an
+.MR awk 1
+script that corrects the Intellifont-based height metrics for several
+glyphs in the
+.B S
+(special) font for TrueType CG Times used in the HP LaserJet\~4000 and
+later.
+.
+.
+.TP
+.I \%@FONTDIR@/\:\%devlj4/\:\%generate/\:\%special\:.map
+.TQ
+.I \%@FONTDIR@/\:\%devlj4/\:\%generate/\:\%symbol\:.map
+.TQ
+.I \%@FONTDIR@/\:\%devlj4/\:\%generate/\:text\:.map
+.TQ
+.I \%@FONTDIR@/\:\%devlj4/\:\%generate/\:\%wingdings.map
+map MSL indices and HP Unicode Private Use Area assignments to
+.I groff
+special character identifiers.
+.
+.
+.TP
+.I \%@MACRODIR@/\:lj4\:.tmac
+defines macros for use with the
+.B lj4
+output device.
+.
+It is automatically loaded by
+.I troffrc
+when the
+.B lj4
+output device is selected.
 .
 .
 .\" ====================================================================
 .SH Bugs
 .\" ====================================================================
 .
+.\" XXX: What does this mean?  The period/full stop glyph?  Flyspecks?
 Small dots.
 .
 .
diff --git a/src/devices/grolj4/lj4_font.5.man 
b/src/devices/grolj4/lj4_font.5.man
index cbd21177..75763ba6 100644
--- a/src/devices/grolj4/lj4_font.5.man
+++ b/src/devices/grolj4/lj4_font.5.man
@@ -234,19 +234,53 @@ and one for more recent TFM files.
 .
 .TP
 .I \%@FONTDIR@/\:devlj4/\:DESC
-device description file
+describes the
+.B lj4
+output device.
 .
 .
 .TP
 .IR \%@FONTDIR@/\:devlj4/\: F
-font description file for font
-.I F
+describes the font known
+.RI as\~ F
+on device
+.BR lj4 .
 .
 .
 .TP
-.I \%@FONTDIR@/\:devlj4/\:generate
-corrects Intellifont-based height metrics for several glyphs in the
-special font for TrueType CG Times (LaserJet\~4000 and later).
+.I \%@FONTDIR@/\:\%devlj4/\:\%generate/\:\%Makefile
+is a
+.MR make 1
+script that uses
+.MR hpftodit @MAN1EXT@
+to prepare the foregoing font description files from HP TFM data;
+in can be used to regenerate the
+.I groff
+font descriptions in the event the TFM files are updated.
+.
+.
+.TP
+.I \%@FONTDIR@/\:\%devlj4/\:\%generate/\:\%special\:.awk
+is an
+.MR awk 1
+script that corrects the Intellifont-based height metrics for several
+glyphs in the
+.B S
+(special) font for TrueType CG Times used in the HP LaserJet\~4000 and
+later.
+.
+.
+.TP
+.I \%@FONTDIR@/\:\%devlj4/\:\%generate/\:\%special\:.map
+.TQ
+.I \%@FONTDIR@/\:\%devlj4/\:\%generate/\:\%symbol\:.map
+.TQ
+.I \%@FONTDIR@/\:\%devlj4/\:\%generate/\:text\:.map
+.TQ
+.I \%@FONTDIR@/\:\%devlj4/\:\%generate/\:\%wingdings.map
+map MSL indices and HP Unicode Private Use Area assignments to
+.I groff
+special character identifiers.
 .
 .
 .\" ====================================================================
diff --git a/src/devices/gropdf/gropdf.1.man b/src/devices/gropdf/gropdf.1.man
index ca35c3a9..25b9c022 100644
--- a/src/devices/gropdf/gropdf.1.man
+++ b/src/devices/gropdf/gropdf.1.man
@@ -1495,41 +1495,83 @@ see
 .\" ====================================================================
 .
 .TP
-.I @FONTDIR@/devpdf/DESC
-Device description file.
+.I \%@FONTDIR@/\:\%devpdf/\:DESC
+describes the
+.B pdf
+output device.
+.
+.
+.TP
+.IR \%@FONTDIR@/\:\%devpdf/ F
+describes the font known
+.RI as\~ F
+on device
+.BR pdf .
+.
 .
 .TP
-.IR @FONTDIR@/devpdf/ F
-Font description file for font\~\c
-.IR F .
+.IR \%@FONTDIR@/\:\%devpdf/ U\-F
+describes the font
+from the URW foundry
+(rather than the Adobe default)
+known
+.RI as\~ F
+on device
+.BR pdf .
+.
 .
 .TP
-.IR @FONTDIR@/devpdf/ U\-F
-Font description file for font\~\c
-.I F
-(using foundry\~\c
-.I U
-rather than the default foundry).
+.I \%@FONTDIR@/\:\%devpdf/\%download
+lists fonts available for embedding within the PDF document
+(by analogy to the
+.B ps
+device's downloadable font support).
 .
+.
+.\" XXX: Why are we shipping this but not BuildFoundries.pl?
 .TP
-.I @FONTDIR@/devpdf/download
-List of downloadable fonts.
+.I \%@FONTDIR@/\:\%devpdf/\%Foundry
+is a data file used by the
+.I groff
+build system to locate PostScript Type\~1 fonts.
+.
 .
 .TP
-.I @FONTDIR@/devpdf/Foundry
-A Perl script used during install to locate suitable fonts.
+.I \%@FONTDIR@/\:\%devpdf/\:enc/\:\%text\:.enc
+describes the encoding scheme used by most PostScript Type\~1 fonts;
+the
+.B \%encoding
+directive of
+font description files for the
+.B pdf
+device refers to it.
+.
 .
 .TP
-.I @FONTDIR@/devpdf/enc/text.enc
-Encoding used for text fonts.
+.I \%@MACRODIR@/\:pdf\:.tmac
+defines macros for use with the
+.B pdf
+output device.
+.
+It is automatically loaded by
+.I troffrc
+when the
+.B pdf
+output device is selected.
+.
 .
 .TP
-.I @MACRODIR@/pdf.tmac
-Macros for use with
-.BR gropdf ;
-automatically loaded by
-.BR troffrc .
+.I \%@MACRODIR@/\:pdfpic\:.tmac
+defines the
+.B PDFPIC
+macro for embedding images in a document;
+see
+.MR groff_tmac @MAN5EXT@ .
 .
+It is automatically loaded by
+.I troffrc .
+.\"
+.\"
 .\" .TP
 .\" .B @MACRODIR@/pspic.tmac
 .\" Definition of
diff --git a/src/devices/grops/grops.1.man b/src/devices/grops/grops.1.man
index 3730ae9d..200e54e3 100644
--- a/src/devices/grops/grops.1.man
+++ b/src/devices/grops/grops.1.man
@@ -1555,48 +1555,86 @@ see
 .\" ====================================================================
 .
 .TP
-.I @FONTDIR@/devps/DESC
-Device description file.
+.I \%@FONTDIR@/\:\%devps/\:DESC
+describes the
+.B ps
+output device.
+.
 .
 .TP
-.IR @FONTDIR@/devps/ F
-Font description file for font
-.IR F .
+.IR \%@FONTDIR@/\:\%devps/ F
+describes the font known
+.RI as\~ F
+on device
+.BR ps .
+.
 .
 .TP
-.I @FONTDIR@/devps/download
-List of downloadable fonts.
+.I \%@FONTDIR@/\:\%devps/\:\%download
+lists fonts available for embedding within the PostScript document
+(or download to the device).
+.
 .
 .TP
-.I @FONTDIR@/devps/text.enc
-Encoding used for text fonts.
+.I \%@FONTDIR@/\:\%devps/\:text.enc
+describes the encoding scheme used by most PostScript Type\~1 fonts;
+the
+.B \%encoding
+directive of
+font description files for the
+.B ps
+device refers to it.
+.
 .
 .TP
-.I @MACRODIR@/ps.tmac
-Macros for use with
-.BR grops ;
-automatically loaded by
-.B troffrc
+.I \%@FONTDIR@/\:\%devps/\:\%generate/\:textmap
+maps names in the Adobe Glyph List to
+.I groff
+special character identifiers.
+.
 .
 .TP
-.I @MACRODIR@/pspic.tmac
-Definition of
-.B PSPIC
-macro,
-automatically loaded by
-.IR ps.tmac .
+.I \%@MACRODIR@/\:ps.tmac
+defines macros for use with the
+.B ps
+output device.
+.
+It is automatically loaded by
+.I troffrc
+when the
+.B ps
+output device is selected.
+.
 .
 .TP
-.I @MACRODIR@/psold.tmac
-Macros to disable use of characters not present in older
-PostScript printers (e.g., \[oq]eth\[cq] or \[oq]thorn\[cq]).
+.I \%@MACRODIR@/\:pspic.tmac
+defines the
+.B PSPIC
+macro for embedding images in a document;
+see
+.MR groff_tmac @MAN5EXT@ .
+.
+It is automatically loaded by
+.I troffrc .
+.
 .
 .TP
-.IR /tmp/grops XXXXXX
-Temporary file.
-See
+.I \%@MACRODIR@/psold.tmac
+provides replacement glyphs for text fonts that lack complete coverage
+of the ISO Latin-1 character set;
+using it,
+.I groff
+can produce glyphs like eth (\[Sd]) and thorn (\[Tp]) that older
+PostScript printers do not natively support.
+.
+.
+.P
+.I grops
+creates temporary files using the template
+.RI \[lq] grops XXXXXX\[rq];
+see
 .MR groff @MAN1EXT@
-for details on the location of temporary files.
+for details on their storage location.
 .
 .
 .\" ====================================================================
diff --git a/src/devices/grotty/grotty.1.man b/src/devices/grotty/grotty.1.man
index a46004a2..c1e952ae 100644
--- a/src/devices/grotty/grotty.1.man
+++ b/src/devices/grotty/grotty.1.man
@@ -567,85 +567,92 @@ see subsection \[lq]Legacy output format\[rq] above.
 .\" ====================================================================
 .SH Files
 .\" ====================================================================
-.\"ne 3v \" Keep section heading and paragraph tag together.
 .
 .TP
-.I @FONTDIR@/devascii/DESC
-Device description file for the
+.I \%@FONTDIR@/\:\%devascii/\:DESC
+describes the
 .B ascii
-device.
+output device.
 .
 .
 .TP
-.IR @FONTDIR@/devascii/ F
-Font description file for font
-.I F
-of the
-.B ascii
-device.
+.IR \%@FONTDIR@/\:\%devascii/ F
+describes the font known
+.RI as\~ F
+on device
+.BR ascii .
 .
 .
 .TP
-.I @FONTDIR@/devcp1047/DESC
-Device description file for the
+.I \%@FONTDIR@/\:\%devcp1047/\:DESC
+describes the
 .B cp1047
-device.
+output device.
 .
 .
 .TP
-.IR @FONTDIR@/devcp1047/ F
-Font description file for font
-.I F
-of the
-.B cp1047
-device.
+.IR \%@FONTDIR@/\:\%devcp1047/ F
+describes the font known
+.RI as\~ F
+on device
+.BR cp1047 .
 .
 .
 .TP
-.I @FONTDIR@/devlatin1/DESC
-Device description file for the
+.I \%@FONTDIR@/\:\%devlatin1/\:DESC
+describes the
 .B latin1
-device.
+output device.
 .
 .
 .TP
-.IR @FONTDIR@/devlatin1/ F
-Font description file for font
-.I F
-of the
-.B latin1
-device.
+.IR \%@FONTDIR@/\:\%devlatin1/ F
+describes the font known
+.RI as\~ F
+on device
+.BR latin1 .
 .
 .
 .TP
-.I @FONTDIR@/devutf8/DESC
-Device description file for the
+.I \%@FONTDIR@/\:\%devutf8/\:DESC
+describes the
 .B utf8
-device.
+output device.
 .
 .
 .TP
-.IR @FONTDIR@/devutf8/ F
-Font description file for font
-.I F
-of the
-.B utf8
-device.
+.IR \%@FONTDIR@/\:\%devutf8/ F
+describes the font known
+.RI as\~ F
+on device
+.BR utf8 .
 .
 .
 .TP
-.I @MACRODIR@/tty.tmac
-Macros for use with
-.IR grotty .
+.I \%@MACRODIR@/\:tty\:.tmac
+defines macros for use with the
+.BR ascii ,
+.BR cp1047 ,
+.BR latin1 ,
+and
+.B utf8
+output devices.
+.
+It is automatically loaded by
+.I troffrc
+when any of those output devices is selected.
 .
 .
 .TP
-.I @MACRODIR@/tty\-char.tmac
-Additional character definitions for use with
-.IR grotty .
+.I \%@MACRODIR@/\:tty\-char\:.tmac
+defines fallback characters for use with
+.I grotty.
+.
+.MR nroff @MAN1EXT@
+loads it automatically.
 .
 .
-.\" The following no longer seems to be true; an inspection of the
+.\" XXX: The following no longer seems to be true; an inspection of the
 .\" font/*/dev*.am files suggests no evidence of it, at any rate.
 .\".P
 .\"Note that on EBCDIC hosts,
diff --git a/src/preproc/grn/grn.1.man b/src/preproc/grn/grn.1.man
index c1aa3beb..f740c4de 100644
--- a/src/preproc/grn/grn.1.man
+++ b/src/preproc/grn/grn.1.man
@@ -918,9 +918,9 @@ even when followed by a character other than space or 
newline.
 .\" ====================================================================
 .
 .TP
-.IR \%@FONTDIR@/\:dev name /\:DESC
-device description file for output driver
-.I name
+.IR \%@FONTDIR@/\:\%dev name /\:DESC
+describes the output device
+.IR name .
 .
 .
 .\" ====================================================================
diff --git a/src/roff/troff/troff.1.man b/src/roff/troff/troff.1.man
index 5cd1129e..bf725987 100644
--- a/src/roff/troff/troff.1.man
+++ b/src/roff/troff/troff.1.man
@@ -822,7 +822,7 @@ see
 .\" ====================================================================
 .
 .TP
-.I @MACRODIR@/troffrc
+.I \%@MACRODIR@/\:\%troffrc
 is an initialization macro file loaded before any macro packages
 specified with
 .B \-m
@@ -830,7 +830,7 @@ options.
 .
 .
 .TP
-.I @MACRODIR@/troffrc\-end
+.I \%@MACRODIR@/\:\%troffrc\-end
 is an initialization macro file loaded after all macro packages
 specified with
 .B \-m
@@ -838,21 +838,21 @@ options.
 .
 .
 .TP
-.IR @MACRODIR@/ name .tmac
+.IR \%@MACRODIR@/\: name \:.tmac
 .TQ
-.IR @MACRODIR@/tmac. name
+.IR \%@MACRODIR@/\:tmac\:. name
 are macro files distributed with
 .IR groff .
 .
 .
 .TP
-.IR @FONTDIR@/dev name /DESC
+.IR \%@FONTDIR@/\:\%dev name /\:DESC
 describes the output device
 .IR name .
 .
 .
 .TP
-.IR @FONTDIR@/dev name / F
+.IR \%@FONTDIR@/\:\%dev name / F
 describes the font
 .I F
 of device
diff --git a/src/utils/afmtodit/afmtodit.1.man 
b/src/utils/afmtodit/afmtodit.1.man
index b9fc749f..ba2468c5 100644
--- a/src/utils/afmtodit/afmtodit.1.man
+++ b/src/utils/afmtodit/afmtodit.1.man
@@ -435,28 +435,41 @@ Don't use the built-in Adobe Glyph List.
 .
 .TP
 .I \%@FONTDIR@/\:\%devps/\:DESC
-Device description file.
+describes the
+.B ps
+output device.
 .
 .
 .TP
-.IR \%@FONTDIR@/\:\%devps/\: F
-Font description file for font
-.IR F .
+.IR \%@FONTDIR@/\:\%devps/ F
+describes the font known
+.RI as\~ F
+on device
+.BR ps .
 .
 .
 .TP
 .I \%@FONTDIR@/\:\%devps/\:\%download
-List of downloadable fonts.
+lists fonts available for embedding within the PostScript document
+(or download to the device).
 .
 .
 .TP
 .I \%@FONTDIR@/\:\%devps/\:text.enc
-Encoding used for text fonts.
+describes the encoding scheme used by most PostScript Type\~1 fonts;
+the
+.B \%encoding
+directive of
+font description files for the
+.B ps
+device refers to it.
 .
 .
 .TP
 .I \%@FONTDIR@/\:\%devps/\:\%generate/\:textmap
-Standard mapping.
+maps names in the Adobe Glyph List to
+.I groff
+special character identifiers.
 .
 .
 .\" ====================================================================
diff --git a/src/utils/hpftodit/hpftodit.1.man 
b/src/utils/hpftodit/hpftodit.1.man
index 90a4c59d..81a03e0e 100644
--- a/src/utils/hpftodit/hpftodit.1.man
+++ b/src/utils/hpftodit/hpftodit.1.man
@@ -392,18 +392,53 @@ the search order is reversed.
 .
 .TP
 .I \%@FONTDIR@/\:\%devlj4/\:DESC
-device description file
+describes the
+.B lj4
+output device.
 .
 .
 .TP
-.IR \%@FONTDIR@/\:\%devlj4/\: F
-font description file for font
-.I F
+.IR \%@FONTDIR@/\:\%devlj4/ F
+describes the font known
+.RI as\~ F
+on device
+.BR lj4 .
 .
 .
 .TP
-.IR \%@FONTDIR@/\:\%devlj4/\:\%generate/\: * .map
-symbol mapping files
+.I \%@FONTDIR@/\:\%devlj4/\:\%generate/\:\%Makefile
+is a
+.MR make 1
+script that uses
+.MR hpftodit @MAN1EXT@
+to prepare the foregoing font description files from HP TFM data;
+in can be used to regenerate the
+.I groff
+font descriptions in the event the TFM files are updated.
+.
+.
+.TP
+.I \%@FONTDIR@/\:\%devlj4/\:\%generate/\:\%special\:.awk
+is an
+.MR awk 1
+script that corrects the Intellifont-based height metrics for several
+glyphs in the
+.B S
+(special) font for TrueType CG Times used in the HP LaserJet\~4000 and
+later.
+.
+.
+.TP
+.I \%@FONTDIR@/\:\%devlj4/\:\%generate/\:\%special\:.map
+.TQ
+.I \%@FONTDIR@/\:\%devlj4/\:\%generate/\:\%symbol\:.map
+.TQ
+.I \%@FONTDIR@/\:\%devlj4/\:\%generate/\:text\:.map
+.TQ
+.I \%@FONTDIR@/\:\%devlj4/\:\%generate/\:\%wingdings.map
+map MSL indices and HP Unicode Private Use Area assignments to
+.I groff
+special character identifiers.
 .
 .
 .\" ====================================================================
diff --git a/src/utils/tfmtodit/tfmtodit.1.man 
b/src/utils/tfmtodit/tfmtodit.1.man
index 80942737..bfb6a460 100644
--- a/src/utils/tfmtodit/tfmtodit.1.man
+++ b/src/utils/tfmtodit/tfmtodit.1.man
@@ -270,13 +270,18 @@ directive to the font description file.
 .\" ====================================================================
 .
 .TP
-.I @FONTDIR@/devdvi/DESC
-Device description file.
+.I \%@FONTDIR@/\:\%devdvi/\:DESC
+describes the
+.B dvi
+output device.
+.
 .
 .TP
-.IR @FONTDIR@/devdvi/ F
-Font description file for font
-.IR F .
+.IR \%@FONTDIR@/\:\%devdvi/ F
+describes the font known
+.RI as\~ F
+on device
+.BR dvi .
 .
 .
 .\" ====================================================================