# grohtml

## Name



           grohtml, post-grohtml, pre-grohtml - _groff_ output driver for HTML
    


## Synopsis



           **pre-grohtml**[**-epV**] [**-a** _anti-aliasing-text-bits_] [**-D** _image-_
                       _directory_] [**-F** _font-directory_] [**-g** _anti-aliasing-_
                       _graphic-bits_] [**-i** _resolution_] [**-I** _image-stem_]
                       [**-o** _image-vertical-offset_] [**-x** _html-dialect_] _troff-_
                       _command troff-argument_ ...
    
           **pre-grohtml --help**
    
           **pre-grohtml -v**
    
           **pre-grohtml --version**
    
           **post-grohtml**[**-bCGhlnrVy**] [**-F** _font-directory_] [**-j** _output-stem_]
                        [**-k** _encoding_] [**-s** _base-point-size_] [**-S** _heading-level_]
                        [**-x** _html-dialect_] [_file_ ...]
    
           **post-grohtml --help**
    
           **post-grohtml -v**
    
           **post-grohtml --version**
    


## Description



           The GNU _roff_ system's HTML support consists of a preprocessor,
           _pre-grohtml_ , and an output driver, _post-grohtml_ ; together, they
           translate _roff_(7) documents to HTML.  Because a preprocessor is
           (uniquely) required for this output driver, users should invoke
           _grohtml_ via the _groff_(1) command with the **-Thtml** or **-Txhtml**
           options.  (In this installation, **ps** is the default output device.)
           Use _groff_ 's **-P** option to pass any options shown above to _grohtml_.
           If no operands are given, or if _file_ is “**-** ”, _grohtml_ reads the
           standard input stream.  It writes to the standard output stream.
    
           _grohtml_ invokes _groff_ twice.  In the first pass, the preprocessor
           _pre-grohtml_ renders pictures, equations, and tables as images in
           PostScript format using the **ps** output device.  In the second pass,
           the output driver _post-grohtml_ translates the output of _troff_(1)
           to HTML.
    
           _grohtml_ writes UTF-8-encoded output (but see the **-k** option) and
           produces HTML character references for most non-composite, non-
           basic Latin Unicode characters.  In spite of this, _groff_ may issue
           warnings about unknown special characters if they can't be found
           during the first pass.  You can ignore these warnings unless the
           special characters appear inside a table or equation.
    
       **Typefaces**
           _grohtml_ supports the standard four styles: **R**(roman), **I**(_italic_),
           **B**(**bold**), and **BI**(_**bold-italic**_).  Fonts are grouped into families **T**
           and **C** having members in each style.
    
                  **TR** Times roman
                  **TI** Times italic
                  **TB** Times bold
                  **TBI** Times bold-italic
                  **CR** Courier roman
                  **CI** Courier italic
                  **CB** Courier bold
                  **CBI** Courier bold-italic
    
           A special font, **S** , is also provided to accommodate _roff_ documents
           that expect it to always be available.
    
           _grohtml_ furthermore supports a naming scheme for East Asian
           typefaces shared with _gropdf_(1), _grops_(1), and _grotty_(1).
    
                  **CSH** Simplified Chinese, Hei style
                  **CSS** Simplified Chinese, Song style
                  **CTH** Traditional Chinese, Hei style
                  **CTS** Traditional Chinese, Song style
                  **JPG** Japanese, Gothic style
                  **JPM** Japanese, Mincho style
                  **KOG** Korean, Gothic style
                  **KOM** Korean, Mincho style
    
       **Font description files**
           The font description files used with _grohtml_ expose the same glyph
           repertoire in their **charset** sections.  See _groff_font_(5).
    
       **Dependencies**
           _pre-grohtml_ generates an image whenever an _eqn_ equation, _tbl_
           table, or _pic_ picture is encountered in the input.  _grohtml_
           therefore may run several commands as part of its operation.
           These include the Netpbm tools _pamcut_ , _pnmcrop_ , and _pnmtopng_ , as
           well as Ghostscript's _gs_ and _ps2ps_.
    


## Options



           **--help** displays a usage message, while **-v** and **--version** show
           version information; all exit afterward.
    
           **-a** _anti-aliasing-text-bits_
                  Number of bits of antialiasing information to be used by
                  text when generating PNG images.  The default is **4** but **0** ,
                  **1** , and **2** are also valid.  Your system's version of _gs_ must
                  support the **-dTextAlphaBits** option in order to exploit
                  antialiasing.  A value of **0** stops _grohtml_ from issuing
                  antialiasing commands to _gs_.
    
           **-b** Initialize the background color to white.
    
           **-C** Suppress output of “CreationDate:” HTML comment.
    
           **-D** _image-directory_
                  Instruct _grohtml_ to place all image files into directory
                  _image-directory_.
    
           **-e** Direct _eqn_ to produce MathML.
    
                  This option should not be manually specified; it is
                  synthesized by _groff_ depending on whether it was given the
                  **-Thtml** or **-Txhtml** option.
    
           **-F** _font-directory_
                  Prepend directory font-directory _/dev_ name to the search path
                  for font and device description files; _name_ is the name of
                  the device, usually **html**.
    
           **-g** _anti-aliasing-graphic-bits_
                  Number of bits of antialiasing information to be used by
                  graphics when generating PNG images.  The default is **4** but
                  **0** , **1** , and **2** are also valid.  Your system's version of _gs_
                  must support the **-dGraphicAlphaBits** option in order to
                  exploit antialiasing.  A value of **0** stops _grohtml_ from
                  issuing antialiasing commands to _gs_.
    
           **-G** Suppress output of “Creator:” HTML comment.
    
           **-h** Generate section headings by using HTML **B** elements and
                  increasing the font size, rather than HTML **H** elements.
    
           **-i** _resolution_
                  Set the image resolution in pixels per inch; the default
                  is **100**.
    
           **-I** _image-stem_
                  Determine the image file name stem.  If omitted, _grohtml_
                  uses _grohtml-_ XXXXX (where _XXXXX_ is the process ID).  A dash
                  is appended to the stem to separate it from the following
                  image number.
    
           **-j** _output-stem_
                  Instruct _grohtml_ to split the HTML output into multiple
                  files.  Output is written to a new file at each section
                  heading (but see option **-S** below) named _output-stem-_ n _.html_.
    
           **-k** _encoding_
                  Select the character encoding used in the generated
                  document, affecting the declared encoding in the preamble
                  and the form of character entity references.  Valid values
                  are “ASCII” and “UTF-8”.  The default is “UTF-8”.
    
           **-l** Turn off the production of automatic section links at the
                  top of the document.
    
           **-n** Generate simple heading anchors whenever a section/number
                  heading is found.  Without the option the anchor value is
                  the textual heading.  This can cause problems when a
                  heading contains a “?” on older versions of some browsers.
                  This feature is automatically enabled if a heading contains
                  an image.
    
           **-o** _image-vertical-offset_
                  Specify the vertical offset of images in points.
    
           **-p** Display page rendering progress to the standard error
                  stream.  _grohtml_ displays a page number only when an image
                  is required.
    
           **-r** Turn off the automatic header and footer line (HTML rule).
    
           **-s** _base-type-size_
                  Set the document's base type size in points.  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
                  produce a “**big** ” element, and conversely when a decrease of
                  two points is seen, a “**small** ” element is emitted.
    
           **-S** _heading-level_
                  When splitting HTML output (see option **-j** above), split at
                  each nested heading level defined by _heading-level_ , or
                  higher).  The default is **1**.
    
           **-V** Create an XHTML or HTML validator button at the bottom of
                  each page of the document.
    
           **-x** _html-dialect_
                  Select HTML dialect.  Currently, _html-dialect_ should be
                  either the digit **4** or the letter **x** , which indicates whether
                  _grohtml_ should generate HTML 4 or XHTML, respectively.
    
                  This option should not be manually specified; it is
                  synthesized by _groff_ depending on whether it was given the
                  **-Thtml** or **-Txhtml** option.
    
           **-y** Produce a right-aligned _groff_ signature at the end of the
                  document (only if **-V** is also specified).
    


## Exit status



           _pre-grohtml_ and _post-grohtml_ each exit with status **0** on successful
           operation, status **2** if the program cannot interpret its command-
           line arguments, and status **1** if it encounters an error during
           operation.
    


## Environment



           _GROFF_FONT_PATH_
                  lists directories in which to search for _devhtml_ , _grohtml_ 's
                  directory of device and font description files.  See
                  _troff_(1) and _groff_font_(5).
    
           _SOURCE_DATE_EPOCH_
                  A timestamp (expressed as seconds since the Unix epoch) to
                  use as the output creation timestamp in place of the
                  current time.  The time is converted to human-readable form
                  using _gmtime_(3) and _asctime_(3), and recorded in an HTML
                  comment.
    
           _TZ_     The time zone to use when converting the current time to
                  human-readable form; see _tzset_(3).  If _SOURCE_DATE_EPOCH_ is
                  used, it is always converted to human-readable form using
                  UTC.
    


## Files



           _/usr/local/share/groff/1.23.0/font/devhtml/DESC_
                  describes the **html** output device.
    
           _/usr/local/share/groff/1.23.0/font/devhtml/_ F
                  describes the font known as _F_ on device **html**.
    
           _/usr/local/share/groff/1.23.0/tmac/html.tmac_
                  defines font mappings, special characters, and colors for
                  use with the **html** output device.  It is automatically
                  loaded by _troffrc_ when either of the **html** or **xhtml** output
                  devices is selected.
    
           _/usr/local/share/groff/1.23.0/tmac/html-end.tmac_
                  finalizes setup of the **html** output device.  It is
                  automatically loaded by _troffrc-end_ when either of the **html**
                  or **xhtml** output devices is selected.
    
           _grohtml_ uses temporary files.  See _groff_(1) for details about
           where such files are created.
    


## Bugs



           _grohtml_ is still beta code.
    
           _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 space but no line break.
    


## See also



           _groff_(1), _troff_(1), _groff_font_(5)
    


* * *