Debian Codegraph @

upstream/debian-trixie/man1/groff.1

raw
1 .TH groff 1 "3 June 2025" "groff 1.23.0"
2 .SH Name
3 groff \- front end to the GNU
4 .I roff
5 document formatting system
6 .
7 .
8 .\" ====================================================================
9 .\" Legal Terms
10 .\" ====================================================================
11 .\"
12 .\" Copyright (C) 1989-2022 Free Software Foundation, Inc.
13 .\"
14 .\" This file is part of groff, the GNU roff type-setting system.
15 .\"
16 .\" Permission is granted to copy, distribute and/or modify this
17 .\" document under the terms of the GNU Free Documentation License,
18 .\" Version 1.3 or any later version published by the Free Software
19 .\" Foundation; with no Invariant Sections, with no Front-Cover Texts,
20 .\" and with no Back-Cover Texts.
21 .\"
22 .\" A copy of the Free Documentation License is included as a file
23 .\" called FDL in the main directory of the groff source package.
24 .\"
25 .\" A copy of the GNU Free Documentation License is also available in this
26 .\" Debian package as /usr/share/doc/groff-base/copyright.
27 .
28 .
29 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
30 .do nr *groff_groff_1_man_C \n[.cp]
31 .cp 0
32 .
33 .\" Define fallback for groff 1.23's MR macro if the system lacks it.
34 .nr do-fallback 0
35 .if !\n(.f .nr do-fallback 1 \" mandoc
36 .if \n(.g .if !d MR .nr do-fallback 1 \" older groff
37 .if !\n(.g .nr do-fallback 1 \" non-groff *roff
38 .if \n[do-fallback] \{\
39 . de MR
40 . ie \\n(.$=1 \
41 . I \%\\$1
42 . el \
43 . IR \%\\$1 (\\$2)\\$3
44 . .
45 .\}
46 .rr do-fallback
47 .
48 .\" Define a string for the TeX logo.
49 .ie t .ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
50 .el .ds TeX TeX
51 .
52 .\" ====================================================================
53 .SH Synopsis
54 .\" ====================================================================
55 .
56 .SY groff
57 .RB [ \-abcCeEgGijklNpRsStUVXzZ ]
58 .RB [ \-d\~\c
59 .IR ctext ]
60 .RB [ \-d\~\c
61 .IB string =\c
62 .IR text ]
63 .RB [ \-D\~\c
64 .IR fallback-encoding ]
65 .RB [ \-f\~\c
66 .IR font-family ]
67 .RB [ \-F\~\c
68 .IR font-directory ]
69 .RB [ \-I\~\c
70 .IR inclusion-directory ]
71 .RB [ \-K\~\c
72 .IR input-encoding ]
73 .RB [ \-L\~\c
74 .IR spooler-argument ]
75 .RB [ \-m\~\c
76 .IR macro-package ]
77 .RB [ \-M\~\c
78 .IR macro-directory ]
79 .RB [ \-n\~\c
80 .IR page-number ]
81 .RB [ \-o\~\c
82 .IR page-list ]
83 .RB [ \-P\~\c
84 .IR postprocessor-argument ]
85 .RB [ \-r\~\c
86 .IR cnumeric-expression ]
87 .RB [ \-r\~\c
88 .IB register =\c
89 .IR numeric-expression ]
90 .RB [ \-T\~\c
91 .IR output-device ]
92 .RB [ \-w\~\c
93 .IR warning-category ]
94 .RB [ \-W\~\c
95 .IR warning-category ]
96 .RI [ file\~ .\|.\|.]
97 .YS
98 .
99 .
100 .SY groff
101 .B \-h
102 .
103 .SY groff
104 .B \-\-help
105 .YS
106 .
107 .
108 .SY groff
109 .B \-v
110 .RI [ option\~ .\|.\|.\&]
111 .RI [ file\~ .\|.\|.]
112 .
113 .SY groff
114 .B \-\-version
115 .RI [ option\~ .\|.\|.\&]
116 .RI [ file\~ .\|.\|.]
117 .YS
118 .
119 .
120 .\" ====================================================================
121 .SH Description
122 .\" ====================================================================
123 .
124 .I groff
125 is the primary front end to the GNU
126 .I roff
127 document formatting system.
128 .
129 .\" BEGIN Keep parallel with groff.texi node "What Is groff?".
130 .\" This language is slightly expanded from that in the "ANNOUNCE" file
131 .\" and on the groff home page.
132 GNU
133 .I roff
134 is a typesetting system that reads plain text input files that include
135 formatting commands to produce output in PostScript,
136 PDF,
137 HTML,
138 DVI,
139 or other formats,
140 or for display to a terminal.
141 .
142 Formatting commands can be low-level typesetting primitives,
143 macros from a supplied package,
144 or user-defined macros.
145 .
146 All three approaches can be combined.
147 .
148 If no
149 .I file
150 operands are specified,
151 or if
152 .I file
153 is
154 .RB \[lq] \- \[rq],
155 .I groff
156 reads the standard input stream.
157 .
158 .
159 .P
160 A reimplementation and extension of the typesetter from AT&T Unix,
161 .I groff
162 is present on most POSIX systems owing to its long association with Unix
163 manuals
164 (including man pages).
165 .
166 It and its predecessor are notable for their production of several
167 best-selling software engineering texts.
168 .
169 .I groff
170 is capable of producing typographically sophisticated documents while
171 consuming minimal system resources.
172 .\" END Keep parallel with groff.texi node "What Is groff?".
173 .
174 .
175 .P
176 The
177 .I groff
178 command orchestrates the execution of preprocessors,
179 the transformation of input documents into a device-independent page
180 description language,
181 and the production of output from that language.
182 .
183 .
184 .\" ====================================================================
185 .SH Options
186 .\" ====================================================================
187 .
188 .B \-h
189 and
190 .B \-\-help
191 display a usage message and exit.
192 .
193 .
194 .P
195 Because
196 .I groff
197 is intended to subsume most users' direct invocations of the
198 .MR \%troff 1
199 formatter,
200 the two programs share a set of options.
201 .
202 However,
203 .I groff
204 has some options that
205 .I \%troff
206 does not share,
207 and others which
208 .I groff
209 interprets differently.
210 .
211 At the same time,
212 not all valid
213 .I \%troff
214 options can be given to
215 .IR groff .
216 .
217 .
218 .\" ====================================================================
219 .SS "\f[I]groff\f[]-specific options"
220 .\" ====================================================================
221 .
222 The following options either do not exist in
223 GNU
224 .I troff \" GNU
225 or are interpreted differently by
226 .IR groff .
227 .
228 .
229 .TP
230 .BI \-D\~ enc
231 Set fallback input encoding used by
232 .MR preconv 1
233 to
234 .IR enc ;
235 implies
236 .BR \-k .
237 .
238 .
239 .TP
240 .B \-e
241 Run
242 .MR \%eqn 1
243 preprocessor.
244 .
245 .
246 .TP
247 .B \-g
248 Run
249 .MR \%grn 1
250 preprocessor.
251 .
252 .
253 .TP
254 .B \-G
255 Run
256 .MR grap 1
257 preprocessor;
258 implies
259 .BR \-p .
260 .
261 .
262 .TP
263 .BI \-I\~ dir
264 Works as
265 .IR \%troff 's
266 option
267 (see below),
268 but also implies
269 .B \-g
270 and
271 .BR \-s .
272 .
273 It is passed to
274 .MR \%soelim 1
275 and the output driver,
276 and
277 .I \%grn
278 is passed an
279 .B \-M
280 option with
281 .I dir
282 as its argument.
283 .
284 .
285 .TP
286 .B \-j
287 Run
288 .MR \%chem 1
289 preprocessor;
290 implies
291 .BR \-p .
292 .
293 .
294 .TP
295 .B \-k
296 Run
297 .MR preconv 1
298 preprocessor.
299 .
300 Refer to its man page for its behavior if neither of
301 .IR groff 's
302 .B \-K
303 or
304 .B \-D
305 options is also specified.
306 .
307 .
308 .TP
309 .BI \-K\~ enc
310 Set input encoding used by
311 .MR preconv 1
312 to
313 .IR enc ;
314 implies
315 .BR \-k .
316 .
317 .
318 .TP
319 .B \-l
320 Send the output to a spooler program for printing.
321 .
322 The
323 .RB \[lq] print \[rq]
324 directive in the device description file
325 specifies the default command to be used;
326 see
327 .MR groff_font 5 .
328 .
329 If no such directive is present for the output device,
330 .ie 'lpr'' \{\
331 this option is ignored.
332 .\}
333 .el \{\
334 output is piped to
335 .MR lpr 1 .
336 .\}
337 .
338 See options
339 .B \-L
340 and
341 .BR \-X .
342 .
343 .
344 .TP
345 .BI \-L\~ arg
346 Pass
347 .I arg
348 to the print spooler program.
349 .
350 If multiple
351 .IR arg s
352 are required,
353 pass each with a separate
354 .B \-L
355 option.
356 .
357 .I groff
358 does not prefix an option dash to
359 .I arg
360 before passing it to the spooler program.
361 .
362 .
363 .TP
364 .B \-M
365 Works as
366 .IR \%troff 's
367 option
368 (see below),
369 but is also passed to
370 .MR \%eqn 1 ,
371 .MR grap 1 ,
372 and
373 .MR \%grn 1 .
374 .
375 .
376 .TP
377 .B \-N
378 Prohibit newlines between
379 .I eqn \" language
380 delimiters:
381 pass
382 .B \-N
383 to
384 .MR \%eqn 1 .
385 .
386 .
387 .TP
388 .B \-p
389 Run
390 .MR \%pic 1
391 preprocessor.
392 .
393 .
394 .TP
395 .BI \-P\~ arg
396 Pass
397 .I arg
398 to the postprocessor.
399 .
400 If multiple
401 .IR arg s
402 are required,
403 pass each with a separate
404 .B \-P
405 option.
406 .
407 .I groff
408 does not prefix an option dash to
409 .I arg
410 before passing it to the postprocessor.
411 .
412 .
413 .TP
414 .B \-R
415 Run
416 .MR \%refer 1
417 preprocessor.
418 .
419 No mechanism is provided for passing arguments to
420 .I \%refer
421 because most
422 .I \%refer
423 options have equivalent language elements that can be specified within
424 the document.
425 .
426 .
427 .TP
428 .B \-s
429 Run
430 .MR \%soelim 1
431 preprocessor.
432 .
433 .
434 .TP
435 .B \-S
436 Operate in \[lq]safer\[rq] mode;
437 see
438 .B \-U
439 below for its opposite.
440 .
441 For security reasons,
442 safer mode is enabled by default.
443 .
444 .
445 .TP
446 .B \-t
447 Run
448 .MR \%tbl 1
449 preprocessor.
450 .
451 .
452 .TP
453 .BI \-T\~ dev
454 Direct
455 .I \%troff
456 to format the input for the output device
457 .IR dev .
458 .
459 .I groff
460 then calls an output driver to convert
461 .IR \%troff 's
462 output to a form appropriate for
463 .IR dev ;
464 see subsection \[lq]Output devices\[rq] below.
465 .
466 .
467 .TP
468 .B \-U
469 Operate in unsafe mode:
470 pass the
471 .B \-U
472 option to
473 .I \%pic
474 and
475 .IR \%troff .
476 .
477 .
478 .TP
479 .B \-v
480 .TQ
481 .B \-\-version
482 Write version information for
483 .I groff
484 and all programs run by it to the standard output stream;
485 that is,
486 the given command line is processed in the usual way,
487 passing
488 .B \-v
489 to the formatter and any pre- or postprocessors invoked.
490 .
491 .
492 .TP
493 .B \-V
494 Output the pipeline that
495 .I groff
496 would run to the standard output stream,
497 but do not execute it.
498 .
499 If given more than once,
500 .I groff
501 both writes and runs the pipeline.
502 .
503 .
504 .TP
505 .B \-X
506 Use
507 .MR gxditview 1
508 instead of the usual postprocessor to (pre)view a document on an X11
509 display.
510 .
511 Combining this option with
512 .B \-Tps
513 uses the font metrics of the PostScript device,
514 whereas the
515 .B \-TX75
516 and
517 .B \-TX100
518 options use the metrics of X11 fonts.
519 .
520 .
521 .TP
522 .B \-Z
523 Disable postprocessing.
524 .
525 .I \%troff
526 output will appear on the standard output stream
527 (unless suppressed with
528 .BR \-z );
529 see
530 .MR groff_out 5
531 for a description of this format.
532 .
533 .
534 .\" ====================================================================
535 .SS "Transparent options"
536 .\" ====================================================================
537 .
538 The following options are passed as-is to the formatter program
539 .MR \%troff 1
540 and described in more detail in its man page.
541 .
542 .
543 .TP
544 .B \-a
545 Generate a plain text approximation of the typeset output.
546 .
547 .
548 .TP
549 .B \-b
550 Write a backtrace to the standard error stream on each error or warning.
551 .
552 .
553 .TP
554 .B \-c
555 Start with color output disabled.
556 .
557 .
558 .TP
559 .B \-C
560 Enable AT&T
561 .I troff \" AT&T
562 compatibility mode;
563 implies
564 .BR \-c .
565 .
566 .
567 .TP
568 .BI \-d\~ cs
569 .TQ
570 .BI \-d\~ name = string
571 Define string.
572 .
573 .
574 .TP
575 .B \-E
576 Inhibit
577 .I \%troff
578 error messages;
579 implies
580 .BR \-Ww .
581 .
582 .
583 .TP
584 .BI \-f\~ fam
585 Set default font family.
586 .
587 .
588 .TP
589 .BI \-F\~ dir
590 Search in directory
591 .I dir
592 for the selected output device's directory of device and font
593 description files.
594 .
595 .
596 .TP
597 .B \-i
598 Process standard input after the specified input files.
599 .
600 .
601 .TP
602 .BI \-I\~ dir
603 Search
604 .I dir
605 for input files.
606 .
607 .
608 .TP
609 .BI \-m\~ name
610 Process
611 .RI name .tmac
612 before input files.
613 .
614 .
615 .TP
616 .BI \-M\~ dir
617 Search directory
618 .I dir
619 for macro files.
620 .
621 .
622 .TP
623 .BI \-n\~ num
624 Number the first page
625 .IR num .
626 .
627 .
628 .TP
629 .BI \-o\~ list
630 Output only pages in
631 .IR list .
632 .
633 .
634 .TP
635 .BI \-r\~ cnumeric-expression
636 .TQ
637 .BI \-r\~ register = numeric-expression
638 Define register.
639 .
640 .
641 .TP
642 .BI \-w\~ name
643 .TQ
644 .BI \-W\~ name
645 Enable
646 .RB ( \-w )
647 or inhibit
648 .RB ( \-W )
649 emission of warnings in category
650 .IR name .
651 .
652 .
653 .TP
654 .B \-z
655 Suppress formatted device-independent output of
656 .IR \%troff .
657 .
658 .
659 .\" ====================================================================
660 .SH Usage
661 .\" ====================================================================
662 .
663 The architecture of the GNU
664 .I roff
665 system
666 follows that of other device-independent
667 .I roff
668 implementations,
669 comprising preprocessors,
670 macro packages,
671 output drivers
672 (or \[lq]postprocessors\[rq]),
673 a suite of utilities,
674 and the formatter
675 .I \%troff
676 at its heart.
677 .
678 See
679 .MR roff 7
680 for a survey of how a
681 .I roff
682 system works.
683 .
684 .
685 .P
686 The front end programs available in the GNU
687 .I roff
688 system make it easier to use than traditional
689 .IR roff s
690 that required the construction of pipelines or use of temporary files to
691 carry a source document from maintainable form to device-ready output.
692 .
693 The discussion below summarizes the constituent parts of the GNU
694 .I roff
695 system.
696 .
697 It complements
698 .MR roff 7
699 with
700 .IR groff -specific
701 information.
702 .
703 .
704 .\" ====================================================================
705 .SS "Getting started"
706 .\" ====================================================================
707 .
708 Those who prefer to learn by experimenting or are desirous of rapid
709 feedback from the system may wish to start with a \[lq]Hello,
710 world!\&\[rq] document.
711 .
712 .
713 .P
714 .EX
715 $ \c
716 .B echo \[dq]Hello, world!\[dq] | groff \-Tascii \
717 | sed \[aq]/\[ha]$/d\[aq]
718 Hello, world!
719 .EE
720 .
721 .
722 .P
723 We used a
724 .I sed
725 command only to eliminate the 65 blank lines that would otherwise flood
726 the terminal screen.
727 .
728 .RI ( roff
729 systems were developed in the days of paper-based terminals with 66
730 lines to a page.)
731 .
732 .
733 .P
734 Today's users may prefer output to a UTF-8-capable terminal.
735 .
736 .
737 .P
738 .EX
739 $ \c
740 .B echo \[dq]Hello, world!\[dq] | groff \-Tutf8 \
741 | sed \[aq]/\[ha]$/d\[aq]
742 .EE
743 .
744 .
745 .P
746 Producing PDF,
747 HTML,
748 or \*[TeX]'s DVI is also straightforward.
749 .
750 The hard part may be selecting a viewer program for the output.
751 .
752 .
753 .P
754 .EX
755 $ \c
756 .B echo \[dq]Hello, world!\[dq] | groff \-Tpdf > hello.pdf
757 $ \c
758 .B evince hello.pdf
759 $ \c
760 .B echo \[dq]Hello, world!\[dq] | groff \-Thtml > hello.html
761 $ \c
762 .B firefox hello.html
763 $ \c
764 .B echo \[dq]Hello, world!\[dq] | groff \-Tdvi > hello.dvi
765 $ \c
766 .B xdvi hello.html
767 .EE
768 .
769 .
770 .\" ====================================================================
771 .SS "Using \f[I]groff\f[] as a REPL"
772 .\" ====================================================================
773 .
774 Those with a programmer's bent may be pleased to know that they can use
775 .I groff
776 in a read-evaluate-print loop (REPL).
777 .
778 Doing so can be handy to verify one's understanding of the formatter's
779 behavior and/or the syntax it accepts.
780 .
781 Turning on all warnings with
782 .B \-ww
783 can aid this goal.
784 .
785 .
786 .P
787 .EX
788 $ \c
789 .B groff \-ww \-Tutf8
790 .B \[rs]# This is a comment. Let\[aq]s define a register.
791 .B .nr a 1
792 .B \[rs]# Do integer arithmetic with operators evaluated left-to-right.
793 .B .nr b \[rs]n[a]+5/2
794 .ne 2v
795 .B \[rs]# Let\[aq]s get the result on the standard error stream.
796 .B .tm \[rs]n[b]
797 3
798 .B \[rs]# Now we\[aq]ll define a string.
799 .B .ds name Leslie\[rs]" This is another form of comment.
800 .B .nr b (\[rs]n[a] + (7/2))
801 .B \[rs]# Center the next two text input lines.
802 .B .ce 2
803 .B Hi, \[rs]*[name].
804 .B Your secret number is \[rs]n[b].
805 .B \[rs]# We will see that the division rounded toward zero.
806 .B It is
807 .B \[rs]# Here\[aq]s an if-else control structure.
808 .B .ie (\[rs]n[b] % 2) odd.
809 .B .el even.
810 .B \[rs]# This trick sets the page length to the current vertical
811 .B \[rs]# position, so that blank lines don\[aq]t spew when we\[aq]re \
812 done.
813 .B .pl \[rs]n[nl]u
814 .I <Control-D>
815 Hi, Leslie.
816 Your secret number is 4.
817 It is even.
818 .EE
819 .
820 .
821 .\" ====================================================================
822 .SS "Paper format"
823 .\" ====================================================================
824 .
825 In GNU
826 .IR roff ,
827 the page dimensions for the formatter
828 .I \%troff
829 and for output devices are handled separately.
830 .
831 In the formatter,
832 requests are used to set the page length
833 .RB ( .pl ),
834 page offset
835 (or left margin,
836 .BR .po ),
837 and line length
838 .RB ( .ll ).
839 .
840 The right margin is not explicitly configured;
841 the combination of page offset and line length provides the information
842 necessary to derive it.
843 .
844 The
845 .I papersize
846 macro package,
847 automatically loaded by
848 .IR \%troff ,
849 provides an interface for configuring page dimensions by convenient
850 names,
851 like \[lq]letter\[rq] or
852 \[lq]A4\[rq];
853 see
854 .MR groff_tmac 5 .
855 .
856 The formatter's default in this installation is
857 .RB \[lq] \%A4 \[rq].
858 .
859 .
860 .P
861 It is up to each macro package to respect the page dimensions configured
862 in this way.
863 .
864 Some offer alternative mechanisms.
865 .
866 .
867 .P
868 For each output device,
869 the size of the output medium can be set in its
870 .I DESC
871 file.
872 .
873 Most output drivers also recognize a command-line option
874 .B \-p
875 to override the default dimensions and an option
876 .B \-l
877 to use landscape orientation.
878 .
879 See
880 .MR groff_font 5
881 for a description of the
882 .B papersize
883 directive,
884 which takes an argument of the same form as
885 .BR \-p .
886 .
887 The output driver's man page,
888 such as
889 .MR grops 1 ,
890 may also be helpful.
891 .
892 .I groff
893 uses the command-line option
894 .B \-P
895 to pass options to output devices;
896 for example,
897 use the following for PostScript output on A4 paper in landscape
898 orientation.
899 .
900 .
901 .IP
902 .EX
903 groff \-Tps \-dpaper=a4l \-P\-pa4 \-P\-l \-ms foo.ms > foo.ps
904 .EE
905 .
906 .
907 .\" ====================================================================
908 .SS "Front end"
909 .\" ====================================================================
910 .
911 The
912 .I groff
913 program is a wrapper around the
914 .MR \%troff 1
915 program.
916 .
917 It allows one to specify preprocessors via command-line options and
918 automatically runs the appropriate postprocessor for the selected
919 output device.
920 .
921 Doing so,
922 the manual construction of pipelines or management of temporary files
923 required of users of traditional
924 .MR roff 7
925 systems can be avoided.
926 .
927 Use the
928 .MR grog 1
929 program to infer an appropriate
930 .I groff
931 command line to format a document.
932 .
933 .
934 .\" ====================================================================
935 .SS Language
936 .\" ====================================================================
937 .
938 Input to a
939 .I roff
940 system is in plain text interleaved with control lines and escape
941 sequences.
942 .
943 The combination constitutes a document in one of a family of languages
944 we also call
945 .IR roff ;
946 see
947 .MR roff 7
948 for background.
949 .
950 An overview of GNU
951 .I roff
952 language syntax and features,
953 including lists of all supported escape sequences,
954 requests,
955 and predefined registers,
956 can be found in
957 .MR groff 7 .
958 .
959 GNU
960 .I roff
961 extensions to the AT&T
962 .I troff
963 language,
964 a common subset of
965 .I roff
966 dialects extant today,
967 are detailed in
968 .MR groff_diff 7 .
969 .
970 .
971 .\" ====================================================================
972 .SS Preprocessors
973 .\" ====================================================================
974 .
975 A preprocessor interprets a domain-specific language that produces
976 .I roff
977 language output.
978 .
979 Frequently,
980 such input is confined to sections or regions of a
981 .I roff
982 input file
983 (bracketed with macro calls specific to each preprocessor),
984 which it replaces.
985 .
986 Preprocessors therefore often interpret a subset of
987 .I roff
988 syntax along with their own language.
989 .
990 GNU
991 .I roff
992 provides reimplementations of most preprocessors familiar to users of
993 AT&T
994 .IR troff ; \" AT&T
995 these routinely have extended features and/or require GNU
996 .I troff \" GNU
997 to format their output.
998 .
999 .
1000 .br
1001 .ne 10v
1002 .P
1003 .RS
1004 .TS
1005 tab($);
1006 Li Lx.
1007 \%tbl$lays out tables;
1008 \%eqn$typesets mathematics;
1009 \%pic$draws diagrams;
1010 \%refer$processes bibliographic references;
1011 \%soelim$preprocesses \[lq]sourced\[rq] input files;
1012 \%grn$T{
1013 renders
1014 .MR gremlin 1
1015 diagrams;
1016 T}
1017 \%chem$T{
1018 draws chemical structural formul\[ae]
1019 using
1020 .IR pic ; \" generic
1021 T}
1022 gperl$T{
1023 populates
1024 .I groff
1025 registers and strings using
1026 .MR perl 1 ;
1027 T}
1028 glilypond$T{
1029 embeds
1030 .I LilyPond
1031 sheet music;
1032 and
1033 T}
1034 gpinyin$T{
1035 eases Mandarin Chinese input using Hanyu Pinyin.
1036 T}
1037 .TE
1038 .RE
1039 .
1040 .
1041 .P
1042 A preprocessor unique to GNU
1043 .I roff
1044 is
1045 .MR preconv 1 ,
1046 which converts various input encodings to something GNU
1047 .I troff \" GNU
1048 can understand.
1049 .
1050 When used,
1051 it is run before any other preprocessors.
1052 .
1053 .
1054 .P
1055 Most preprocessors enclose content between a pair of characteristic
1056 tokens.
1057 .
1058 Such a token must occur at the beginning of an input line and use the
1059 dot control character.
1060 .
1061 Spaces and tabs must not follow the control character or precede the
1062 end of the input line.
1063 .
1064 Deviating from these rules defeats a token's recognition by the
1065 preprocessor.
1066 .
1067 Tokens are generally preserved in preprocessor output and interpreted as
1068 macro calls subsequently by
1069 .IR \%troff .
1070 .
1071 The
1072 .I \%ideal
1073 preprocessor is not yet available in
1074 .IR groff .
1075 .
1076 .
1077 .P
1078 .TS
1079 box, center, tab (^);
1080 c | c | c
1081 CfCR | CfCR | CfCR.
1082 preprocessor^starting token^ending token
1083 =
1084 \%chem^.cstart^.cend
1085 \%eqn^.EQ^.EN
1086 grap^.G1^.G2
1087 \%grn^.GS^.GE
1088 .\" Keep the .IF line below the \%ideal line.
1089 \%ideal^.IS^.IE
1090 ^^.IF
1091 .\" Keep the .PF line below the \%pic line.
1092 \%pic^.PS^.PE
1093 ^^.PF
1094 ^^.PY
1095 \%refer^.R1^.R2
1096 \%tbl^.TS^.TE
1097 _
1098 glilypond^.lilypond start^.lilypond stop
1099 gperl^.Perl start^.Perl stop
1100 gpinyin^.pinyin start^.pinyin stop
1101 .TE
1102 .
1103 .
1104 .\" ====================================================================
1105 .SS "Macro packages"
1106 .\" ====================================================================
1107 .
1108 Macro files are
1109 .I roff
1110 input files designed to produce no output themselves but instead ease
1111 the preparation of other
1112 .I roff
1113 documents.
1114 .
1115 When a macro file is installed at a standard location and suitable for
1116 use by a general audience,
1117 it is termed a
1118 .IR "macro package" .
1119 .
1120 .
1121 .P
1122 Macro packages can be loaded prior to any
1123 .I roff
1124 input documents with the
1125 .BR \-m \~option.
1126 .
1127 The GNU
1128 .I roff
1129 system implements most well-known macro packages for AT&T
1130 .I troff \" AT&T
1131 .\" exceptions: mpm, mv
1132 in a compatible way and extends them.
1133 .
1134 These have one- or two-letter names arising from intense practices of
1135 naming economy in early Unix culture,
1136 a laconic approach that led to many of the packages being identified in
1137 general usage with the
1138 .I nroff
1139 and
1140 .I troff
1141 option letter used to invoke them,
1142 sometimes to punning effect,
1143 as with \[lq]man\[rq]
1144 (short for \[lq]manual\[rq]),
1145 and even with the option dash,
1146 as in the case of the
1147 .I s
1148 package,
1149 much better known as
1150 .I ms
1151 or even
1152 .IR \-ms .
1153 .
1154 .
1155 .P
1156 Macro packages serve a variety of purposes.
1157 .
1158 Some are \[lq]full-service\[rq] packages,
1159 adopting responsibility for page layout among other fundamental tasks,
1160 and defining their own lexicon of macros for document composition;
1161 each such package stands alone and a given document can use at most one.
1162 .
1163 .
1164 .TP
1165 .I an
1166 is used to compose man pages in the format originating in Version\~7
1167 Unix (1979);
1168 see
1169 .MR groff_man 7 .
1170 .
1171 It can be specified on the command line as
1172 .BR \-man .
1173 .
1174 .
1175 .TP
1176 .I doc
1177 is used to compose man pages in the format originating in 4.3BSD-Reno
1178 (1990);
1179 see
1180 .MR groff_mdoc 7 .
1181 .
1182 It can be specified on the command line as
1183 .BR \-mdoc .
1184 .
1185 .
1186 .TP
1187 .I e
1188 is the Berkeley general-purpose macro suite,
1189 developed as an alternative to AT&T's
1190 .IR s ;
1191 see
1192 .MR groff_me 7 .
1193 .
1194 It can be specified on the command line as
1195 .BR \-me .
1196 .
1197 .
1198 .TP
1199 .I m
1200 implements the format used by the
1201 second-generation AT&T macro suite for general documents,
1202 a successor to
1203 .IR s ;
1204 see
1205 .MR groff_mm 7 .
1206 .
1207 It can be specified on the command line as
1208 .BR \-mm .
1209 .
1210 .
1211 .TP
1212 .I om
1213 (invariably called \[lq]mom\[rq])
1214 is a modern package written by Peter Schaffter specifically for GNU
1215 .IR roff .
1216 .
1217 Consult the
1218 .UR file://\:/usr/\:\%share/\:\%doc/\:\%groff\-base/\:\%html/\:mom/\:toc\:.html
1219 .I mom
1220 HTML manual
1221 .UE
1222 for extensive documentation.
1223 .
1224 She\[em]for
1225 .I mom
1226 takes the female pronoun\[em]can be specified on the command line as
1227 .BR \-mom .
1228 .
1229 .
1230 .TP
1231 .I s
1232 is the original AT&T general-purpose document format;
1233 see
1234 .MR groff_ms 7 .
1235 .
1236 It can be specified on the command line as
1237 .BR \-ms .
1238 .
1239 .
1240 .P
1241 Others are supplemental.
1242 .
1243 For instance,
1244 .
1245 .I \%andoc
1246 is a wrapper package specific to GNU
1247 .I roff
1248 that recognizes whether a document uses
1249 .I man
1250 or
1251 .I mdoc
1252 format and loads the corresponding macro package.
1253 .
1254 It can be specified on the command line as
1255 .BR \%\-mandoc .
1256 .
1257 A
1258 .MR man 1
1259 librarian program \" such as man-db, since 2001
1260 may use this macro file to delegate loading of the correct macro
1261 package;
1262 it is thus unnecessary for
1263 .I man
1264 itself to scan the contents of a document to decide the issue.
1265 .
1266 .
1267 .P
1268 Many macro files augment the function of the full-service packages,
1269 or of
1270 .I roff
1271 documents that do not employ such a package\[em]the latter are sometimes
1272 characterized as \[lq]raw\[rq].
1273 .
1274 These auxiliary packages are described,
1275 along with
1276 details of macro file naming and placement,
1277 in
1278 .MR groff_tmac 5 .
1279 .
1280 .
1281 .\" ====================================================================
1282 .SS Formatters
1283 .\" ====================================================================
1284 .
1285 The formatter,
1286 the program that interprets
1287 .I roff
1288 language input,
1289 is
1290 .MR \%troff 1 .
1291 .
1292 It provides the features of the AT&T
1293 .I troff \" AT&T
1294 and
1295 .I nroff \" AT&T
1296 programs as well as many extensions.
1297 .
1298 The command-line option
1299 .B \-C
1300 switches
1301 .I \%troff
1302 into
1303 .IR "compatibility mode" ,
1304 which tries to emulate AT&T
1305 .I troff \" AT&T
1306 as closely as is practical to enable the formatting of documents written
1307 for the older system.
1308 .
1309 .
1310 .P
1311 A shell script,
1312 .MR \%nroff 1 ,
1313 emulates the behavior of AT&T
1314 .IR nroff . \" AT&T
1315 .
1316 It attempts to correctly encode the output based on the locale,
1317 relieving the user of the need to specify an output device with the
1318 .B \-T
1319 option and is therefore convenient for use with terminal output devices,
1320 described in the next subsection.
1321 .
1322 .
1323 .P
1324 GNU
1325 .I troff \" GNU
1326 generates output in a device-independent,
1327 but not device-agnostic,
1328 page description language detailed in
1329 .MR groff_out 5 .
1330 .
1331 .
1332 .\" ====================================================================
1333 .SS "Output devices"
1334 .\" ====================================================================
1335 .
1336 .I \%troff
1337 output is formatted for a particular
1338 .IR "output device" ,
1339 typically specified by the
1340 .B \-T
1341 option to the formatter or a front end.
1342 .
1343 If neither this option nor the
1344 .I \%GROFF_TYPESETTER
1345 environment variable is used,
1346 the default output device is
1347 .BR \%ps .
1348 .
1349 An output device may be any of the following.
1350 .
1351 .
1352 .TP 9n \" to fit "X100\-12" even on troff devices
1353 .B ascii
1354 for terminals using the ISO 646 1991:IRV character set and encoding,
1355 also known as US-ASCII.
1356 .
1357 .
1358 .TP
1359 .B cp1047
1360 for terminals using the IBM code page 1047 character set and encoding.
1361 .
1362 .
1363 .TP
1364 .B dvi
1365 for TeX DVI format.
1366 .
1367 .
1368 .TP
1369 .B html
1370 .TQ
1371 .B xhtml
1372 for HTML and XHTML output,
1373 respectively.
1374 .
1375 .
1376 .TP
1377 .B latin1
1378 for terminals using the ISO Latin-1
1379 (ISO 8859-1)
1380 character set and encoding.
1381 .
1382 .
1383 .TP
1384 .B lbp
1385 for Canon CaPSL printers
1386 (LBP-4 and LBP-8 series laser printers).
1387 .
1388 .
1389 .TP
1390 .B lj4
1391 for HP LaserJet4-compatible
1392 (or other PCL5-compatible)
1393 printers.
1394 .
1395 .
1396 .TP
1397 .B pdf
1398 for PDF output.
1399 .
1400 .
1401 .TP
1402 .B ps
1403 for PostScript output.
1404 .
1405 .
1406 .TP
1407 .B utf8
1408 for terminals using the ISO 10646 (\[lq]Unicode\[rq]) character set in
1409 UTF-8 encoding.
1410 .
1411 .
1412 .TP
1413 .B X75
1414 for previewing with
1415 .I \%gxditview
1416 using
1417 75 dpi resolution and a
1418 10-point base type size.
1419 .
1420 .
1421 .TP
1422 .B X75\-12
1423 for previewing with
1424 .I \%gxditview
1425 using
1426 75 dpi resolution and a
1427 12-point base type size.
1428 .
1429 .
1430 .TP
1431 .B X100
1432 for previewing with
1433 .I \%gxditview
1434 using
1435 100 dpi resolution and a
1436 10-point base type size.
1437 .
1438 .
1439 .TP
1440 .B X100\-12
1441 for previewing with
1442 .I \%gxditview
1443 using
1444 100 dpi resolution
1445 and a
1446 12-point base type size.
1447 .
1448 .
1449 .\" ====================================================================
1450 .SS Postprocessors
1451 .\" ====================================================================
1452 .
1453 Any program that interprets the output of
1454 GNU
1455 .I troff \" GNU
1456 is a
1457 postprocessor.
1458 .
1459 The postprocessors provided by GNU
1460 .I roff
1461 are
1462 .IR "output drivers" ,
1463 which prepare a document for viewing or printing.
1464 .
1465 Postprocessors for other purposes,
1466 such as page resequencing or statistical measurement of a document,
1467 are conceivable.
1468 .
1469 .
1470 .P
1471 An output driver supports one or more output devices,
1472 each with its own device description file.
1473 .
1474 A device determines its postprocessor with the
1475 .B postpro
1476 directive in its device description file;
1477 see
1478 .MR groff_font 5 .
1479 .
1480 The
1481 .B \-X
1482 option overrides this selection,
1483 causing
1484 .I \%gxditview
1485 to serve as the output driver.
1486 .
1487 .
1488 .TP
1489 .MR grodvi 1
1490 provides
1491 .BR dvi .
1492 .
1493 .
1494 .TP
1495 .MR grohtml 1
1496 provides
1497 .B html
1498 and
1499 .BR xhtml .
1500 .
1501 .
1502 .TP
1503 .MR grolbp 1
1504 provides
1505 .BR lbp .
1506 .
1507 .
1508 .TP
1509 .MR grolj4 1
1510 provides
1511 .BR lj4 .
1512 .
1513 .
1514 .TP
1515 .MR gropdf 1
1516 provides
1517 .BR pdf .
1518 .
1519 .
1520 .TP
1521 .MR grops 1
1522 provides
1523 .BR ps .
1524 .
1525 .
1526 .TP
1527 .MR grotty 1
1528 provides
1529 .BR ascii ,
1530 .BR cp1047 ,
1531 .BR latin1 ,
1532 and
1533 .BR utf8 .
1534 .
1535 .
1536 .TP
1537 .MR gxditview 1
1538 provides
1539 .BR X75 ,
1540 .BR X75\-12 ,
1541 .BR X100 ,
1542 and
1543 .BR X100\-12 ,
1544 and additionally can preview
1545 .BR ps .
1546 .
1547 .
1548 .\" ====================================================================
1549 .SS Utilities
1550 .\" ====================================================================
1551 .
1552 GNU
1553 .I roff
1554 includes a suite of utilities.
1555 .
1556 .
1557 .TP
1558 .MR gdiffmk 1
1559 marks differences between a pair of
1560 .I roff
1561 input files.
1562 .
1563 .
1564 .TP
1565 .MR grog 1
1566 infers the
1567 .I groff
1568 command a document requires.
1569 .
1570 .
1571 .P
1572 Several utilities prepare descriptions of fonts,
1573 enabling the formatter to use them when producing output for a given
1574 device.
1575 .
1576 .
1577 .TP
1578 .MR addftinfo 1
1579 adds information to AT&T
1580 .I troff \" AT&T
1581 font description files to enable their use with
1582 GNU
1583 .IR troff .\" GNU
1584 .
1585 .
1586 .TP
1587 .MR afmtodit 1
1588 creates font description files for PostScript Type\~1 fonts.
1589 .
1590 .
1591 .TP
1592 .MR pfbtops 1
1593 translates a PostScript Type\~1 font in PFB
1594 (Printer Font Binary)
1595 format to PFA
1596 (Printer Font ASCII),
1597 which can then be interpreted by
1598 .IR \%afmtodit .
1599 .
1600 .
1601 .TP
1602 .MR hpftodit 1
1603 creates font description files for the HP LaserJet\~4 family of
1604 printers.
1605 .
1606 .
1607 .TP
1608 .MR tfmtodit 1
1609 creates font description files for the TeX DVI device.
1610 .
1611 .
1612 .TP
1613 .MR xtotroff 1
1614 creates font description files for X Window System core fonts.
1615 .
1616 .
1617 .P
1618 A trio of tools transform material constructed using
1619 .I roff
1620 preprocessor languages into graphical image files.
1621 .
1622 .
1623 .TP
1624 .MR eqn2graph 1
1625 converts an
1626 .I eqn
1627 equation into a cropped image.
1628 .
1629 .
1630 .TP
1631 .MR grap2graph 1
1632 converts a
1633 .I grap
1634 diagram into a cropped image.
1635 .
1636 .
1637 .TP
1638 .MR pic2graph 1
1639 converts a
1640 .I pic
1641 diagram into a cropped image.
1642 .
1643 .
1644 .P
1645 Another set of programs works with the bibliographic data files used
1646 by the
1647 .MR refer 1
1648 preprocessor.
1649 .
1650 .
1651 .TP
1652 .MR \%indxbib 1
1653 makes inverted indices for bibliographic databases,
1654 speeding lookup operations on them.
1655 .
1656 .
1657 .TP
1658 .MR lkbib 1
1659 searches the databases.
1660 .
1661 .
1662 .TP
1663 .MR \%lookbib 1
1664 interactively searches
1665 the databases.
1666 .
1667 .
1668 .\" ====================================================================
1669 .SH "Exit status"
1670 .\" ====================================================================
1671 .
1672 .I groff
1673 exits with a failure status if there was a problem parsing its arguments
1674 and a successful status if either of the options
1675 .B \-h
1676 or
1677 .B \-\-help
1678 was specified.
1679 .
1680 Otherwise,
1681 .I groff
1682 runs a pipeline to process its input;
1683 if all commands within the pipeline exit successfully,
1684 .I groff
1685 does likewise.
1686 .
1687 If not,
1688 .IR groff 's
1689 exit status encodes a summary of problems encountered,
1690 setting bit\~0 if a command exited with a failure status,
1691 bit\~1 if a command was terminated with a signal,
1692 and bit\~2 if a command could not be executed.
1693 .
1694 (Thus,
1695 if all three misfortunes befell one's pipeline,
1696 .I groff
1697 would exit with status 2\[ha]0 + 2\[ha]1 + 2\[ha]2 = 1+2+4 = 7.)
1698 .
1699 To troubleshoot pipeline problems,
1700 you may wish to re-run the
1701 .I groff
1702 command with the
1703 .B \-V
1704 option and break the reported pipeline down into separate stages,
1705 inspecting the exit status of and diagnostic messages emitted by each
1706 command.
1707 .
1708 .
1709 .\" ====================================================================
1710 .SH Environment
1711 .\" ====================================================================
1712 .
1713 Normally,
1714 the path separator in environment variables ending with
1715 .I PATH
1716 is the colon;
1717 this may vary depending on the operating system.
1718 .
1719 For example,
1720 Windows uses a semicolon instead.
1721 .
1722 .
1723 .TP
1724 .I GROFF_BIN_PATH
1725 This search path,
1726 followed by
1727 .IR PATH ,
1728 is used to locate commands executed by
1729 .IR groff .
1730 .
1731 If it is not set,
1732 the installation directory of the GNU
1733 .I roff
1734 executables,
1735 .IR /usr/\:\%bin ,
1736 is searched before
1737 .IR PATH .
1738 .
1739 .
1740 .TP
1741 .I GROFF_COMMAND_PREFIX
1742 GNU
1743 .I roff
1744 can be configured at compile time to apply a prefix to the names of the
1745 programs it provides that had a counterpart in AT&T
1746 .IR troff , \" AT&T
1747 so that name collisions are avoided at run time.
1748 .
1749 The default prefix is empty.
1750 .
1751 .
1752 .IP
1753 When used,
1754 this prefix is conventionally the letter \[lq]g\[rq].
1755 .
1756 For example,
1757 GNU
1758 .I troff \" GNU
1759 would be installed as
1760 .IR gtroff .
1761 .
1762 Besides
1763 .IR troff , \" GNU
1764 the prefix applies to
1765 the formatter
1766 .IR nroff ; \" GNU
1767 the preprocessors
1768 .IR eqn , \" generic
1769 .IR grn , \" generic
1770 .IR pic , \" generic
1771 .IR \%refer , \" generic
1772 .IR tbl , \" generic
1773 and
1774 .IR \%soelim ; \" generic
1775 and the utilities
1776 .I \%indxbib \" generic
1777 and
1778 .IR \%lookbib . \" generic
1779 .
1780 .
1781 .TP
1782 .I GROFF_ENCODING
1783 The value of this variable is passed to the
1784 .IR preconv (1)
1785 preprocessor's
1786 .B \-e
1787 option to select the character encoding of input files.
1788 .
1789 This variable's existence implies
1790 the
1791 .I groff
1792 option
1793 .BR \-k .
1794 .
1795 If set but empty,
1796 .I groff
1797 calls
1798 .I preconv
1799 without an
1800 .B \-e
1801 option.
1802 .
1803 .IR groff 's
1804 .B \-K
1805 option overrides
1806 .IR \%GROFF_ENCODING .
1807 .
1808 .
1809 .TP
1810 .I GROFF_FONT_PATH
1811 Seek the selected output device's directory of device and font
1812 description files in this list of directories.
1813 .
1814 See
1815 .MR \%troff 1
1816 and
1817 .MR groff_font 5 .
1818 .
1819 .
1820 .TP
1821 .I GROFF_TMAC_PATH
1822 Seek macro files in this list of directories.
1823 .
1824 See
1825 .MR \%troff 1
1826 and
1827 .MR groff_tmac 5 .
1828 .
1829 .
1830 .TP
1831 .I GROFF_TMPDIR
1832 Create temporary files in this directory.
1833 .
1834 If not set,
1835 but the environment variable
1836 .I \%TMPDIR
1837 is set,
1838 temporary files are created there instead.
1839 .
1840 On Windows systems,
1841 if neither of the foregoing are set,
1842 the environment variables
1843 .I TMP
1844 and
1845 .I TEMP
1846 (in that order)
1847 are checked also.
1848 .
1849 Otherwise,
1850 temporary files are created in
1851 .IR /tmp .
1852 .
1853 The
1854 .MR \%refer 1 ,
1855 .MR grohtml 1 ,
1856 and
1857 .MR grops 1
1858 commands use temporary files.
1859 .
1860 .
1861 .TP
1862 .I GROFF_TYPESETTER
1863 Set the default output device.
1864 .
1865 If empty or not set,
1866 .B \%ps
1867 is used.
1868 .
1869 The
1870 .B \-T
1871 option overrides
1872 .IR \%GROFF_TYPESETTER .
1873 .
1874 .
1875 .TP
1876 .I SOURCE_DATE_EPOCH
1877 A time stamp
1878 (expressed as seconds since the Unix epoch)
1879 to use as the output creation time stamp in place of the current time.
1880 .
1881 The time is converted to human-readable form using
1882 .MR gmtime 3
1883 and
1884 .MR asctime 3
1885 when the formatter starts up and stored in registers usable by documents
1886 and macro packages.
1887 .
1888 .
1889 .TP
1890 .I TZ
1891 The time zone to use when converting the current time to human-readable form;
1892 see
1893 .MR tzset 3 .
1894 If
1895 .I SOURCE_DATE_EPOCH
1896 is used, it is always converted to human-readable form using UTC.
1897 .
1898 .
1899 .\" ====================================================================
1900 .SH Examples
1901 .\" ====================================================================
1902 .
1903 .I roff
1904 systems are best known for formatting man pages.
1905 .
1906 Once a
1907 .MR man 1
1908 librarian program has located a man page,
1909 it may execute a
1910 .I groff
1911 command much like the following.
1912 .
1913 .RS
1914 .EX
1915 groff \-t \-man \-Tutf8 /usr/share/man/man1/groff.1
1916 .EE
1917 .RE
1918 .
1919 The librarian will also pipe the output through a pager,
1920 which might not interpret the SGR terminal escape sequences
1921 .I groff
1922 emits for boldface,
1923 underlining,
1924 or italics;
1925 see section \[lq]Limitations\[rq] below.
1926 .
1927 .
1928 .P
1929 To process a
1930 .I roff
1931 input file using the preprocessors
1932 .I \%tbl
1933 and
1934 .I \%pic
1935 and the
1936 .I me
1937 macro package in the way to which AT&T
1938 .I troff \" AT&T
1939 users were accustomed,
1940 one would type
1941 (or script)
1942 a pipeline.
1943 .
1944 .
1945 .IP
1946 .EX
1947 \%pic foo.me | \%tbl | \%troff \-me \-Tutf8 | grotty
1948 .EE
1949 .
1950 .
1951 .P
1952 Using
1953 .IR groff ,
1954 this pipe can be shortened to an equivalent command.
1955 .
1956 .IP
1957 .EX
1958 groff \-p \-t \-me \-T utf8 foo.me
1959 .EE
1960 .
1961 .
1962 .P
1963 An even easier way to do this is to use
1964 .MR grog 1
1965 to guess the preprocessor and macro options and execute the result by
1966 using the command substitution feature of the shell.
1967 .
1968 .IP
1969 .EX
1970 $(grog \-Tutf8 foo.me)
1971 .EE
1972 .
1973 .
1974 .P
1975 Each command-line option to a postprocessor must be specified with any
1976 required leading dashes
1977 .RB \[lq] \- \[rq]
1978 .\" No GNU roff postprocessor uses long options for anything except
1979 .\" --help or --version.
1980 .\"or
1981 .\".RB \[lq] \-\- \[rq]
1982 because
1983 .I groff
1984 passes the arguments as-is to the postprocessor;
1985 this permits arbitrary arguments to be transmitted.
1986 .
1987 For example,
1988 to pass a title to the
1989 .I gxditview
1990 postprocessor,
1991 the shell commands
1992 .
1993 .RS
1994 .EX
1995 groff \-X \-P \-title \-P \[aq]trial run\[aq] mydoc.t
1996 .EE
1997 .RE
1998 .
1999 and
2000 .
2001 .RS
2002 .EX
2003 groff \-X \-Z mydoc.t | gxditview \-title \[aq]trial run\[aq] \-
2004 .EE
2005 .RE
2006 .
2007 are equivalent.
2008 .
2009 .
2010 .\" ====================================================================
2011 .SH Limitations
2012 .\" ====================================================================
2013 .
2014 When paging output for the
2015 .BR ascii ,
2016 .BR cp1047 ,
2017 .BR latin1 ,
2018 and
2019 .B utf8
2020 devices,
2021 programs like
2022 .MR more 1
2023 and
2024 .MR less 1
2025 may require command-line options to correctly handle some terminal
2026 escape sequences;
2027 see
2028 .MR grotty 1 .
2029 .
2030 .
2031 .P
2032 On EBCDIC hosts such as OS/390 Unix,
2033 the output devices
2034 .B ascii
2035 and
2036 .B latin1
2037 aren't available.
2038 .
2039 Conversely,
2040 the output device
2041 .B cp1047
2042 is not available on systems based on the ISO\~646 or ISO\~8859 character
2043 encoding standards.
2044 .
2045 .
2046 .\" ====================================================================
2047 .SH "Installation directories"
2048 .\" ====================================================================
2049 .
2050 GNU
2051 .I roff
2052 installs files in varying locations depending on its compile-time
2053 configuration.
2054 .
2055 On this installation,
2056 the following locations are used.
2057 .
2058 .
2059 .if !'/etc/\:\%X11/\:\%app\-defaults'' \{\
2060 .TP
2061 .I /etc/\:\%X11/\:\%app\-defaults
2062 Application defaults directory for
2063 .MR gxditview 1 .
2064 .\}
2065 .
2066 .
2067 .TP
2068 .I /usr/\:\%bin
2069 Directory containing
2070 .IR groff 's
2071 executable commands.
2072 .
2073 .
2074 .TP
2075 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%eign
2076 List of common words for
2077 .MR indxbib 1 .
2078 .
2079 .
2080 .TP
2081 .I /usr/\:\%share/\:\%groff/\:\%1.23.0
2082 Directory for data files.
2083 .
2084 .
2085 .TP
2086 .I /usr/\:\%dict/\:\%papers/\:\%Ind
2087 Default index for
2088 .MR lkbib 1
2089 and
2090 .MR refer 1 .
2091 .
2092 .
2093 .TP
2094 .I /usr/\:\%share/\:\%doc/\:\%groff\-base
2095 Documentation directory.
2096 .
2097 .
2098 .TP
2099 .I /usr/\:\%share/\:\%doc/\:\%groff\-base/\:\%examples
2100 Example directory.
2101 .
2102 .
2103 .TP
2104 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font
2105 Font directory.
2106 .
2107 .
2108 .TP
2109 .I /usr/\:\%share/\:\%doc/\:\%groff\-base/\:\%html
2110 HTML documentation directory.
2111 .
2112 .
2113 .TP
2114 .I /usr/\:\%lib/\:\%font
2115 Legacy font directory.
2116 .
2117 .
2118 .TP
2119 .I /usr/\:\%share/\:\%groff/\:\%site\-font
2120 Local font directory.
2121 .
2122 .
2123 .TP
2124 .I /usr/\:\%share/\:\%groff/\:\%site\-tmac
2125 Local macro package
2126 .RI ( tmac
2127 file) directory.
2128 .
2129 .
2130 .TP
2131 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac
2132 Macro package
2133 .RI ( tmac
2134 file) directory.
2135 .
2136 .
2137 .TP
2138 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%oldfont
2139 Font directory for compatibility with old versions of
2140 .IR groff ;
2141 see
2142 .MR grops 1 .
2143 .
2144 .
2145 .TP
2146 .I /usr/\:\%share/\:\%doc/\:\%groff\-base/\:\%pdf
2147 PDF documentation directory.
2148 .
2149 .
2150 .if !'no'no' \{\
2151 .TP
2152 .I /usr/\:\%lib/\:\%groff/\:\%site\-tmac
2153 System macro package
2154 .RI ( tmac
2155 file) directory.
2156 .\}
2157 .
2158 .
2159 .\" ====================================================================
2160 .SS "\f[I]groff\f[] macro directory"
2161 .\" ====================================================================
2162 .
2163 Most macro files supplied with GNU
2164 .I roff
2165 are stored in
2166 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac
2167 for the installation corresponding to this document.
2168 .
2169 As a rule,
2170 multiple directories are searched for macro files;
2171 see
2172 .MR \%troff 1 .
2173 .
2174 For a catalog of macro files GNU
2175 .I roff
2176 provides,
2177 see
2178 .MR groff_tmac 5 .
2179 .
2180 .
2181 .\" ====================================================================
2182 .SS "\f[I]groff\f[] device and font description directory"
2183 .\" ====================================================================
2184 .
2185 Device and font description files supplied with GNU
2186 .I roff
2187 are stored in
2188 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%font
2189 for the installation corresponding to this document.
2190 .
2191 As a rule,
2192 multiple directories are searched for device and font description files;
2193 see
2194 .MR \%troff 1 .
2195 .
2196 For the formats of these files,
2197 see
2198 .MR groff_font 5 .
2199 .
2200 .
2201 .\" ====================================================================
2202 .SH Availability
2203 .\" ====================================================================
2204 .
2205 Obtain links to
2206 .I groff
2207 releases for download,
2208 its source repository,
2209 discussion mailing lists,
2210 a support ticket tracker,
2211 and further information from the
2212 .UR http://\:www\:.gnu\:.org/\:software/\:groff
2213 .I groff
2214 page of the GNU website
2215 .UE .
2216 .
2217 .
2218 .P
2219 A free implementation of the
2220 .I grap
2221 preprocessor,
2222 written by
2223 .MT faber@\:lunabase\:.org
2224 Ted Faber
2225 .ME ,
2226 can be found at the
2227 .UR http://\:www\:.lunabase\:.org/\:\[ti]faber/\:Vault/\:software/\
2228 \:grap/
2229 .I grap
2230 website
2231 .UE .
2232 .
2233 .I groff
2234 supports only this
2235 .IR grap .
2236 .
2237 .
2238 .\" ====================================================================
2239 .SH Authors
2240 .\" ====================================================================
2241 .
2242 .I groff
2243 (both the front-end command and the overall system)
2244 was primarily written by
2245 .MT jjc@\:jclark\:.com
2246 James Clark
2247 .ME .
2248 .
2249 Contributors to this document include Clark,
2250 Trent A.\& Fisher,
2251 .MT [email protected]
2252 Werner Lemberg
2253 .ME ,
2254 .MT groff\-bernd.warken\-72@\:web\:.de
2255 Bernd Warken
2256 .ME ,
2257 and
2258 .MT g.branden\:.robinson@\:gmail\:.com
2259 G.\& Branden Robinson
2260 .ME .
2261 .
2262 .
2263 .\" ====================================================================
2264 .SH "See also"
2265 .\" ====================================================================
2266 .
2267 .IR "Groff: The GNU Implementation of troff" ,
2268 by Trent A.\& Fisher and Werner Lemberg,
2269 is the primary
2270 .I groff
2271 manual.
2272 .
2273 You can browse it interactively with \[lq]info groff\[rq].
2274 .
2275 .
2276 .\" groff ships 59 man pages generated from 58 source files. The
2277 .\" numbered comments refer to their sorting order in the source tree,
2278 .\" so that it is easier to tell that we've enumerated all of them.
2279 .TP
2280 Introduction, \c
2281 history, \c
2282 and further reading:
2283 .MR roff 7 \" #23
2284 .
2285 .
2286 .TP
2287 .RI "Viewer for\~" groff "\~(and AT&T device-independent\~" troff \
2288 )\~documents:
2289 .MR gxditview 1 \" #33
2290 .
2291 .
2292 .TP
2293 Preprocessors:
2294 .MR \%chem 1 , \" #1
2295 .MR \%eqn 1 , \" #34
2296 .MR \%neqn 1 , \" #35
2297 .MR glilypond 1 , \" #4
2298 .MR \%grn 1 , \" #36
2299 .MR preconv 1 , \" #38
2300 .MR gperl 1 , \" #5
2301 .MR \%pic 1 , \" #37
2302 .MR gpinyin 1 , \" #6
2303 .MR \%refer 1 , \" #39
2304 .MR \%soelim 1 , \" #40
2305 .MR \%tbl 1 \" #41
2306 .
2307 .
2308 .TP
2309 Macro packages and package-specific utilities:
2310 .MR groff_hdtbl 7 , \" #9
2311 .MR groff_man 7 , \" #55a
2312 .MR groff_man_style 7 , \" #55b
2313 .MR groff_mdoc 7 , \" #56
2314 .MR groff_me 7 , \" #57
2315 .MR groff_mm 7 , \" # 10
2316 .MR groff_mmse 7 \" # 11
2317 (only in Swedish locales),
2318 .MR mmroff 1 , \" #12
2319 .MR groff_mom 7 , \" #13
2320 .MR pdfmom 1 , \" #30
2321 .MR groff_ms 7 , \" #58
2322 .MR groff_rfc1345 7 , \" 16
2323 .MR groff_trace 7 , \" #59
2324 .MR groff_www 7 \" #60
2325 .
2326 .
2327 .TP
2328 Bibliographic database management tools:
2329 .MR \%indxbib 1 , \" #49
2330 .MR lkbib 1 , \" #50
2331 .MR \%lookbib 1 \" #51
2332 .
2333 .
2334 .TP
2335 Language, \c
2336 conventions, \c
2337 and GNU extensions:
2338 .MR groff 7 , \" #17
2339 .MR groff_char 7 , \" #18
2340 .MR groff_diff 7 , \" #19
2341 .MR groff_font 5 , \" #20
2342 .MR groff_tmac 5 \" #22
2343 .
2344 .
2345 .TP
2346 Intermediate output language:
2347 .MR groff_out 5 \" #21
2348 .
2349 .
2350 .TP
2351 Formatter program:
2352 .MR \%troff 1 \" #45
2353 .
2354 .
2355 .TP
2356 Formatter wrappers:
2357 .\".MR groff 1 , \" 42 -- this page
2358 .MR \%nroff 1 , \" #44
2359 .MR pdfroff 1 \" #14
2360 .
2361 .
2362 .TP
2363 Postprocessors for output devices:
2364 .MR grodvi 1 , \" #24
2365 .MR grohtml 1 , \" #25
2366 .MR grolbp 1 , \" #26
2367 .MR grolj4 1 , \" #27
2368 .MR gropdf 1 , \" #29
2369 .MR grops 1 , \" #31
2370 .MR grotty 1 \" #32
2371 .
2372 .
2373 .TP
2374 Font support utilities:
2375 .MR addftinfo 1 , \" #46
2376 .MR afmtodit 1 , \" #47
2377 .MR hpftodit 1 , \" #48
2378 .MR pfbtops 1 , \" #52
2379 .MR tfmtodit 1 , \" #53
2380 .MR xtotroff 1 \" #54
2381 .
2382 .
2383 .TP
2384 Graphics conversion utilities:
2385 .MR eqn2graph 1 , \" #2
2386 .MR grap2graph 1 , \" #7
2387 .MR pic2graph 1 \" #15
2388 .
2389 .
2390 .TP
2391 Difference-marking utility:
2392 .MR gdiffmk 1 \" #3
2393 .
2394 .
2395 .TP
2396 \[lq]groff guess\[rq] utility:
2397 .MR grog 1 \" #43
2398 .
2399 .
2400 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
2401 .cp \n[*groff_groff_1_man_C]
2402 .do rr *groff_groff_1_man_C
2403 .
2404 .
2405 .\" Local Variables:
2406 .\" fill-column: 72
2407 .\" mode: nroff
2408 .\" End:
2409 .\" vim: set filetype=groff textwidth=72: