[groff] 03/04: gpinyin(1), grohtml(1): Fix style issues.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 051d5d5bc67dc3fcaaeb379fec39698bca7f1778
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Sep 19 02:48:04 2020 +1000

    gpinyin(1), grohtml(1): Fix style issues.
    
    * Add inline man page cross-references on first occurrence.
    * Comment out "See Also" cross-references to pages that are not
      mentioned in the man page text; cross-references should have
      motivation.
    * Refer to standard {input, output, error} _streams_.
    * Capitlize "HTML" when not referring specifically to an argument to
      [gt]roff's -T option.
    * Add space between options and their arguments.
    * Document --help and --version options in abbreviated form (q.v.
      3e980bf836307857541cf58451fc5d0149f30441, 19 August)
    * Set program names and man page topics in italics.
    * Don't prevent hyphenation of words that won't be hyphenated.
    * Tighten wording and use more idiomatic English.
    * Break input lines after commas and semicolons.
    * Put multi-word parentheticals on their own input lines.
    * Put an empty request between sentences.
    * Put two empty requests between paragraphs.
---
 contrib/gpinyin/gpinyin.1.man     |  20 +--
 src/devices/grohtml/grohtml.1.man | 301 +++++++++++++++++++++++---------------
 2 files changed, 189 insertions(+), 132 deletions(-)

diff --git a/contrib/gpinyin/gpinyin.1.man b/contrib/gpinyin/gpinyin.1.man
index b73c07e..a66a3f2 100644
--- a/contrib/gpinyin/gpinyin.1.man
+++ b/contrib/gpinyin/gpinyin.1.man
@@ -62,11 +62,11 @@ gpinyin \- use Hanyu Pinyin Chinese in roff
 .SH Description
 .\" ====================================================================
 .
-.B gpinyin
+.I gpinyin
 is a preprocessor for
-.BR \%groff (@MAN1EXT@)
-that facilitates use of the Hanyu Pinyin
-.BR groff (@MAN7EXT@)
+.IR groff (@MAN1EXT@)
+that facilitates use of Hanyu Pinyin in
+.IR groff (@MAN7EXT@)
 files.
 .
 Pinyin is a method for writing the Chinese language with the Latin
@@ -84,7 +84,7 @@ can be appended to each syllable.
 Each
 .I input-file
 is a file name or the hyphen-minus character \[lq]\-\[rq] to indicate
-that standard input should be read.
+that the standard input stream should be read.
 .
 As usual,
 the argument \[lq]\-\-\[rq] can be used in order to force interpretation
@@ -243,7 +243,7 @@ but not otherwise.
 .SH Authors
 .\" ====================================================================
 .
-.B gpinyin
+.I gpinyin
 was written by
 .MT <groff\-bernd.warken\-72@\:web.de>
 Bernd Warken
@@ -313,18 +313,18 @@ pinyin.sty from the CJK macro package for \*[TeX]
 .RE
 .
 .P
-.BR groff (@MAN1EXT@)
+.IR groff (@MAN1EXT@)
 and
-.BR grog (@MAN1EXT@)
+.IR grog (@MAN1EXT@)
 explain how to view
 .I roff
 documents.
 .
 .
 .P
-.BR groff (@MAN7EXT@)
+.IR groff (@MAN7EXT@)
 and
-.BR groff_char (@MAN7EXT@)
+.IR groff_char (@MAN7EXT@)
 are comprehensive references covering the language elements of GNU
 .I roff
 and the available glyph repertoire,
diff --git a/src/devices/grohtml/grohtml.1.man 
b/src/devices/grohtml/grohtml.1.man
index 3732042..31fdbfa 100644
--- a/src/devices/grohtml/grohtml.1.man
+++ b/src/devices/grohtml/grohtml.1.man
@@ -70,65 +70,71 @@ grohtml \- HTML driver for groff
 .\" ====================================================================
 .
 The
-.B grohtml
+.I grohtml
 front end (which consists of a preprocessor,
-.BR pre-grohtml ,
+.IR pre-grohtml ,
 and a device driver,
-.BR post-grohtml )
+.IR post-grohtml )
 translates the output of GNU
