[groff] 11/20: man pages: Make style fixes.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit c7888b059f502e7ff1eafc75452bdbf05cebf9da
Author: G. Branden Robinson <address@hidden>
Date:   Fri Nov 9 11:28:11 2018 -0500

    man pages: Make style fixes.
    
        * src/preproc/eqn/neqn.1.man:
        * src/utils/lkbib/lkbib.1.man:
        * src/utils/lookbib/lookbib.1.man:
        * src/utils/pfbtops/pfbtops.1.man:
        * src/utils/xtotroff/xtotroff.1.man:
          + Set command names in italics (as works of software), not
            bold.
    
        * src/preproc/eqn/neqn.1.man:
          + Convert Synopsis section to use .SY/.YS synopsis macros.
    
        * src/utils/lkbib/lkbib.1.man:
        * src/utils/lookbib/lookbib.1.man:
        * src/utils/pfbtops/pfbtops.1.man:
        * src/utils/xtotroff/xtotroff.1.man:
          + Set (fixed portions of) filenames in italics, not bold.
          + Tweak description of (help and) version flags' behavior;
            "print" can be ambiguous in typesetting contexts.
    
        * src/utils/pfbtops/pfbtops.1.man:
        * src/utils/xtotroff/xtotroff.1.man:
          + Document --help option.
    
        * src/utils/lkbib/lkbib.1.man:
        * src/utils/lookbib/lookbib.1.man:
          + Use the "standard ellipsis" documented in groff_man(7).
          + Set variable portions of filenames in roman when not used in
            isolation.
          + Sort option descriptions in Options section in alphabetical
            order.
    
        * src/utils/lkbib/lkbib.1.man:
          + Set environment variable names in italics, not small bold.
    
        * src/utils/pfbtops/pfbtops.1.man:
          + Expand PFB initialism (Printer Font Binary), to aid
            comprehension and man -k indexing.
          + Use hyphens instead of underscores in option argument names;
                they are prose, not C identifiers.
    
        * src/utils/xtotroff/xtotroff.1.man:
          + Use hyphens instead of StudlyCaps in option argument names;
            they are prose, not C identifiers.
          + Add man page cross references to first mentions of groff and
            troff; also add them to the See Also section.
          + Expand XLFD initialism to aid comprehension.
          + Set off XLFD example inside relative indent and example
            macros.
          + Escape hyphens in XLFD example.
          + Double-quote (instead of single-quoting) the names of the
            supported encodings, since they are used as strings; also
            escape the hyphens therein, as they are subsets of an XLFD,
            not ordinary prose (cf. "ISO 8859-1" and "iso8859\-1").
    
        * src/utils/lkbib/lkbib.1.man:
        * src/utils/lookbib/lookbib.1.man:
        * src/utils/tfmtodit/tfmtodit.1.man:
        * src/utils/xtotroff/xtotroff.1.man:
          + Consistently put two empty requests between paragraph
            macros.
    
    Signed-off-by: G. Branden Robinson <address@hidden>
---
 src/preproc/eqn/neqn.1.man        | 16 +++++------
 src/utils/lkbib/lkbib.1.man       | 55 +++++++++++++++++++++++---------------
 src/utils/lookbib/lookbib.1.man   | 31 ++++++++++++++--------
 src/utils/pfbtops/pfbtops.1.man   | 44 ++++++++++++++++--------------
 src/utils/tfmtodit/tfmtodit.1.man |  1 +
 src/utils/xtotroff/xtotroff.1.man | 56 ++++++++++++++++++++++++---------------
 6 files changed, 121 insertions(+), 82 deletions(-)

diff --git a/src/preproc/eqn/neqn.1.man b/src/preproc/eqn/neqn.1.man
index 3deb0f5..4381f0a 100644
--- a/src/preproc/eqn/neqn.1.man
+++ b/src/preproc/eqn/neqn.1.man
@@ -29,18 +29,18 @@
 .SH SYNOPSIS
 .\" ====================================================================
 .
-.B @address@hidden
address@hidden@eqn options]
+.SY @address@hidden
+.RI [ @address@hidden ]
+.YS
 .
 .
 .\" ====================================================================
 .SH DESCRIPTION
 .\" ====================================================================
 .
-The
-.B @address@hidden
-program is actually just a shell script which invokes the
-.BR @address@hidden (@MAN1EXT@)
+.I @address@hidden
+invokes the
+.IR @address@hidden (@MAN1EXT@)
 command with the
 .B ascii
 output device.
@@ -48,7 +48,7 @@ output device.
 .
 .LP
 Note that
-.B @address@hidden
+.I @address@hidden
 does not support low-resolution, typewriter-like devices (although it
 may work adequately for very simple input).
 .
@@ -57,7 +57,7 @@ may work adequately for very simple input).
 .SH "SEE ALSO"
 .\" ====================================================================
 .
-.BR @address@hidden (@MAN1EXT@)
+.IR @address@hidden (@MAN1EXT@)
 .
 .
 .\" Local Variables:
diff --git a/src/utils/lkbib/lkbib.1.man b/src/utils/lkbib/lkbib.1.man
index e614adb..d4213a4 100644
--- a/src/utils/lkbib/lkbib.1.man
+++ b/src/utils/lkbib/lkbib.1.man
@@ -53,29 +53,29 @@ lkbib \- search bibliographic databases
 .SH DESCRIPTION
 .\" ====================================================================
 .
-.B lkbib
+.I lkbib
 searches bibliographic databases for references that contain the keys
-.IR key \|.\|.\|.\&
-and prints any references found on the standard output.
+.I key
+\&.\|.\|.\& and prints any references found on the standard output.
 .
-.B lkbib
+.I lkbib
 will search any databases given by
 .B \-p
 options, and then a default database.
 .
 The default database is taken from the
-.SB REFER
+.I REFER
 environment variable if it is set,
 otherwise it is
-.BR @DEFAULT_INDEX@ .
+.IR @DEFAULT_INDEX@ .
 .
 For each database
 .I filename
 to be searched,
 if an index
-.IB filename @INDEX_SUFFIX@
+.RI filename @INDEX_SUFFIX@
 created by
-.BR @address@hidden (@MAN1EXT@)
+.IR @address@hidden (@MAN1EXT@)
 exists, then it will be searched instead;
 each index can cover multiple databases.
 .
@@ -88,8 +88,16 @@ Whitespace is permitted between a command-line option and 
its argument.
 .
 .
 .TP
-.B \-v
-Print the version number.
+.B \-\-help
+Display a usage message and exit.
+.
+.
+.TP
+.BI \-i string
+When searching files for which no index exists,
+ignore the contents of fields whose names are in
+.IR string .
+.
 .
 .TP
 .BI \-p filename
@@ -100,11 +108,6 @@ Multiple
 .B \-p
 options can be used.
 .
-.TP
-.BI \-i string
-When searching files for which no index exists,
-ignore the contents of fields whose names are in
-.IR string .
 .
 .TP
 .BI \-t n
@@ -117,12 +120,19 @@ Initially
 is\~6.
 .
 .
+.TP
+.B \-v
+.TQ
+.B \-\-version
+Display version information and exit.
+.
+.
 .\" ====================================================================
 .SH ENVIRONMENT
 .\" ====================================================================
 .
 .TP
-.SB REFER
+.I REFER
 Default database.
 .
 .
@@ -131,22 +141,23 @@ Default database.
 .\" ====================================================================
 .
 .TP
-.B @DEFAULT_INDEX@
+.I @DEFAULT_INDEX@
 Default database to be used if the
-.SB REFER
+.I REFER
 environment variable is not set.
 .
+.
 .TP
-.IB filename @INDEX_SUFFIX@
+.RI filename @INDEX_SUFFIX@
 Index files.
 .
 .
 .\" ====================================================================
 .SH "SEE ALSO"
 .\" ====================================================================
-.BR @address@hidden (@MAN1EXT@),
-.BR @address@hidden (@MAN1EXT@),
-.BR @address@hidden (@MAN1EXT@)
+.IR @address@hidden (@MAN1EXT@),
+.IR @address@hidden (@MAN1EXT@),
+.IR @address@hidden (@MAN1EXT@)
 .
 .
 .\" Local Variables:
diff --git a/src/utils/lookbib/lookbib.1.man b/src/utils/lookbib/lookbib.1.man
index e64dafb..b395226 100644
--- a/src/utils/lookbib/lookbib.1.man
+++ b/src/utils/lookbib/lookbib.1.man
@@ -51,13 +51,13 @@
 .SH DESCRIPTION
 .\" ====================================================================
 .
-.B @address@hidden
+.I @address@hidden
 prints a prompt on the standard error (unless the standard input is not
 a terminal),
 reads from the standard input a line containing a set of keywords,
 searches the bibliographic databases
-.IR filename \|.\|.\|.\&
-for references containing those keywords,
+.I filename
+\&.\|.\|.\& for references containing those keywords,
 prints any references found on the standard output,
 and repeats this process until the end of input.
 .
@@ -65,9 +65,9 @@ For each database
 .I filename
 to be searched,
 if an index
-.IB filename @INDEX_SUFFIX@
+.RI filename @INDEX_SUFFIX@
 created by
-.BR @address@hidden (@MAN1EXT@)
+.IR @address@hidden (@MAN1EXT@)
 exists, then it will be searched instead;
 each index can cover multiple databases.
 .
@@ -80,8 +80,9 @@ Whitespace is permitted between a command-line option and its 
argument.
 .
 .
 .TP
-.B \-v
-Print the version number.
+.B \-\-help
+Display a usage message and exit.
+.
 .
 .TP
 .BI \-i string
@@ -89,6 +90,7 @@ When searching files for which no index exists,
 ignore the contents of fields whose names are in
 .IR string .
 .
+.
 .TP
 .BI \-t n
 Only require the first
@@ -99,21 +101,28 @@ Initially
 is\~6.
 .
 .
+.TP
+.B \-v
+.TQ
+.B \-\-version
+Display version information and exit.
+.
+.
 .\" ====================================================================
 .SH FILES
 .\" ====================================================================
 .
 .TP
-.IB filename @INDEX_SUFFIX@
+.RI filename @INDEX_SUFFIX@
 Index files.
 .
 .
 .\" ====================================================================
 .SH "SEE ALSO"
 .\" ====================================================================
-.BR @address@hidden (@MAN1EXT@),
-.BR lkbib (@MAN1EXT@),
-.BR @address@hidden (@MAN1EXT@)
+.IR @address@hidden (@MAN1EXT@),
+.IR lkbib (@MAN1EXT@),
+.IR @address@hidden (@MAN1EXT@)
 .
 .
 .\" Local Variables:
diff --git a/src/utils/pfbtops/pfbtops.1.man b/src/utils/pfbtops/pfbtops.1.man
index e6512b1..8f90ff6 100644
--- a/src/utils/pfbtops/pfbtops.1.man
+++ b/src/utils/pfbtops/pfbtops.1.man
@@ -1,6 +1,6 @@
 .TH PFBTOPS @MAN1EXT@ "@MDATE@" "groff @VERSION@"
 .SH NAME
-pfbtops \- translate a PostScript font in .pfb format to ASCII
+pfbtops \- translate Printer Font Binary files to PostScript ASCII
 .
 .
 .\" ====================================================================
@@ -30,7 +30,7 @@ pfbtops \- translate a PostScript font in .pfb format to ASCII
 .\" ====================================================================
 .
 .SY pfbtops
-.RI [ pfb_file ]
+.RI [ pfb-file ]
 .YS
 .
 .SY pfbtops
@@ -47,45 +47,49 @@ pfbtops \- translate a PostScript font in .pfb format to 
ASCII
 .SH DESCRIPTION
 .\" ====================================================================
 .
-.B pfbtops
-translates a PostScript font in
-.B .pfb
-format to ASCII, splitting overlong lines in text packets into smaller
-chunks.
+.I pfbtops
+translates a PostScript font in Printer Font Binary (PFB) format to
+ASCII, splitting overlong lines in text packets into smaller chunks.
 .
 If
-.I pfb_file
-is omitted the pfb file will be read from the standard input.
+.I pfb-file
+is omitted, the PFB file will be read from the standard input.
 .
 The ASCII format PostScript font will be written on the standard output.
 .
-PostScript fonts for MS-DOS are normally supplied in
-.B .pfb
-format.
+PostScript fonts for MS-DOS are normally supplied in PFB format.
 .
 .
 .LP
-The resulting ASCII format PostScript font can be used with groff.
-.
-It must first be listed in
-.B @FONTDIR@/devps/download
+The resulting ASCII format PostScript font can be used with groff,
+if it is first listed in
+.I @FONTDIR@/\:devps/\:download
 and
-.BR @FONTDIR@/devpdf/download .
+.IR @FONTDIR@/\:devpdf/\:download .
 .
 .
 .\" ====================================================================
 .SH OPTIONS
 .\" ====================================================================
+.
+.TP
+.B \-\-help
+Display a usage message and exit.
+.
+.
 .TP
 .B \-v
-Print the version number.
+.TQ
+.B \-\-version
+Display version information and exit.
 .
 .
 .\" ====================================================================
 .SH "SEE ALSO"
 .\" ====================================================================
-.BR grops (@MAN1EXT@),
-.BR gropdf (@MAN1EXT@)
+.
+.IR grops (@MAN1EXT@),
+.IR gropdf (@MAN1EXT@)
 .
 .
 .\" Local Variables:
diff --git a/src/utils/tfmtodit/tfmtodit.1.man 
b/src/utils/tfmtodit/tfmtodit.1.man
index e9e2a41..7ddf30e 100644
--- a/src/utils/tfmtodit/tfmtodit.1.man
+++ b/src/utils/tfmtodit/tfmtodit.1.man
@@ -185,6 +185,7 @@ is true.
 .
 Whitespace is permitted between a command-line option and its argument.
 .
+.
 .TP
 .B \-v
 Print the version number.
diff --git a/src/utils/xtotroff/xtotroff.1.man 
b/src/utils/xtotroff/xtotroff.1.man
index 7ae8427..4833f55 100644
--- a/src/utils/xtotroff/xtotroff.1.man
+++ b/src/utils/xtotroff/xtotroff.1.man
@@ -32,7 +32,7 @@ xtotroff \- convert X font metrics into GNU troff font metrics
 .SY xtotroff
 .OP \-r resolution
 .OP \-s point-size
-.I FontMap
+.I font-map
 .YS
 .
 .SY xtotroff
@@ -50,30 +50,33 @@ xtotroff \- convert X font metrics into GNU troff font 
metrics
 .SH DESCRIPTION
 .\" ====================================================================
 .
-.B xtotroff
+.I xtotroff
 takes a
-.IR FontMap ,
+.IR font-map ,
 which maps
-.B groff
+.IR groff (@MAN1EXT@)
 fonts to X11 fonts,
 creates GNU
-.B troff
+.IR troff (@MAN1EXT@)
 metric files for all fonts listed.
 .
 Each line in
-.I FontMap
-consists of GNU
-.B troff
-font name and an X font name (XLFD) pattern, separated by whitespace.
+.I font-map
+consists of a
+.I groff
+font name and an X font name as a X Logical Font Description (XLFD)
+pattern,
+separated by whitespace.
 .
 Example:
 .
+.
 .PP
-.in +2n
-.nf
-TB   -adobe-times-bold-r-normal--*-*-*-*-p-*-iso8859-1
-.fi
-.in
+.RS
+.EX
+TB \-adobe\-times\-bold\-r\-normal\-\-*\-*\-*\-*\-p\-*\-iso8859\-1
+.EE
+.RE
 .
 .
 .PP
@@ -84,7 +87,7 @@ and
 switches.
 .
 If a font name is still ambiguous,
-.B xtotroff
+.I xtotroff
 aborts.
 .
 .
@@ -96,37 +99,48 @@ Whitespace is permitted between a command-line option and 
its argument.
 .
 .
 .TP
+.B \-\-help
+Display a usage message and exit.
+.
+.
+.TP
 .BI \-r resolution
 Set the resolution for all font patterns in
-.IR FontMap .
+.IR font-map .
 .
 The value is used for both the horizontal and vertical resolution.
 .
 If not specified, a resolution of 75dpi is assumed.
 .
+.
 .TP
 .BI \-s point-size
 Set the point size for all font patterns in
-.IR FontMap .
+.IR font-map .
 .
 If not specified, a size of 10pt is assumed.
 .
+.
 .TP
 .B \-v
-Print the version number.
+.TQ
+.B \-\-version
+Display version information and exit.
 .
 .
 .\" ====================================================================
 .SH BUGS
 .\" ====================================================================
-The only supported font encodings are \(oqiso8859-1\(cq and
-\(cqadobe-fontspecific\(cq.
+The only supported font encodings are \(lqiso8859\-1\(rq and
+\(lqadobe\-fontspecific\(rq.
 .
 .
 .\" ====================================================================
 .SH "SEE ALSO"
 .\" ====================================================================
-.BR gxditview (@MAN1EXT@)
+.IR groff (@MAN1EXT@),
+.IR gxditview (@MAN1EXT@),
+.IR troff (@MAN1EXT@)
 .
 .
 .\" Local Variables: