[groff] 12/21: grohtml(1): Organize and clarify.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit b128913074d43c11d0f0eec035fcdb316ad7e397
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Aug 22 06:44:26 2022 -0500

    grohtml(1): Organize and clarify.
    
    Impose more structure on output driver man pages, part 2.
    
    Fix content nits.
    * Explain why (most) users should only try to approach this output
      device via the groff(1) front end.
    * Document which output device is the default.
    * Parallelize introduction with that of other output drivers.
    * Correctly distinguish output "driver" from output "device" (the former
      is a program; the latter is a parameter in a programming interface).
    * Clarify what sorts of "entities" grohtml writes.
    * Add "Typefaces" subsection, replacing "Usage".  Expand discussion to
      cover the font descriptions actually shipped.
    * Add "Font description files" subsection noting parallelism of glyph
      repertoires in all fonts, an uncommon property.
    * Move discussion of runtime program dependencies into new
      "Dependencies" subsection.
    * Drop trivial and obvious example.
    * Shift discussion from HTML "tags" to "elements".  The details of
      (X)HTML markup are not relevant here.
    * Migrate terminology: "point size" -> "type size".
    * Migrate terminology: "right-justified" -> "right-aligned".
    * Flesh out "Files" section, discussing more than just temporary files.
      Align with other output driver documentation, presenting device and
      font description files, and device-specific macro files.  (The latter
      aren't _opened_ by the driver program, which is why we don't document
      GROFF_TMAC_PATH in the page, but this is most appropriate place to
      discuss them.)
    
    Fix style nits.
    * Set "Name" section's summary-description terms in italics as needed.
    * Parallelize discussion of (internal) options.  Say what they do first,
      then warn the user off.
    * Shift "only" modifiers to more appropriate syntactical locations.
    * (Environment) Begin sentences with the paragraph tag, to economize and
      align with (material being added to) section "Files".
    * Tighten wording.
    
    Fix markup nits.
    * Protect "pre-grohtml", "post-grohtml", "grohtml" from hyphenation.
    * Protect "Netpbm", "Ghostscript", and "PSUtils" from hyphenation.
    * Annotate areas where might be able to drop some text outright.  (How
      long ago did Ghostscript lack anti-aliasing support?)
---
 src/devices/grohtml/grohtml.1.man | 412 ++++++++++++++++++++++++--------------
 1 file changed, 267 insertions(+), 145 deletions(-)

diff --git a/src/devices/grohtml/grohtml.1.man 
b/src/devices/grohtml/grohtml.1.man
index 293f478ed..389b8f5fc 100644
--- a/src/devices/grohtml/grohtml.1.man
+++ b/src/devices/grohtml/grohtml.1.man
@@ -1,13 +1,15 @@
 .TH grohtml @MAN1EXT@ "@MDATE@" "groff @VERSION@"
 .SH Name
-grohtml, post\-grohtml, pre\-grohtml \- groff output driver for HTML
+grohtml, post\-grohtml, pre\-grohtml \-
+.I groff
+output driver for HTML
 .
 .
 .\" ====================================================================
 .\" Legal Terms
 .\" ====================================================================
 .\"
-.\" Copyright (C) 1999-2021 Free Software Foundation, Inc.
+.\" Copyright (C) 1999-2022 Free Software Foundation, Inc.
 .\"
 .\" Permission is granted to make and distribute verbatim copies of this
 .\" manual provided the copyright notice and this permission notice are
@@ -107,16 +109,17 @@ grohtml, post\-grohtml, pre\-grohtml \- groff output 
driver for HTML
 The GNU
 .I roff
 system's HTML support consists of a preprocessor,
-.IR pre\-grohtml ,
+.IR \%pre\-grohtml ,
 and an output driver,
-.IR post\-grohtml ;
+.IR \%post\-grohtml ;
 together,
 they translate
 .MR roff @MAN7EXT@
 documents to HTML.
 .
-Users should always invoke
-.I grohtml
+Because a preprocessor is (uniquely) required for this output driver,
+users should invoke
+.I \%grohtml
 via the
 .MR groff @MAN1EXT@
 command with the
@@ -125,56 +128,55 @@ or
 .B \-Txhtml
 options.
 .
+(In this installation,
+.B @DEVICE@
+is the default output device.)
+.
+Use
+.IR groff 's
+.B \-P
+option to pass any options shown above to
+.IR \%grohtml .
+.
 If no operands are given,
 or if
 .I file
 is
 .RB \[lq] \- \[rq],
-.I grohtml
+.I \%grohtml
 reads the standard input stream.
 .
 Output is written to the standard output stream.
 .
-When
-.I grohtml
-is run by
-.IR groff ,
-options can be passed to
-.I grohtml
-using
-.IR groff 's
-.B \-P
-option.
-.
 .
-.PP
-.I grohtml
+.P
+.I \%grohtml
 invokes
 .I groff
 twice.
 .
 In the first pass,
 the preprocessor
-.I pre\-grohtml
+.I \%pre\-grohtml
 renders
 pictures,
 equations,
 and tables as images in PostScript format using the
 .B ps
-output driver.
+output device.
 .
 In the second pass,
 the output driver
-.I post\-grohtml
+.I \%post\-grohtml
 translates the output of
 .MR @g@troff @MAN1EXT@
 to HTML.
 .
 .
-.PP
-.I grohtml
-always writes output encoded in \%UTF-8 and has built-in entities for
-all non-composite Unicode characters.
+.P
+.I \%grohtml
+writes output encoded in \%UTF-8 and has built-in HTML entities for all
+non-composite Unicode characters.
 .
 In spite of this,
 .I groff
@@ -186,32 +188,113 @@ appear inside a table or equation.
 .
 .
 .\" ====================================================================
-.SH Dependencies
+.SS Typefaces
 .\" ====================================================================
 .
-.I grohtml
-is dependent upon the PNG utilities
-.RI ( \%pnmcut ,
-.IR \%pnmcrop ,
-.IR \%pnmtopng )
-and Ghostscript
-.RI ( gs ).
+.I \%grohtml
+supports the standard four styles:
+.B R
+(roman),
+.B I
+.RI ( italic ),
+.B B
+.RB ( bold ),
+and
+.B BI
+(\f[BI]bold-italic\f[]).
 .
-.I \%pnmtopng
-(version 2.37.6 or greater)
+Fonts are grouped into families
+.B T
 and
-.I \%pnmcut
-from the netpbm package (version 9.16 or greater) will work also.
+.B C
+having members in each style.
+.
+.
+.RS
+.TP
+.B TR
+Times roman
+.
+.TQ
+.B TI
+Times italic
+.
+.TQ
+.B TB
+Times bold
+.
+.TQ
+.B TBI
+Times bold-italic
+.
+.TQ
+.B CR
+Courier roman
+.
+.TQ
+.B CI
+Courier italic
 .
-It is also dependent upon
-.I \%psselect
-from the PSUtils package.
+.TQ
+.B CB
+Courier bold
 .
-Images are generated whenever a table,
+.TQ
+.B CBI
+Courier bold-italic
+.RE
+.
+.
+.P
+A special font,
+.BR S ,
+is also provided to accommodate
+.I roff
+documents that expect it to always be available.
+.
+.
+.\" ====================================================================
+.SS "Font description files"
+.\" ====================================================================
+.
+The font description files used with
+.I \%grohtml
+expose the same glyph repertoire in their
+.B charset
+sections.
+.
+See
+.MR groff_font @MAN5EXT@ .
+.
+.
+.\" ====================================================================
+.SS Dependencies
+.\" ====================================================================
+.
+.I \%pre\-grohtml
+generates an image whenever an
+.I @g@eqn
+equation,
+.I @g@tbl
+table,
+.I @g@pic
 picture,
-equation or line
+or line
 (such as a baseline rule or box rule)
-is encountered.
+is encountered in the input.
+.
+.I \%grohtml
+therefore may run several commands as part of its operation.
+.
+These include the \%Netpbm tools
+.IR \%pnmcrop ,
+.IR \%pnmcut ,
+and
+.IR \%pnmtopng ;
+\%Ghostscript
+.RI ( gs );
+and the \%PSUtils tool
+.IR \%psselect .
 .
 .
 .\" ====================================================================
@@ -230,25 +313,29 @@ all exit afterward.
 .
 .TP
 .BI \-a \~anti-aliasing-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.
+Number of bits of antialiasing information to be used by text when
+generating PNG images.
+.
+The default
+.RB is\~ 4
+but
+.BR 0 ,
+.BR 1 ,
+and
+.B 2
+are also valid.
 .
-Note that your version of
+Your system's version of
 .I gs
-needs to support the
+must support the
 .B \%\-dTextAlphaBits
-and
-.B \%\-dGraphicAlphaBits
-options in order to exploit antialiasing.
+option in order to exploit antialiasing.
+.\" XXX: How antiquated are the ones that don't?  Get rid of this?
 .
-A value of\~0 stops
-.I grohtml
+A value
+.RB of\~ 0
+stops
+.I \%grohtml
 from issuing antialiasing commands to
 .IR gs .
 .
@@ -266,29 +353,27 @@ Suppress output of \[lq]CreationDate:\[rq] HTML comment.
 .TP
 .BI \-D \~image-directory
 Instruct
-.I grohtml
+.I \%grohtml
 to place all image files into directory
 .IR image-directory .
 .
 .
 .TP
 .B \-e
-This option should not be directly specified;
-it is an internal option used by
+Direct
+.I @g@eqn
+to produce MathML.
+.
+.
+.IP
+This option should not be manually specified;
+it is synthesized by
 .I groff
-when
+depending on whether it was given the
 .B \-Thtml
 or
 .B \-Txhtml
-is specified.
-.
-.IR grohtml 's
-preprocessor uses it to determine whether
-.I eqn
-should be directed to produce MathML
-(if
-.B \-Txhtml
-is specified).
+option.
 .
 .
 .TP
@@ -309,50 +394,48 @@ Suppress output of \[lq]Creator:\[rq] HTML comment.
 .
 .TP
 .BI \-g \~anti-aliasing-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.
+Number of bits of antialiasing information to be used by graphics when
+generating PNG images.
+.
+The default
+.RB is\~ 4
+but
+.BR 0 ,
+.BR 1 ,
+and
+.B 2
+are also valid.
 .
-Note your version of
+Your system's version of
 .I gs
-needs to support the
-.B \%\-dTextAlphaBits
-and
+must support the
 .B \%\-dGraphicAlphaBits
-options in order to exploit antialiasing.
+option in order to exploit antialiasing.
+.\" XXX: How antiquated are the ones that don't?  Get rid of this?
 .
-A value of\~0 stops
-.I grohtml
+A value
+.RB of\~ 0
+stops
+.I \%grohtml
 from issuing antialiasing commands to
 .IR gs .
 .
 .
 .TP
 .B \-h
-Generate section and number headings by using
-.BR <B> .\|.\|. </B>
-and increasing the font size,
-rather than using the
-.BI <H n >\c
-\&.\|.\|.\c
-.BI </H n >
-tags.
+Generate section headings by using HTML
+.B B
+elements and increasing the font size,
+rather than HTML
+.B H
+elements.
 .
 .
 .TP
 .BI \-i \~resolution
-Select the resolution for all images.
-.
-By default this is 100 pixels per inch.
-.
-Example:
-.B \-i200
-indicates 200 pixels per inch.
+Set the image resolution in pixels per inch;
+the default
+.RB is\~ 100 .
 .
 .
 .TP
@@ -360,7 +443,7 @@ indicates 200 pixels per inch.
 Determine the image file name stem.
 .
 If omitted,
-.I grohtml
+.I \%grohtml
 uses
 .IR \%grohtml\- XXXXX
 (where
@@ -374,7 +457,7 @@ number.
 .TP
 .BI \-j \~output-stem
 Instruct
-.I grohtml
+.I \%grohtml
 to split the HTML output into multiple files.
 .
 Output is written to a new file at each section heading
@@ -401,7 +484,7 @@ Without the option the anchor value is the textual heading.
 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.
+This feature is automatically enabled if a heading contains an image.
 .
 .
 .TP
@@ -413,8 +496,8 @@ Specify the vertical offset of images in points.
 .B \-p
 Display page rendering progress to the standard error stream.
 .
-.I grohtml
-only displays a page number when an image is required.
+.I \%grohtml
+displays a page number only when an image is required.
 .
 .
 .TP
@@ -424,17 +507,19 @@ Turn off the automatic header and footer line
 .
 .
 .TP
-.BI \-s \~base-point-size
-Set the base point size of the source file.
+.BI \-s \~base-type-size
+Set the document's base type size in points.
 .
-Thereafter when this point size is used in the source it will correspond
-to the HTML base size.
+When this size is used in the source,
+it corresponds to the HTML base type size.
 .
-Every increase of two points in the source will yield a
-.B <big>
-tag, and conversely when a decrease of two points is seen a
-.B <small>
-tag is emitted.
+Every increase of two points in the source will produce a
+.RB \[lq] big \[rq]
+element,
+and conversely when a decrease of two points is seen,
+a
+.RB \[lq] small \[rq]
+element is emitted.
 .
 .
 .TP
@@ -468,43 +553,30 @@ should be either the
 or the
 .RB letter\~ x ,
 which indicates whether
-.I grohtml
+.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
+.
+.IP
+This option should not be manually specified;
+it is synthesized by
 .I groff
-when
+depending on whether it was given the
 .B \-Thtml
 or
 .B \-Txhtml
-is specified.
+option.
 .
 .
 .TP
 .B \-y
-Produce a right-justified
+Produce a right-aligned
 .I groff
-signature at the end of the document.
-.
-This is only generated if the
+signature at the end of the document
+(only if
 .B \-V
-flag is also specified.
-.
-.
-.\" ====================================================================
-.SH Usage
-.\" ====================================================================
-.
-Font styles called
-.BR R ,
-.BR I ,
-.BR B ,
-and
-.B BI
-are mounted at font positions\~1 to\~4,
-respectively.
+is also specified).
 .
 .
 .\" ====================================================================
@@ -513,7 +585,9 @@ respectively.
 .
 .TP
 .I GROFF_FONT_PATH
-A list of directories in which to seek the selected output device's
+lists directories in which to search for
+.IR devhtml ,
+.IR grohtml 's
 directory of device and font description files.
 .
 See
@@ -547,7 +621,55 @@ see
 .SH Files
 .\" ====================================================================
 .
-.I grohtml
+.TP
+.I @FONTDIR@/\:\%devhtml/\:DESC
+describes the
+.B html
+output device.
+.
+.
+.TP
+.IR @FONTDIR@/\:\%devhtml/ F
+describes the font known
+.RI as\~ F
+on device
+.BR html .
+.
+.
+.TP
+.I @MACRODIR@/\:html\:.tmac
+defines font mappings,
+special characters,
+and colors for use with the
+.B html
+output device.
+.
+It is automatically loaded by
+.I \%troffrc
+when either of the
+.B html
+or
+.B xhtml
+output devices is selected.
+.
+.
+.TP
+.I @MACRODIR@/\:html\-end\:.tmac
+finalizes setup of the
+.B html
+output device.
+.
+It is automatically loaded by
+.I \%troffrc\-end
+when either of the
+.B html
+or
+.B xhtml
+output devices is selected.
+.
+.
+.P
+.I \%grohtml
 uses temporary files.
 .
 See
@@ -559,12 +681,12 @@ for details about where such files are created.
 .SH Bugs
 .\" ====================================================================
 .
-.I grohtml
+.I \%grohtml
 is still beta code.
 .
 .
 .PP
-.I grohtml
+.I \%grohtml
 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