-.B troff
+.I roff
 to HTML.
 .
 Users should always invoke
-.B grohtml
-via the groff command with a
+.I grohtml
+via the
+.IR groff (@MAN1EXT@)
+command with the
 .B \-Thtml
 option.
 .
-If no files are given,
-.B grohtml
-will read the standard input.
-.
-A filename of
-.B \-
-will also cause
-.B grohtml
-to read the standard input.
+If no file are given,
+or if
+.I file
+is
+.RB \[lq] \- \[rq],
+.I grohtml
+will read the standard input stream.
 .
-Html output is written to the standard output.
+HTML output is written to the standard output stream.
 .
 When
-.B grohtml
+.I grohtml
 is run by
-.B groff
+.IR groff ,
 options can be passed to
-.B grohtml
+.I grohtml
 using
-.BR groff 's
+.IR groff 's
 .B \-P
 option.
 .
 .
 .PP
-.B grohtml
+.I grohtml
 invokes
-.B groff
+.I groff
 twice.
-In the first pass, pictures, equations, and tables are rendered
-using the
+.
+In the first pass,
+pictures,
+equations,
+and tables are rendered using the
 .B ps
-device, and in the second pass HTML output is generated by the
+device,
+and in the second pass HTML output is generated by the
 .B html
 device.
 .
 .
 .PP
-.B grohtml
+.I grohtml
 always writes output in \%UTF-8 encoding and has built-in entities for
-all non-composite unicode characters.
+all non-composite Unicode characters.
 .
-In spite of this, groff may issue warnings about unknown special
-characters if they can't be found during the first pass.
+In spite of this,
+.I groff
+may issue warnings about unknown special characters if they can't be
+found during the first pass.
 .
 Such warnings can be safely ignored unless the special characters
 appear inside a table or equation.
@@ -138,16 +144,27 @@ appear inside a table or equation.
 .SH Options
 .\" ====================================================================
 .
+.B \-\-help
+displays a usage message
+and
+.B \-v
+shows version information;
+both exit afterward.
+.
+.
 .TP
-.BI \-a aa-text-bits
+.BI \-a \~aa-text-bits
 Number of bits of antialiasing information to be used by
 .I text
 when generating PNG images.
 .
-The default is\~4 but valid values are 0, 1, 2, and\~4.
+The default is\~4 but valid values are 0,
+1,
+2,
+and\~4.
 .
-Note your version of
-.B gs
+Note that your version of
+.I gs
 needs to support the
 .B \%\-dTextAlphaBits
 and
@@ -155,58 +172,68 @@ and
 options in order to exploit antialiasing.
 .
 A value of\~0 stops
-.B grohtml
+.I grohtml
 from issuing antialiasing commands to
-.BR gs .
+.IR gs .
+.
 .
 .TP
 .B \-b
 Initialize the background color to white.
 .
+.
 .TP
-.BI \-D dir
-Inform
-.B grohtml
+.BI \-D \~dir
+Instruct
+.I grohtml
 to place all image files into directory
 .IR dir .
 .
+.
 .TP
 .B \-e
-This option should not be directly invoked by the user as it is an
-internal option utilized by
-.B groff
+This option should not be directly specified;
+it is an internal option used by
+.I groff
 when
 .B \-Thtml
 or
 .B \-Txhtml
 is specified.
-It is used by the
-.B grohtml
-preprocessor to determine whether
-.B eqn
-should attempt to produce MathML (if
+.
+.IR grohtml 's
+preprocessor uses it to determine whether
+.I eqn
+should be directed to produce MathML
+(if
 .B \-Txhtml
 is specified).
 .
+.
 .TP
-.BI \-F dir
+.BI \-F \~dir
 Prepend directory
 .RI dir /dev name
 to the search path for font and device description files;
 .I name
-is the name of the device, usually
+is the name of the device,
+usually
 .BR html .
 .
+.
 .TP
-.BI \-g aa-graphic-bits
+.BI \-g \~aa-graphic-bits
 Number of bits of antialiasing information to be used by
 .I graphics
 when generating PNG images.
 .
-The default is\~4 but valid values are 0, 1, 2, and\~4.
+The default is\~4 but valid values are 0,
+1,
+2,
+and\~4.
 .
 Note your version of
-.B gs
+.I gs
 needs to support the
 .B \%\-dTextAlphaBits
 and
@@ -214,22 +241,25 @@ and
 options in order to exploit antialiasing.
 .
 A value of\~0 stops
-.B grohtml
+.I grohtml
 from issuing antialiasing commands to
-.BR gs .
+.IR gs .
+.
 .
 .TP
 .B \-h
 Generate section and number headings by using
 .BR <B> .\|.\|. </B>
-and increasing the font size, rather than using the
+and increasing the font size,
+rather than using the
 .BI <H n >\c
 \&.\|.\|.\c
 .BI </H n >
 tags.
 .
+.
 .TP
-.BI \-i resolution
+.BI \-i \~resolution
 Select the resolution for all images.
 .
 By default this is 100 pixels per inch.
@@ -238,32 +268,40 @@ Example:
 .B \-i200
 indicates 200 pixels per inch.
 .
+.
 .TP
-.BI \-I stem
+.BI \-I \~stem
 Determine the image stem name.
 .
 If omitted grohtml uses
-.BI \%grohtml- XXX
-.RI ( XXX
+.IR \%grohtml\- XXXXX
+(where
+.I XXXXX
 is the process ID).
 .
+.
 .TP
-.BI \-j filename
-Inform
-.B grohtml
+.BI \-j \~filename
+Instruct
+.I grohtml
 to split the HTML output into multiple files.
 .
 The
 .I filename
-is the stem and specified section headings (default is level one)
-start a new file, named
-.IR filename-n.html .
+is the stem and output is written to a new file at each section heading
+(but see option
+.B \-S
+below)
+named
+.IR filename\- n .html .
+.
 .
 .TP
 .B \-l
 Turn off the production of automatic section links at the top of the
 document.
 .
+.
 .TP
 .B \-n
 Generate simple heading anchors whenever a section/number heading is
@@ -271,31 +309,37 @@ found.
 .
 Without the option the anchor value is the textual heading.
 .
-This can cause problems when a heading contains a \(oq?\(cqa on older
-versions of some browsers (Netscape).
+This can cause problems when a heading contains a \[lq]?\[rq] on older
+versions of some browsers.
 .
 This flag is automatically turned on if a heading contains an image.
 .
+.
 .TP
-.BI \-o vertical-offset
+.BI \-o \~vertical-offset
 Specify the vertical offset of images in points.
 .
+.
 .TP
 .B \-p
-Display page rendering progress to stderr.
-.B grohtml
+Display page rendering progress to the standard error stream.
+.
+.I grohtml
 only displays a page number when an image is required.
 .
+.
 .TP
 .B \-r
-Turn off the automatic header and footer line (HTML rule).
+Turn off the automatic header and footer line
+(HTML rule).
+.
 .
 .TP
-.B \-s size
+.BI \-s \~size
 Set the base point size of the source file.
 .
-Thereafter when this point size is used in the source it will
-correspond to the HTML base size.
+Thereafter when this point size is used in the source it will correspond
+to the HTML base size.
 .
 Every increase of two points in the source will yield a
 .B <big>
@@ -303,47 +347,57 @@ tag, and conversely when a decrease of two points is seen 
a
 .B <small>
 tag is emitted.
 .
-.TP
-.BI \-S level
-When splitting HTML output,
-split at the heading level (or higher) defined by
-.IR level .
 .
 .TP
-.B \-v
-Print the version number.
+.BI \-S \~level
+When splitting HTML output
+(see option
+.B \-j
+above),
+split at each nested heading level defined by
+.IR level ,
+or higher).
+.
+The default is
+.BR 1 .
+.
 .
 .TP
 .B \-V
 Create an XHTML or HTML validator button at the bottom of each page of
 the document.
 .
+.
 .TP
-.BI \-x dialect
+.BI \-x \~dialect
 Select HTML dialect.
 .
 Currently,
 .I dialect
-should be either the digit\~\c
-.B 4
-or the letter\~\c
-.B x
+should be either the
+.RB digit\~ 4
+or the
+.RB letter\~ x ,
 which indicates whether
-.B grohtml
-should generate HTML\~4 or XHTML, respectively.
+.I grohtml
+should generate HTML\~4 or XHTML,
+respectively.
 .
 This option should not be directly invoked by the user as it is
 an internal option utilized by
-.B groff
+.I groff
 when
 .B \-Thtml
 or
 .B \-Txhtml
 is specified.
 .
+.
 .TP
 .B \-y
-Produce a right-justified groff signature at the end of the document.
+Produce a right-justified
+.I groff
+signature at the end of the document.
 .
 This is only generated if the
 .B \-V
@@ -367,40 +421,41 @@ mounted at font positions 1 to\~4.
 .SH Dependencies
 .\" ====================================================================
 .
-.B grohtml
+.I grohtml
 is dependent upon the PNG utilities
-.RB ( \%pnmcut ,
-.BR \%pnmcrop ,
-.BR \%pnmtopng )
+.RI ( \%pnmcut ,
+.IR \%pnmcrop ,
+.IR \%pnmtopng )
 and GhostScript
-.RB ( gs ).
+.RI ( gs ).
 .
-.B \%pnmtopng
+.I \%pnmtopng
 (version 2.37.6 or greater)
 and
-.B \%pnmcut
+.I \%pnmcut
 from the netpbm package (version 9.16 or greater) will work also.
 .
 It is also dependent upon
-.B \%psselect
-from the
-.B PSUtils
-package.
+.I \%psselect
+from the PSUtils package.
 .
-Images are generated whenever a table, picture, equation or line is
-encountered.
+Images are generated whenever a table,
+picture,
+equation or line
+(such as a baseline rule or box rule)
+is encountered.
 .
 .
 .\" ====================================================================
 .SH Files
 .\" ====================================================================
 .
-.B grohtml
+.I grohtml
 uses temporary files.
 .
-See the
-.BR groff (@MAN1EXT@)
-man page for details where such files are created.
+See
+.IR groff (@MAN1EXT@)
+for details about where such files are created.
 .
 .
 .\" ====================================================================
@@ -414,44 +469,46 @@ A list of directories in which to search for the
 directory in addition to the default ones.
 .
 See
-.BR @g@troff (@MAN1EXT@)
+.IR @g@troff (@MAN1EXT@)
 and
-.BR \%groff_font (@MAN5EXT@)
+.IR groff_font (@MAN5EXT@)
 for more details.
 .
 .
 .TP
 .I SOURCE_DATE_EPOCH
-A timestamp (expressed as seconds since the Unix epoch) to use as the
-creation timestamp in place of the current time.
+A timestamp
+(expressed as seconds since the Unix epoch)
+to use as the creation timestamp in place of the current time.
 .
 .
 .\" ====================================================================
 .SH Bugs
 .\" ====================================================================
 .
-.B Grohtml
-has been completely redesigned and rewritten.
-.
-It is still beta code.
+.I grohtml
+is still beta code.
 .
 .
 .PP
 .I grohtml
-does not support hyphenation.
+does not truly support hyphenation,
+but you can fool it into hyphenating long input lines,
+which can appear in HTML output with a hyphenated word followed by a
+space but no line break.
 .
 .
 .\" ====================================================================
 .SH "See Also"
 .\" ====================================================================
 .
-.BR afmtodit (@MAN1EXT@),
-.BR groff (@MAN1EXT@),
-.BR @g@troff (@MAN1EXT@),
-.BR psbb (@MAN1EXT@),
-.BR groff_out (@MAN5EXT@),
-.BR groff_font (@MAN5EXT@),
-.BR groff_char (@MAN7EXT@)
+.\" IR afmtodit (@MAN1EXT@),
+.IR groff (@MAN1EXT@),
+.IR @g@troff (@MAN1EXT@),
+.\" IR psbb (@MAN1EXT@),
+.\" IR groff_out (@MAN5EXT@),
+.\" IR groff_char (@MAN7EXT@),
+.IR groff_font (@MAN5EXT@)
 .
 .
 .\" Restore compatibility mode (for, e.g., Solaris 10/11).