Debian Codegraph @

upstream/opensuse-tumbleweed/man1/groff.1

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