Debian Codegraph @

upstream/debian-trixie/man1/grohtml.1

raw
1 .TH grohtml 1 "3 June 2025" "groff 1.23.0"
2 .SH Name
3 grohtml, post\-grohtml, pre\-grohtml \-
4 .I groff
5 output driver for HTML
6 .
7 .
8 .\" ====================================================================
9 .\" Legal Terms
10 .\" ====================================================================
11 .\"
12 .\" Copyright (C) 1999-2022 Free Software Foundation, Inc.
13 .\"
14 .\" Permission is granted to make and distribute verbatim copies of this
15 .\" manual provided the copyright notice and this permission notice are
16 .\" preserved on all copies.
17 .\"
18 .\" Permission is granted to copy and distribute modified versions of
19 .\" this manual under the conditions for verbatim copying, provided that
20 .\" the entire resulting derived work is distributed under the terms of
21 .\" a permission notice identical to this one.
22 .\"
23 .\" Permission is granted to copy and distribute translations of this
24 .\" manual into another language, under the above conditions for
25 .\" modified versions, except that this permission notice may be
26 .\" included in translations approved by the Free Software Foundation
27 .\" instead of in the original English.
28 .
29 .
30 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
31 .do nr *groff_grohtml_1_man_C \n[.cp]
32 .cp 0
33 .
34 .\" Define fallback for groff 1.23's MR macro if the system lacks it.
35 .nr do-fallback 0
36 .if !\n(.f .nr do-fallback 1 \" mandoc
37 .if \n(.g .if !d MR .nr do-fallback 1 \" older groff
38 .if !\n(.g .nr do-fallback 1 \" non-groff *roff
39 .if \n[do-fallback] \{\
40 . de MR
41 . ie \\n(.$=1 \
42 . I \%\\$1
43 . el \
44 . IR \%\\$1 (\\$2)\\$3
45 . .
46 .\}
47 .rr do-fallback
48 .
49 .
50 .\" ====================================================================
51 .SH Synopsis
52 .\" ====================================================================
53 .
54 .SY pre\-grohtml
55 .RB [ \-epV ]
56 .RB [ \-a
57 .IR anti-aliasing-text-bits ]
58 .RB [ \-D
59 .IR image-directory ]
60 .RB [ \-F
61 .IR font-directory ]
62 .RB [ \-g
63 .IR anti-aliasing-graphic-bits ]
64 .RB [ \-i
65 .IR resolution ]
66 .RB [ \-I
67 .IR image-stem ]
68 .RB [ \-o
69 .IR image-vertical-offset ]
70 .RB [ \-x
71 .IR html-dialect ]
72 .I troff-command
73 .I troff-argument
74 \&.\|.\|.
75 .YS
76 .
77 .
78 .SY pre\-grohtml
79 .B \-\-help
80 .YS
81 .
82 .
83 .SY pre\-grohtml
84 .B \-v
85 .
86 .SY pre\-grohtml
87 .B \-\-version
88 .YS
89 .
90 .
91 .SY post\-grohtml
92 .RB [ \-bCGhlnrVy ]
93 .RB [ \-F
94 .IR font-directory ]
95 .RB [ \-j
96 .IR output-stem ]
97 .RB [ \-s
98 .IR base-point-size ]
99 .RB [ \-S
100 .IR heading-level ]
101 .RB [ \-x
102 .IR html-dialect ]
103 .RI [ file\~ .\|.\|.]
104 .YS
105 .
106 .
107 .SY post\-grohtml
108 .B \-\-help
109 .YS
110 .
111 .
112 .SY post\-grohtml
113 .B \-v
114 .
115 .SY post\-grohtml
116 .B \-\-version
117 .YS
118 .
119 .
120 .\" ====================================================================
121 .SH Description
122 .\" ====================================================================
123 .
124 The GNU
125 .I roff
126 system's HTML support consists of a preprocessor,
127 .IR \%pre\-grohtml ,
128 and an output driver,
129 .IR \%post\-grohtml ;
130 together,
131 they translate
132 .MR roff 7
133 documents to HTML.
134 .
135 Because a preprocessor is (uniquely) required for this output driver,
136 users should invoke
137 .I \%grohtml
138 via the
139 .MR groff 1
140 command with the
141 .B \-Thtml
142 or
143 .B \-Txhtml
144 options.
145 .
146 (In this installation,
147 .B \%ps
148 is the default output device.)
149 .
150 Use
151 .IR groff 's
152 .B \-P
153 option to pass any options shown above to
154 .IR \%grohtml .
155 .
156 If no operands are given,
157 or if
158 .I file
159 is
160 .RB \[lq] \- \[rq],
161 .I \%grohtml
162 reads the standard input stream.
163 .
164 Output is written to the standard output stream.
165 .
166 .
167 .P
168 .I \%grohtml
169 invokes
170 .I groff
171 twice.
172 .
173 In the first pass,
174 the preprocessor
175 .I \%pre\-grohtml
176 renders
177 pictures,
178 equations,
179 and tables as images in PostScript format using the
180 .B ps
181 output device.
182 .
183 In the second pass,
184 the output driver
185 .I \%post\-grohtml
186 translates the output of
187 .MR \%troff 1
188 to HTML.
189 .
190 .
191 .P
192 .I \%grohtml
193 writes output encoded in \%UTF-8 and has built-in HTML entities for all
194 non-composite Unicode characters.
195 .
196 In spite of this,
197 .I groff
198 may issue warnings about unknown special characters if they can't be
199 found during the first pass.
200 .
201 Such warnings can be safely ignored unless the special characters
202 appear inside a table or equation.
203 .
204 .
205 .\" ====================================================================
206 .SS Typefaces
207 .\" ====================================================================
208 .
209 .I \%grohtml
210 supports the standard four styles:
211 .B R
212 (roman),
213 .B I
214 .RI ( italic ),
215 .B B
216 .RB ( bold ),
217 and
218 .B BI
219 (\f[BI]bold-italic\f[]).
220 .
221 Fonts are grouped into families
222 .B T
223 and
224 .B C
225 having members in each style.
226 .
227 .
228 .RS
229 .TP
230 .B TR
231 Times roman
232 .
233 .TQ
234 .B TI
235 Times italic
236 .
237 .TQ
238 .B TB
239 Times bold
240 .
241 .TQ
242 .B TBI
243 Times bold-italic
244 .
245 .TQ
246 .B CR
247 Courier roman
248 .
249 .TQ
250 .B CI
251 Courier italic
252 .
253 .TQ
254 .B CB
255 Courier bold
256 .
257 .TQ
258 .B CBI
259 Courier bold-italic
260 .RE
261 .
262 .
263 .P
264 A special font,
265 .BR S ,
266 is also provided to accommodate
267 .I roff
268 documents that expect it to always be available.
269 .
270 .
271 .\" ====================================================================
272 .SS "Font description files"
273 .\" ====================================================================
274 .
275 The font description files used with
276 .I \%grohtml
277 expose the same glyph repertoire in their
278 .B charset
279 sections.
280 .
281 See
282 .MR groff_font 5 .
283 .
284 .
285 .\" ====================================================================
286 .SS Dependencies
287 .\" ====================================================================
288 .
289 .I \%pre\-grohtml
290 generates an image whenever an
291 .I \%eqn
292 equation,
293 .I \%tbl
294 table,
295 or
296 .I \%pic
297 picture is encountered in the input.
298 .
299 .I \%grohtml
300 therefore may run several commands as part of its operation.
301 .
302 These include the \%Netpbm tools
303 .IR \%pnmcrop ,
304 .IR \%pnmcut ,
305 and
306 .IR \%pnmtopng ;
307 \%Ghostscript
308 .RI ( gs );
309 and the \%PSUtils tool
310 .IR \%psselect .
311 .
312 .
313 .\" ====================================================================
314 .SH Options
315 .\" ====================================================================
316 .
317 .B \-\-help
318 displays a usage message,
319 while
320 .B \-v
321 and
322 .B \-\-version
323 show version information;
324 all exit afterward.
325 .
326 .
327 .TP
328 .BI \-a \~anti-aliasing-text-bits
329 Number of bits of antialiasing information to be used by text when
330 generating PNG images.
331 .
332 The default
333 .RB is\~ 4
334 but
335 .BR 0 ,
336 .BR 1 ,
337 and
338 .B 2
339 are also valid.
340 .
341 Your system's version of
342 .I gs
343 must support the
344 .B \%\-dTextAlphaBits
345 option in order to exploit antialiasing.
346 .\" XXX: How antiquated are the ones that don't? Get rid of this?
347 .
348 A value
349 .RB of\~ 0
350 stops
351 .I \%grohtml
352 from issuing antialiasing commands to
353 .IR gs .
354 .
355 .
356 .TP
357 .B \-b
358 Initialize the background color to white.
359 .
360 .
361 .TP
362 .B \-C
363 Suppress output of \[lq]CreationDate:\[rq] HTML comment.
364 .
365 .
366 .TP
367 .BI \-D \~image-directory
368 Instruct
369 .I \%grohtml
370 to place all image files into directory
371 .IR image-directory .
372 .
373 .
374 .TP
375 .B \-e
376 Direct
377 .I \%eqn
378 to produce MathML.
379 .
380 .
381 .IP
382 This option should not be manually specified;
383 it is synthesized by
384 .I groff
385 depending on whether it was given the
386 .B \-Thtml
387 or
388 .B \-Txhtml
389 option.
390 .
391 .
392 .TP
393 .BI \-F \~font-directory
394 Prepend directory
395 .RI font-directory /dev name
396 to the search path for font and device description files;
397 .I name
398 is the name of the device,
399 usually
400 .BR html .
401 .
402 .
403 .TP
404 .BI \-g \~anti-aliasing-graphic-bits
405 Number of bits of antialiasing information to be used by graphics when
406 generating PNG images.
407 .
408 The default
409 .RB is\~ 4
410 but
411 .BR 0 ,
412 .BR 1 ,
413 and
414 .B 2
415 are also valid.
416 .
417 Your system's version of
418 .I gs
419 must support the
420 .B \%\-dGraphicAlphaBits
421 option in order to exploit antialiasing.
422 .\" XXX: How antiquated are the ones that don't? Get rid of this?
423 .
424 A value
425 .RB of\~ 0
426 stops
427 .I \%grohtml
428 from issuing antialiasing commands to
429 .IR gs .
430 .
431 .
432 .TP
433 .B \-G
434 Suppress output of \[lq]Creator:\[rq] HTML comment.
435 .
436 .
437 .TP
438 .B \-h
439 Generate section headings by using HTML
440 .B B
441 elements and increasing the font size,
442 rather than HTML
443 .B H
444 elements.
445 .
446 .
447 .TP
448 .BI \-i \~resolution
449 Set the image resolution in pixels per inch;
450 the default
451 .RB is\~ 100 .
452 .
453 .
454 .TP
455 .BI \-I \~image-stem
456 Determine the image file name stem.
457 .
458 If omitted,
459 .I \%grohtml
460 uses
461 .IR \%grohtml\- XXXXX
462 (where
463 .I XXXXX
464 is the process ID).
465 .
466 A dash is appended to the stem to separate it from the following image
467 number.
468 .
469 .
470 .TP
471 .BI \-j \~output-stem
472 Instruct
473 .I \%grohtml
474 to split the HTML output into multiple files.
475 .
476 Output is written to a new file at each section heading
477 (but see option
478 .B \-S
479 below)
480 named
481 .IR output-stem\- n .html .
482 .
483 .
484 .TP
485 .B \-l
486 Turn off the production of automatic section links at the top of the
487 document.
488 .
489 .
490 .TP
491 .B \-n
492 Generate simple heading anchors whenever a section/number heading is
493 found.
494 .
495 Without the option the anchor value is the textual heading.
496 .
497 This can cause problems when a heading contains a \[lq]?\[rq] on older
498 versions of some browsers.
499 .
500 This feature is automatically enabled if a heading contains an image.
501 .
502 .
503 .TP
504 .BI \-o \~image-vertical-offset
505 Specify the vertical offset of images in points.
506 .
507 .
508 .TP
509 .B \-p
510 Display page rendering progress to the standard error stream.
511 .
512 .I \%grohtml
513 displays a page number only when an image is required.
514 .
515 .
516 .TP
517 .B \-r
518 Turn off the automatic header and footer line
519 (HTML rule).
520 .
521 .
522 .TP
523 .BI \-s \~base-type-size
524 Set the document's base type size in points.
525 .
526 When this size is used in the source,
527 it corresponds to the HTML base type size.
528 .
529 Every increase of two points in the source will produce a
530 .RB \[lq] big \[rq]
531 element,
532 and conversely when a decrease of two points is seen,
533 a
534 .RB \[lq] small \[rq]
535 element is emitted.
536 .
537 .
538 .TP
539 .BI \-S \~heading-level
540 When splitting HTML output
541 (see option
542 .B \-j
543 above),
544 split at each nested heading level defined by
545 .IR heading-level ,
546 or higher).
547 .
548 The default is
549 .BR 1 .
550 .
551 .
552 .TP
553 .B \-V
554 Create an XHTML or HTML validator button at the bottom of each page of
555 the document.
556 .
557 .
558 .TP
559 .BI \-x \~html-dialect
560 Select HTML dialect.
561 .
562 Currently,
563 .I html-dialect
564 should be either the
565 .RB digit\~ 4
566 or the
567 .RB letter\~ x ,
568 which indicates whether
569 .I \%grohtml
570 should generate HTML\~4 or XHTML,
571 respectively.
572 .
573 .
574 .IP
575 This option should not be manually specified;
576 it is synthesized by
577 .I groff
578 depending on whether it was given the
579 .B \-Thtml
580 or
581 .B \-Txhtml
582 option.
583 .
584 .
585 .TP
586 .B \-y
587 Produce a right-aligned
588 .I groff
589 signature at the end of the document
590 (only if
591 .B \-V
592 is also specified).
593 .
594 .
595 .\" ====================================================================
596 .SH Environment
597 .\" ====================================================================
598 .
599 .TP
600 .I GROFF_FONT_PATH
601 lists directories in which to search for
602 .IR devhtml ,
603 .IR grohtml 's
604 directory of device and font description files.
605 .
606 See
607 .MR \%troff 1
608 and
609 .MR groff_font 5 .
610 .
611 .
612 .TP
613 .I SOURCE_DATE_EPOCH
614 A timestamp
615 (expressed as seconds since the Unix epoch)
616 to use as the output creation timestamp in place of the current time.
617 .
618 The time is converted to human-readable form using
619 .MR gmtime 3
620 and
621 .MR asctime 3 ,
622 and recorded in an HTML comment.
623 .
624 .
625 .TP
626 .I TZ
627 The time zone to use when converting the current time to human-readable form;
628 see
629 .MR tzset 3 .
630 If
631 .I SOURCE_DATE_EPOCH
632 is used, it is always converted to human-readable form using UTC.
633 .
634 .
635 .\" ====================================================================
636 .SH Files
637 .\" ====================================================================
638 .
639 .TP
640 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devhtml/\:DESC
641 describes the
642 .B html
643 output device.
644 .
645 .
646 .TP
647 .IR /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font/\:\%devhtml/ F
648 describes the font known
649 .RI as\~ F
650 on device
651 .BR html .
652 .
653 .
654 .TP
655 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:html\:.tmac
656 defines font mappings,
657 special characters,
658 and colors for use with the
659 .B html
660 output device.
661 .
662 It is automatically loaded by
663 .I \%troffrc
664 when either of the
665 .B html
666 or
667 .B xhtml
668 output devices is selected.
669 .
670 .
671 .TP
672 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:html\-end\:.tmac
673 finalizes setup of the
674 .B html
675 output device.
676 .
677 It is automatically loaded by
678 .I \%troffrc\-end
679 when either of the
680 .B html
681 or
682 .B xhtml
683 output devices is selected.
684 .
685 .
686 .P
687 .I \%grohtml
688 uses temporary files.
689 .
690 See
691 .MR groff 1
692 for details about where such files are created.
693 .
694 .
695 .\" ====================================================================
696 .SH Bugs
697 .\" ====================================================================
698 .
699 .I \%grohtml
700 is still beta code.
701 .
702 .
703 .PP
704 .I \%grohtml
705 does not truly support hyphenation,
706 but you can fool it into hyphenating long input lines,
707 which can appear in HTML output with a hyphenated word followed by a
708 space but no line break.
709 .
710 .
711 .\" ====================================================================
712 .SH "See also"
713 .\" ====================================================================
714 .
715 .\" IR afmtodit (1),
716 .MR groff 1 ,
717 .MR \%troff 1 ,
718 .\" IR psbb (1), \" XXX: what is this?
719 .\" IR groff_out (5),
720 .\" IR groff_char (7),
721 .MR groff_font 5
722 .
723 .
724 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
725 .cp \n[*groff_grohtml_1_man_C]
726 .do rr *groff_grohtml_1_man_C
727 .
728 .
729 .\" Local Variables:
730 .\" fill-column: 72
731 .\" mode: nroff
732 .\" End:
733 .\" vim: set filetype=groff textwidth=72: