[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 11/20: man pages: Make style fixes.
From: |
G. Branden Robinson |
Subject: |
[groff] 11/20: man pages: Make style fixes. |
Date: |
Fri, 9 Nov 2018 18:39:41 -0500 (EST) |
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:
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 11/20: man pages: Make style fixes.,
G. Branden Robinson <=