Debian Codegraph @

upstream/debian-unstable/man1/grohtml.1

raw
1 .TH grohtml 1 "2026-04-22" "groff 1.24.1"
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-2024 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\~\c
57 .IR anti-aliasing-text-bits ]
58 .RB [ \-D\~\c
59 .IR image-directory ]
60 .RB [ \-F\~\c
61 .IR font-directory ]
62 .RB [ \-g\~\c
63 .IR anti-aliasing-graphic-bits ]
64 .RB [ \-i\~\c
65 .IR resolution ]
66 .RB [ \-I\~\c
67 .IR image-stem ]
68 .RB [ \-o\~\c
69 .IR image-vertical-offset ]
70 .RB [ \-x\~\c
71 .IR html-dialect ]
72 .I troff-command
73 .I troff-argument
74 \&.\|.\|.
75 .YS
76 .
77 .
78 .P
79 .SY pre\-grohtml
80 .B \-\-help
81 .YS
82 .
83 .
84 .P
85 .SY pre\-grohtml
86 .B \-v
87 .YS
88 .
89 .SY pre\-grohtml
90 .B \%\-\-version
91 .YS
92 .
93 .
94 .P
95 .SY post\-grohtml
96 .RB [ \-bCGhlnrVy ]
97 .RB [ \-F\~\c
98 .IR font-directory ]
99 .RB [ \-j\~\c
100 .IR output-stem ]
101 .RB [ \-k\~\c
102 .IR encoding ]
103 .RB [ \-s\~\c
104 .IR base-point-size ]
105 .RB [ \-S\~\c
106 .IR heading-level ]
107 .RB [ \-x\~\c
108 .IR html-dialect ]
109 .RI [ file\~ .\|.\|.]
110 .YS
111 .
112 .
113 .P
114 .SY post\-grohtml
115 .B \-\-help
116 .YS
117 .
118 .
119 .P
120 .SY post\-grohtml
121 .B \-v
122 .YS
123 .
124 .SY post\-grohtml
125 .B \%\-\-version
126 .YS
127 .
128 .
129 .\" ====================================================================
130 .SH Description
131 .\" ====================================================================
132 .
133 The GNU
134 .I roff
135 system's HTML support consists of a preprocessor,
136 .IR \%pre\-grohtml ,
137 and an output driver,
138 .IR \%post\-grohtml ;
139 together,
140 they translate
141 .MR roff 7
142 documents to HTML.
143 .
144 Because a preprocessor is (uniquely) required for this output driver,
145 users should invoke
146 .I \%grohtml
147 via the
148 .MR groff 1
149 command with the
150 .B \-Thtml
151 or
152 .B \%\-Txhtml
153 options.
154 .
155 (In this installation,
156 .B \%ps
157 is the default output device.)
158 .
159 Use
160 .IR groff 's
161 .B \-P
162 option to pass any options shown above to
163 .IR \%grohtml .
164 .
165 If no operands are given,
166 or if
167 .I file
168 is
169 .RB \[lq] \- \[rq],
170 .I \%grohtml
171 reads the standard input stream.
172 .
173 It writes to the standard output stream.
174 .
175 .
176 .P
177 .I \%grohtml
178 invokes
179 .I groff
180 twice.
181 .
182 In the first pass,
183 the preprocessor
184 .I \%pre\-grohtml
185 renders
186 pictures,
187 equations,
188 and tables as images in PostScript format using the
189 .B ps
190 output device.
191 .
192 In the second pass,
193 the output driver
194 .I \%post\-grohtml
195 translates the output of
196 .MR \%troff 1
197 to HTML.
198 .
199 .
200 .P
201 .I \%grohtml
202 writes \%UTF-8-\:encoded output
203 (but see the
204 .B \-k
205 option)
206 and produces HTML character references
207 for most non-composite,
208 non-basic Latin
209 Unicode characters.
210 .\" XXX: Exception: degree sign (U+00B0). Why?
211 .
212 In spite of this,
213 .I groff
214 may issue warnings about unknown special characters if they can't be
215 found during the first pass.
216 .
217 You can ignore these warnings unless the special characters appear
218 inside a table or equation.
219 .\" XXX: or pic(1) description?
220 .
221 .
222 .\" ====================================================================
223 .SS Typefaces
224 .\" ====================================================================
225 .
226 .I \%grohtml
227 supports the standard four styles:
228 .B R
229 (roman),
230 .B I
231 .RI ( italic ),
232 .B B
233 .RB ( bold ),
234 and
235 .B BI
236 (\f[BI]bold-italic\f[]).
237 .
238 Fonts are grouped into families
239 .B T
240 and
241 .B C
242 having members in each style.
243 .
244 .
245 .RS
246 .TP
247 .B TR
248 Times roman
249 .
250 .TQ
251 .B TI
252 Times italic
253 .
254 .TQ
255 .B TB
256 Times bold
257 .
258 .TQ
259 .B TBI
260 Times bold-italic
261 .
262 .TQ
263 .B CR
264 Courier roman
265 .
266 .TQ
267 .B CI
268 Courier italic
269 .
270 .TQ
271 .B CB
272 Courier bold
273 .
274 .TQ
275 .B CBI
276 Courier bold-italic
277 .RE
278 .
279 .
280 .P
281 A special font,
282 .BR S ,
283 is also provided to accommodate
284 .I roff
285 documents that expect it to always be available.
286 .
287 .
288 .P
289 .I \%grohtml
290 furthermore supports a naming scheme for East Asian typefaces
291 shared with
292 .MR gropdf 1 ,
293 .MR grops 1 ,
294 and
295 .MR grotty 1 .
296 .
297 .
298 .RS
299 .TP
300 .B CSH
301 Simplified Chinese,
302 Hei style
303 .
304 .TQ
305 .B CSS
306 Simplified Chinese,
307 Song style
308 .
309 .TQ
310 .B CTH
311 Traditional Chinese,
312 Hei style
313 .
314 .TQ
315 .B CTS
316 Traditional Chinese,
317 Song style
318 .
319 .TQ
320 .B JPG
321 Japanese,
322 Gothic style
323 .
324 .TQ
325 .B JPM
326 Japanese,
327 Mincho style
328 .
329 .TQ
330 .B KOG
331 Korean,
332 Gothic style
333 .
334 .TQ
335 .B KOM
336 Korean,
337 Mincho style
338 .RE
339 .
340 .
341 .\" ====================================================================
342 .SS "Font description files"
343 .\" ====================================================================
344 .
345 The font description files used with
346 .I \%grohtml
347 expose the same glyph repertoire in their
348 .B charset
349 sections.
350 .
351 See
352 .MR groff_font 5 .
353 .
354 .
355 .\" ====================================================================
356 .SS Dependencies
357 .\" ====================================================================
358 .
359 .I \%pre\-grohtml
360 generates an image whenever an
361 .I \%eqn
362 equation,
363 .I \%tbl
364 table,
365 or
366 .I \%pic
367 picture is encountered in the input.
368 .
369 .I \%grohtml
370 therefore may run several commands as part of its operation.
371 .
372 These include the \%Netpbm tools
373 .IR \%pamcut ,
374 .IR \%pnmcrop ,
375 and
376 .IR \%pnmtopng ,
377 as well as
378 \%Ghostscript's
379 .I \%gs
380 and
381 .IR \%ps2ps .
382 .
383 .
384 .\" ====================================================================
385 .SH Options
386 .\" ====================================================================
387 .
388 .B \-\-help
389 displays a usage message,
390 while
391 .B \-v
392 and
393 .B \%\-\-version
394 show version information;
395 all exit afterward.
396 .
397 .
398 .TP
399 .BI \-a \~anti-aliasing-text-bits
400 Number of bits of antialiasing information to be used by text when
401 generating PNG images.
402 .
403 The default
404 .RB is\~ 4
405 but
406 .BR 0 ,
407 .BR 1 ,
408 and
409 .B 2
410 are also valid.
411 .
412 Your system's version of
413 .I gs
414 must support the
415 .B \%\-dTextAlphaBits
416 option in order to exploit antialiasing.
417 .\" XXX: How antiquated are the ones that don't? Get rid of this?
418 .
419 A value
420 .RB of\~ 0
421 stops
422 .I \%grohtml
423 from issuing antialiasing commands to
424 .IR gs .
425 .
426 .
427 .TP
428 .B \-b
429 Initialize the background color to white.
430 .
431 .
432 .TP
433 .B \-C
434 Suppress output of \[lq]CreationDate:\[rq] HTML comment.
435 .
436 .
437 .TP
438 .BI \-D \~image-directory
439 Instruct
440 .I \%grohtml
441 to place all image files into directory
442 .IR image-directory .
443 .
444 .
445 .TP
446 .B \-e
447 Direct
448 .I \%eqn
449 to produce MathML.
450 .
451 .
452 .IP
453 This option should not be manually specified;
454 it is synthesized by
455 .I groff
456 depending on whether it was given the
457 .B \-Thtml
458 or
459 .B \%\-Txhtml
460 option.
461 .
462 .
463 .TP
464 .BI \-F \~font-directory
465 Prepend directory
466 .RI font-directory /dev name
467 to the search path for font and device description files;
468 .I name
469 is the name of the device,
470 usually
471 .BR html .
472 .
473 .
474 .TP
475 .BI \-g \~anti-aliasing-graphic-bits
476 Number of bits of antialiasing information to be used by graphics when
477 generating PNG images.
478 .
479 The default
480 .RB is\~ 4
481 but
482 .BR 0 ,
483 .BR 1 ,
484 and
485 .B 2
486 are also valid.
487 .
488 Your system's version of
489 .I gs
490 must support the
491 .B \%\-dGraphicAlphaBits
492 option in order to exploit antialiasing.
493 .\" XXX: How antiquated are the ones that don't? Get rid of this?
494 .
495 A value
496 .RB of\~ 0
497 stops
498 .I \%grohtml
499 from issuing antialiasing commands to
500 .IR gs .
501 .
502 .
503 .TP
504 .B \-G
505 Suppress output of \[lq]Creator:\[rq] HTML comment.
506 .
507 .
508 .TP
509 .B \-h
510 Generate section headings by using HTML
511 .B B
512 elements and increasing the font size,
513 rather than HTML
514 .B H
515 elements.
516 .
517 .
518 .TP
519 .BI \-i \~resolution
520 Set the image resolution in pixels per inch;
521 the default
522 .RB is\~ 100 .
523 .
524 .
525 .TP
526 .BI \-I \~image-stem
527 Determine the image file name stem.
528 .
529 If omitted,
530 .I \%grohtml
531 uses
532 .IR \%grohtml\- XXXXX
533 (where
534 .I XXXXX
535 is the process ID).
536 .
537 A dash is appended to the stem to separate it from the following image
538 number.
539 .
540 .
541 .TP
542 .BI \-j \~output-stem
543 Instruct
544 .I \%grohtml
545 to split the HTML output into multiple files.
546 .
547 Output is written to a new file at each section heading
548 (but see option
549 .B \-S
550 below)
551 named
552 .IR output-stem\- n .html .
553 .
554 .
555 .br
556 .ne 4v
557 .TP
558 .BI \-k \~encoding
559 Select the character encoding used in the generated document,
560 affecting the declared encoding in the preamble
561 and the form of character entity references.
562 .
563 .\" XXX: Don't present "mixed" until we know what it's for.
564 Valid values are \[lq]ASCII\[rq] and \[lq]UTF\-8\[rq].
565 .
566 The default is \[lq]UTF-8\[rq].
567 .
568 .
569 .TP
570 .B \-l
571 Turn off the production of automatic section links at the top of the
572 document.
573 .
574 .
575 .TP
576 .B \-n
577 Generate simple heading anchors whenever a section/number heading is
578 found.
579 .
580 Without the option the anchor value is the textual heading.
581 .
582 This can cause problems when a heading contains a \[lq]?\[rq] on older
583 versions of some browsers.
584 .
585 This feature is automatically enabled if a heading contains an image.
586 .
587 .
588 .TP
589 .BI \-o \~image-vertical-offset
590 Specify the vertical offset of images in points.
591 .
592 .
593 .TP
594 .B \-p
595 Display page rendering progress to the standard error stream.
596 .
597 .I \%grohtml
598 displays a page number only when an image is required.
599 .
600 .
601 .TP
602 .B \-r
603 Turn off the automatic header and footer line
604 (HTML rule).
605 .
606 .
607 .TP
608 .BI \-s \~base-type-size
609 Set the document's base type size in points.
610 .
611 When this size is used in the source,
612 it corresponds to the HTML base type size.
613 .
614 Every increase of two points in the source will produce a
615 .RB \[lq] big \[rq]
616 element,
617 and conversely when a decrease of two points is seen,
618 a
619 .RB \[lq] small \[rq]
620 element is emitted.
621 .
622 .
623 .TP
624 .BI \-S \~heading-level
625 When splitting HTML output
626 (see option
627 .B \-j
628 above),
629 split at each nested heading level defined by
630 .IR heading-level ,
631 or higher).
632 .
633 The default is
634 .BR 1 .
635 .
636 .
637 .TP
638 .B \-V
639 Create an XHTML or HTML validator button at the bottom of each page of
640 the document.
641 .
642 .
643 .TP
644 .BI \-x \~html-dialect
645 Select HTML dialect.
646 .
647 Currently,
648 .I html-dialect
649 should be either the
650 .RB digit\~ 4
651 or the
652 .RB letter\~ x ,
653 which indicates whether
654 .I \%grohtml
655 should generate HTML\~4 or XHTML,
656 respectively.
657 .
658 .
659 .IP
660 This option should not be manually specified;
661 it is synthesized by
662 .I groff
663 depending on whether it was given the
664 .B \-Thtml
665 or
666 .B \%\-Txhtml
667 option.
668 .
669 .
670 .TP
671 .B \-y
672 Produce a right-aligned
673 .I groff
674 signature at the end of the document
675 (only if
676 .B \-V
677 is also specified).
678 .
679 .
680 .\" ====================================================================
681 .SH "Exit status"
682 .\" ====================================================================
683 .
684 .I \%pre\-grohtml
685 and
686 .I \%post\-grohtml
687 each exit with
688 .RB status\~ 0
689 on successful operation,
690 .RB status\~ 2
691 if the program cannot interpret its command-line arguments,
692 and
693 .RB status\~ 1
694 if it encounters an error during operation.
695 .
696 .
697 .\" ====================================================================
698 .SH Environment
699 .\" ====================================================================
700 .
701 .TP
702 .I GROFF_FONT_PATH
703 lists directories in which to search for
704 .IR devhtml ,
705 .IR grohtml 's
706 directory of device and font description files.
707 .
708 See
709 .MR \%troff 1
710 and
711 .MR groff_font 5 .
712 .
713 .
714 .TP
715 .I SOURCE_DATE_EPOCH
716 A timestamp
717 (expressed as seconds since the Unix epoch)
718 to use as the output creation timestamp in place of the current time.
719 .
720 The time is converted to human-readable form using
721 .MR gmtime 3
722 and
723 .MR asctime 3 ,
724 and recorded in an HTML comment.
725 .
726 .
727 .TP
728 .I TZ
729 The time zone to use when converting the current time to human-readable form;
730 see
731 .MR tzset 3 .
732 If
733 .I SOURCE_DATE_EPOCH
734 is used, it is always converted to human-readable form using UTC.
735 .
736 .
737 .\" ====================================================================
738 .SH Files
739 .\" ====================================================================
740 .
741 .TP
742 .I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%font/\:\%devhtml/\:DESC
743 describes the
744 .B html
745 output device.
746 .
747 .
748 .TP
749 .IR /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%font/\:\%devhtml/ F
750 describes the font known
751 .RI as\~ F
752 on device
753 .BR html .
754 .
755 .
756 .TP
757 .I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/\:html\:.tmac
758 defines font mappings,
759 special characters,
760 and colors for use with the
761 .B html
762 output device.
763 .
764 It is automatically loaded by
765 .I \%troffrc
766 when either of the
767 .B html
768 or
769 .B xhtml
770 output devices is selected.
771 .
772 .
773 .TP
774 .I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/\:html\-end\:.tmac
775 finalizes setup of the
776 .B html
777 output device.
778 .
779 It is automatically loaded by
780 .I \%troffrc\-end
781 when either of the
782 .B html
783 or
784 .B xhtml
785 output devices is selected.
786 .
787 .
788 .P
789 .I \%grohtml
790 uses temporary files.
791 .
792 See
793 .MR groff 1
794 for details about where such files are created.
795 .
796 .
797 .\" ====================================================================
798 .SH Bugs
799 .\" ====================================================================
800 .
801 .I \%grohtml
802 is still beta code.
803 .
804 .
805 .PP
806 .I \%grohtml
807 does not truly support hyphenation,
808 but you can fool it into hyphenating long input lines,
809 which can appear in HTML output with a hyphenated word followed by a
810 space but no line break.
811 .
812 .
813 .\" ====================================================================
814 .SH "See also"
815 .\" ====================================================================
816 .
817 .\" IR afmtodit (1),
818 .MR groff 1 ,
819 .MR \%troff 1 ,
820 .\" IR psbb (1), \" XXX: what is this?
821 .\" IR groff_out (5),
822 .\" IR groff_char (7),
823 .MR groff_font 5
824 .
825 .
826 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
827 .cp \n[*groff_grohtml_1_man_C]
828 .do rr *groff_grohtml_1_man_C
829 .
830 .
831 .\" Local Variables:
832 .\" fill-column: 72
833 .\" mode: nroff
834 .\" End:
835 .\" vim: set filetype=groff textwidth=72: