Debian Codegraph @

upstream/debian-unstable/man1/groff.1

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