[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 03/04: gpinyin(1), grohtml(1): Fix style issues.
From: |
G. Branden Robinson |
Subject: |
[groff] 03/04: gpinyin(1), grohtml(1): Fix style issues. |
Date: |
Fri, 18 Sep 2020 13:28:29 -0400 (EDT) |
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).
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 03/04: gpinyin(1), grohtml(1): Fix style issues.,
G. Branden Robinson <=