1grohtml(1) General Commands Manual grohtml(1)
2
6 grohtml, post-grohtml, pre-grohtml - groff output driver for HTML
7
9 pre-grohtml [-epV] [-a anti-aliasing-text-bits] [-D image-directory]
10 [-F font-directory] [-g anti-aliasing-graphic-bits] [-i
11 resolution] [-I image-stem] [-o image-vertical-offset] [-x
12 html-dialect] troff-command troff-argument ...
13 pre-grohtml --help
15 pre-grohtml -v
17 pre-grohtml --version
18 post-grohtml [-bCGhlnrVy] [-F font-directory] [-j output-stem] [-s
20 base-point-size] [-S heading-level] [-x html-dialect]
21 [file ...]
22 post-grohtml --help
24 post-grohtml -v
26 post-grohtml --version
27
29 The GNU roff system's HTML support consists of a preprocessor,
30 pre-grohtml, and an output driver, post-grohtml; together, they trans‐
31 late roff(7) documents to HTML. Because a preprocessor is (uniquely)
32 required for this output driver, users should invoke grohtml via the
33 groff(1) command with the -Thtml or -Txhtml options. (In this instal‐
34 lation, ps is the default output device.) Use groff's -P option to
35 pass any options shown above to grohtml. If no operands are given, or
36 if file is “-”, grohtml reads the standard input stream. Output is
37 written to the standard output stream.
38 grohtml invokes groff twice. In the first pass, the preprocessor
40 pre-grohtml renders pictures, equations, and tables as images in Post‐
41 Script format using the ps output device. In the second pass, the out‐
42 put driver post-grohtml translates the output of troff(1) to HTML.
43 grohtml writes output encoded in UTF-8 and has built-in HTML entities
45 for all non-composite Unicode characters. In spite of this, groff may
46 issue warnings about unknown special characters if they can't be found
47 during the first pass. Such warnings can be safely ignored unless the
48 special characters appear inside a table or equation.
49 Typefaces
51 grohtml supports the standard four styles: R (roman), I (italic), B
52 (bold), and BI (bold-italic). Fonts are grouped into families T and C
53 having members in each style.
54 TR Times roman
56 TI Times italic
57 TB Times bold
58 TBI Times bold-italic
59 CR Courier roman
60 CI Courier italic
61 CB Courier bold
62 CBI Courier bold-italic
63 A special font, S, is also provided to accommodate roff documents that
65 expect it to always be available.
66 Font description files
68 The font description files used with grohtml expose the same glyph
69 repertoire in their charset sections. See groff_font(5).
70 Dependencies
72 pre-grohtml generates an image whenever an eqn equation, tbl table, or
73 pic picture is encountered in the input. grohtml therefore may run
74 several commands as part of its operation. These include the Netpbm
75 tools pnmcrop, pnmcut, and pnmtopng; Ghostscript (gs); and the PSUtils
76 tool psselect.
77
79 --help displays a usage message, while -v and --version show version
80 information; all exit afterward.
81 -a anti-aliasing-text-bits
83 Number of bits of antialiasing information to be used by text
84 when generating PNG images. The default is 4 but 0, 1, and 2
85 are also valid. Your system's version of gs must support the
86 -dTextAlphaBits option in order to exploit antialiasing. A
87 value of 0 stops grohtml from issuing antialiasing commands to
88 gs.
89 -b Initialize the background color to white.
91 -C Suppress output of “CreationDate:” HTML comment.
93 -D image-directory
95 Instruct grohtml to place all image files into directory image-
96 directory.
97 -e Direct eqn to produce MathML.
99 This option should not be manually specified; it is synthesized
101 by groff depending on whether it was given the -Thtml or -Txhtml
102 option.
103 -F font-directory
105 Prepend directory font-directory/devname to the search path for
106 font and device description files; name is the name of the de‐
107 vice, usually html.
108 -g anti-aliasing-graphic-bits
110 Number of bits of antialiasing information to be used by graph‐
111 ics when generating PNG images. The default is 4 but 0, 1, and
112 2 are also valid. Your system's version of gs must support the
113 -dGraphicAlphaBits option in order to exploit antialiasing. A
114 value of 0 stops grohtml from issuing antialiasing commands to
115 gs.
116 -G Suppress output of “Creator:” HTML comment.
118 -h Generate section headings by using HTML B elements and increas‐
120 ing the font size, rather than HTML H elements.
121 -i resolution
123 Set the image resolution in pixels per inch; the default is 100.
124 -I image-stem
126 Determine the image file name stem. If omitted, grohtml uses
127 grohtml-XXXXX (where XXXXX is the process ID). A dash is ap‐
128 pended to the stem to separate it from the following image num‐
129 ber.
130 -j output-stem
132 Instruct grohtml to split the HTML output into multiple files.
133 Output is written to a new file at each section heading (but see
134 option -S below) named output-stem-n.html.
135 -l Turn off the production of automatic section links at the top of
137 the document.
138 -n Generate simple heading anchors whenever a section/number head‐
140 ing is found. Without the option the anchor value is the tex‐
141 tual heading. This can cause problems when a heading contains a
142 “?” on older versions of some browsers. This feature is auto‐
143 matically enabled if a heading contains an image.
144 -o image-vertical-offset
146 Specify the vertical offset of images in points.
147 -p Display page rendering progress to the standard error stream.
149 grohtml displays a page number only when an image is required.
150 -r Turn off the automatic header and footer line (HTML rule).
152 -s base-type-size
154 Set the document's base type size in points. When this size is
155 used in the source, it corresponds to the HTML base type size.
156 Every increase of two points in the source will produce a “big”
157 element, and conversely when a decrease of two points is seen, a
158 “small” element is emitted.
159 -S heading-level
161 When splitting HTML output (see option -j above), split at each
162 nested heading level defined by heading-level, or higher). The
163 default is 1.
164 -V Create an XHTML or HTML validator button at the bottom of each
166 page of the document.
167 -x html-dialect
169 Select HTML dialect. Currently, html-dialect should be either
170 the digit 4 or the letter x, which indicates whether grohtml
171 should generate HTML 4 or XHTML, respectively.
172 This option should not be manually specified; it is synthesized
174 by groff depending on whether it was given the -Thtml or -Txhtml
175 option.
176 -y Produce a right-aligned groff signature at the end of the docu‐
178 ment (only if -V is also specified).
179
181 GROFF_FONT_PATH
182 lists directories in which to search for devhtml, grohtml's di‐
183 rectory of device and font description files. See troff(1) and
184 groff_font(5).
185 SOURCE_DATE_EPOCH
187 A timestamp (expressed as seconds since the Unix epoch) to use
188 as the output creation timestamp in place of the current time.
189 The time is converted to human-readable form using ctime(3) and
190 recorded in an HTML comment.
191 TZ The time zone to use when converting the current time (or value
193 of SOURCE_DATE_EPOCH) to human-readable form; see tzset(3).
194
196 /usr/share/groff/1.23.0/font/devhtml/DESC
197 describes the html output device.
198 /usr/share/groff/1.23.0/font/devhtml/F
200 describes the font known as F on device html.
201 /usr/share/groff/1.23.0/tmac/html.tmac
203 defines font mappings, special characters, and colors for use
204 with the html output device. It is automatically loaded by
205 troffrc when either of the html or xhtml output devices is se‐
206 lected.
207 /usr/share/groff/1.23.0/tmac/html-end.tmac
209 finalizes setup of the html output device. It is automatically
210 loaded by troffrc-end when either of the html or xhtml output
211 devices is selected.
212 grohtml uses temporary files. See groff(1) for details about where
214 such files are created.
215
217 grohtml is still beta code.
218 grohtml does not truly support hyphenation, but you can fool it into
220 hyphenating long input lines, which can appear in HTML output with a
221 hyphenated word followed by a space but no line break.
222
224 groff(1), troff(1), groff_font(5)
225groff 1.23.0 2 November 2023 grohtml(1)