| blob | 2383178b9f7548eda6aa6ac5fff8931e24ee89c8 |
1 .ig
2 groff.man
4 Last update: 14 July 2002
6 Copyright (C) 1989, 2002 Free Software Foundation, Inc.
7 Rewritten in 2002 by Bernd Warken <bwarken@mayn.de>
9 Permission is granted to copy, distribute and/or modify this document
10 under the terms of the GNU Free Documentation License, Version 1.1 or
11 any later version published by the Free Software Foundation; with the
12 Invariant Sections being this .ig-section and AUTHOR, with no
13 Front-Cover Texts, and with no Back-Cover Texts.
15 A copy of the Free Documentation License is included as a file called
16 FDL in the main directory of the groff source package.
17 ..
18 .
19 .\" --------------------------------------------------------------------
20 .\" Setup
21 .\" --------------------------------------------------------------------
22 .
23 .mso www.tmac
24 .
25 .\" set adjust to both
26 .ad b
27 .
28 .\" fonts of fixed length
29 .
30 .if n \{\
31 . mso tty-char.tmac
32 . ftr CR R
33 . ftr CI I
34 . ftr CB B
35 .\}
36 .
37 .if '\*[.T]'dvi' \
38 . ftr CB CW
39 .
40 .\" --------------------------------------------------------------------
41 .\" String definitions
42 .
43 .ds @- "\-\"
44 .ds @-- "\-\^\-\"
45 .
46 .ds Ellipsis .\|.\|.\"
47 .
48 .
49 .\" --------------------------------------------------------------------
50 .\" Begin of macro definitions
51 .de c
52 .\" this is like a comment request when escape mechanism is off
53 ..
54 .eo
55 .
56 .c --------------------------------------------------------------------
57 .de TP+
58 .br
59 .ns
60 .TP \$1
61 ..
62 .c --------------------------------------------------------------------
63 .c Like TP, but if specified indent is more than half
64 .c the current line-length - indent, use the default indent.
65 .de Tp
66 . ie \n[.$]=0:((0\$1)*2u>(\n.lu-\n(.iu)) .TP
67 . el .TP "\$1"
68 ..
69 .c --------------------------------------------------------------------
70 .de Text
71 . nop \)\$*
72 ..
73 .c --------------------------------------------------------------------
74 .de Synopsis
75 . ds @arg1 \$1\"
76 . nr @old_indent \n[.i]
77 . ad l
78 . in +\w'\f[B]\*[@arg1]\0'u
79 . ti \n[@old_indent]u
80 . B \*[@arg1]\0\c
81 . rr @old_indent
82 . rm @arg1
83 ..
84 .c --------------------------------------------------------------------
85 .de EndSynopsis
86 . ad
87 . in
88 ..
89 .c --------------------------------------------------------------------
90 .c ShortOpt[] (name [arg])
91 .c
92 .c short option in synopsis
93 .c
94 .de ShortOpt[]
95 . if \n[.$]=0 \
96 . return
97 . ds @opt \$1\"
98 . shift
99 . ie \n[.$]=0 \
100 . Text \f[R][\f[]\f[CB]\*[@-]\*[@opt]\f[]\f[R]]\f[]
101 . el \
102 . Text \f[R][\f[]\f[CB]\*[@-]\*[@opt]\~\f[]\f[I]\/\$*\f[]\f[R]]\f[]
103 . rm @opt
104 ..
105 .c --------------------------------------------------------------------
106 .c Option in synopsis (short option)
107 .de SynOpt
108 . if \n[.$]=0 \
109 . return
110 . ds @opt \$1\"
111 . shift
112 . ie \n[.$]=0 \
113 . Text \f[R][\f[]\f[CB]\*[@-]\*[@opt]\f[]\f[R]]\f[]
114 . el \
115 . Text \f[R][\f[]\f[CB]\*[@-]\*[@opt]\~\f[]\f[I]\/\$*\f[]\f[R]]\f[]
116 . rm @opt
117 ..
118 .c --------------------------------------------------------------------
119 .c ShortOpt ([char [punct]])
120 .c
121 .c `-c' somwhere in the text
122 .c second arg is punctuation
123 .c
124 .de ShortOpt
125 . ds @opt \$1\"
126 . shift
127 . Text \f[CB]\*[@-]\*[@opt]\f[]\/\$*
128 . rm @opt
129 ..
130 .c --------------------------------------------------------------------
131 .c LongOpt ([name [punct]])
132 .c
133 .c `--name' somwhere in the text
134 .c second arg is punctuation
135 .c
136 .de LongOpt
137 . ds @opt \$1\"
138 . shift
139 . Text \f[CB]\*[@--]\f[]\f[B]\*[@opt]\f[]\/\$*
140 . rm @opt
141 ..
142 .c --------------------------------------------------------------------
143 .c OptDef (shortopt [longopt [argument]])
144 .c
145 .c option documentation
146 .c args : `shortopt', `longopt' can be ""
147 .c
148 .de OptDef
149 . ds @short
150 . ds @long
151 . ds @arg
152 . if \n[.$]>=1 \{\
153 . ds @arg1 "\$1\"
154 . if !'\*[@arg1]'' \
155 . ds @short "\f[CB]\*[@-]\*[@arg1]\f[]\"
156 . if \n[.$]>=2 \{\
157 . if !'\*[@short]'' \
158 . as @short \f[CW]\0\f[]
159 . ds @arg2 "\$2\"
160 . if !'\*[@arg2]'' \
161 . ds @long "\f[CB]\*[@--]\f[]\f[B]\*[@arg2]\f[]\"
162 . if \n[.$]>=3 \{\
163 . if !'\*[@long]'' \
164 . as @long \|=\|\"
165 . shift 2
166 . ds @arg \f[I]\$*\"
167 . \}
168 . \}
169 . \}
170 . IP "\f[R]\*[@short]\*[@long]\*[@arg]\f[]"
171 . rm @arg
172 . rm @arg1
173 . rm @arg2
174 . rm @short
175 . rm @long
176 ..
177 .c --------------------------------------------------------------------
178 .c Continuation of an OptDef header.
179 .de OptDef+
180 . br
181 . ns
182 . OptDef \$@
183 ..
184 .c --------------------------------------------------------------------
185 .c Environment variable
186 .de EnvVar
187 . SM
188 . BR \$1 \$2
189 ..
190 .c --------------------------------------------------------------------
191 .c a shell command line
192 .de ShellCommand
193 . nr @font \n[.f]
194 . c replace argument separator by unbreakable space
195 . ds @args \$1\""
196 . shift
197 . while (\n[.$]>0) \{\
198 . ds @args \*[@args]\~\$1
199 . shift
200 . \}
201 . br
202 . ad l
203 . nh
204 . Text \f[I]sh#\h'1m'\f[P]\f[CR]\*[@args]\f[P]\&\"
205 . ft R
206 . ft P
207 . hy
208 . ad
209 . ft \n[@font]
210 . br
211 . rr @font
212 . rm @args
213 ..
214 .c --------------------------------------------------------------------
215 .c `char or string'
216 .de Quoted
217 . ft CR
218 . Text \[oq]\$*\[cq]
219 . ft
220 ..
221 .c --------------------------------------------------------------------
222 .c End of macro definitions
223 .ec
224 .
225 .
226 .\" --------------------------------------------------------------------
227 .\" Title
228 .\" --------------------------------------------------------------------
229 .
230 .TH GROFF 1 "23 September 2003" "Groff Version 1.18.1"
231 .SH NAME
232 groff \- front-end for the groff document formatting system
233 .
234 .
235 .\" --------------------------------------------------------------------
236 .SH SYNOPSIS
237 .\" --------------------------------------------------------------------
238 .
239 .ad l
240 .Synopsis groff
241 .ShortOpt[] abcegilpstzCEGNRSUVXZ
242 .ShortOpt[] d cs
243 .ShortOpt[] f fam
244 .ShortOpt[] F dir
245 .ShortOpt[] I dir
246 .ShortOpt[] L arg
247 .ShortOpt[] m name
248 .ShortOpt[] M dir
249 .ShortOpt[] n num
250 .ShortOpt[] o list
251 .ShortOpt[] P arg
252 .ShortOpt[] r cn
253 .ShortOpt[] T dev
254 .ShortOpt[] w name
255 .ShortOpt[] W name
256 .RI [ file
257 .Text \*[Ellipsis]]
258 .EndSynopsis
259 .
260 .Synopsis groff
261 .ShortOpt h
262 |
263 .LongOpt help
264 .EndSynopsis
265 .
266 .Synopsis groff
267 .ShortOpt v
268 |
269 .LongOpt version
270 .RI [ option
271 .Text \*[Ellipsis]]
272 .EndSynopsis
273 .
274 .P
275 The command line is parsed according to the usual GNU convention.
276 .
277 The whitespace between a command line option and its argument is
278 optional.
279 .
280 Options can be grouped behind a single
281 .ShortOpt
282 (minus character).
283 .
284 A filename of
285 .ShortOpt
286 (minus character) denotes the standard input.
287 .
288 .
289 .\" --------------------------------------------------------------------
290 .SH DESCRIPTION
291 .\" --------------------------------------------------------------------
292 .
293 This document describes the
294 .B groff
295 program, the main front-end for the
296 .I groff
297 document formatting system.
298 .
299 The
300 .I groff
301 program and macro suite is the implementation of a
302 .BR roff (7)
303 system within the free software collection
304 .URL http://\:www.gnu.org "GNU" .
305 .
306 The
307 .I groff
308 system has all features of the classical
309 .IR roff ,
310 but adds many extensions.
311 .
312 .P
313 The
314 .B groff
315 program allows to control the whole
316 .I groff
317 system by comand line options.
318 .
319 This is a great simplification in comparison to the classical case (which
320 uses pipes only).
321 .
322 .
323 .\" --------------------------------------------------------------------
324 .SH OPTIONS
325 .\" --------------------------------------------------------------------
326 .
327 As
328 .B groff
329 is a wrapper program for
330 .B troff
331 both programs share a set of options.
332 .
333 But the
334 .B groff
335 program has some additional, native options and gives a new meaning to
336 some
337 .B troff
338 options.
339 .
340 On the other hand, not all
341 .B troff
342 options can be fed into
343 .BR groff .
344 .
345 .
346 .\" --------------------------------------------------------------------
347 .SS Native groff Options
348 .\" --------------------------------------------------------------------
349 .
350 The following options either do not exist for
351 .B troff
352 or are differently interpreted by
353 .BR groff .
354 .
355 .
356 .OptDef e
357 Preprocess with
358 .BR eqn .
359 .
360 .
361 .OptDef g
362 Preprocess with
363 .BR grn .
364 .
365 .
366 .OptDef G
367 Preprocess with
368 .BR grap .
369 .
370 .
371 .OptDef h help
372 Print a help message.
373 .
374 .
375 .OptDef I "" dir
376 Add search directory for
377 .BR \%soelim (1).
378 This option implies the
379 .ShortOpt s
380 option.
381 .
382 .
383 .OptDef l
384 Send the output to a spooler program for printing.
385 .
386 The command that should be used for this is specified by the
387 .B print
388 command in the device description file, see
389 .BR \%groff_font (5).
390 If this command is not present, the output is piped into the
391 .BR lpr (1)
392 program by default.
393 .
394 See options
395 .ShortOpt L
396 and
397 .ShortOpt X .
398 .
399 .
400 .OptDef L "" arg
401 Pass
402 .I arg
403 to the spooler program.
404 Several arguments should be passed with a separate
405 .ShortOpt L
406 option each.
407 .
408 Note that
409 .B groff
410 does not prepend
411 .ShortOpt\" just a minus sign
412 (a minus sign) to
413 .I arg
414 before passing it to the spooler program.
415 .
416 .
417 .OptDef N
418 Don't allow newlines within
419 .I eqn
420 delimiters.
421 .
422 This is the same as the
423 .ShortOpt N
424 option in
425 .BR eqn .
426 .
427 .
428 .OptDef p
429 Preprocess with
430 .BR pic .
431 .
432 .
433 .OptDef P "" "-option"
434 .OptDef+ P "" "-option \f[CB]-P\f[] arg"
435 Pass
436 .I -option
437 or
438 .I -option arg
439 to the postprocessor.
440 .
441 The option must be specified with the necessary preceding minus
442 sign(s)
443 .Quoted \*[@-]
444 or
445 .Quoted \*[@--]
446 because groff does not prepend any dashes before passing it to the
447 postprocessor.
448 .
449 For example, to pass a title to the gxditview postprocessor, the shell
450 command
451 .IP
452 .ShellCommand groff -X -P -title -P 'groff it' \f[I]foo\f[]
453 .IP
454 is equivalent to
455 .IP
456 .ShellCommand groff -X -Z \f[I]foo\f[] | gxditview -title 'groff it' -
457 .
458 .
459 .OptDef R
460 Preprocess with
461 .BR refer .
462 .
463 No mechanism is provided for passing arguments to
464 .B refer
465 because most
466 .B refer
467 options have equivalent language elements that can be specified within
468 the document.
469 .
470 See
471 .BR \%refer (1)
472 for more details.
473 .
474 .
475 .OptDef s
476 Preprocess with
477 .BR soelim .
478 .
479 .
480 .OptDef S
481 Safer mode.
482 .
483 Pass the
484 .ShortOpt S
485 option to
486 .B pic
487 and disable the following
488 .B troff
489 requests:
490 .BR .open ,
491 .BR .opena ,
492 .BR .pso ,
493 .BR .sy ,
494 and
495 .BR .pi .
496 For security reasons, safer mode is enabled by default.
497 .
498 .
499 .OptDef t
500 Preprocess with
501 .BR tbl .
502 .
503 .
504 .OptDef T "" dev
505 Set output device to
506 .IR dev .
507 The possible values in
508 .I groff
509 are
510 .BR ascii ,
511 .BR cp1047 ,
512 .BR dvi ,
513 .BR html ,
514 .BR latin1 ,
515 .BR lbp ,
516 .BR lj4 ,
517 .BR ps ,
518 .BR utf8 ,
519 .BR X75 ,
520 and
521 .BR X100 .
522 .
523 Additionally,
524 .B X75-12
525 and
526 .B X100-12
527 are available for documents which use 12\|pt as the base document size.
528 .
529 The default device is
530 .BR ps .
531 .
532 .
533 .OptDef U
534 Unsafe mode.
535 .
536 Reverts to the (old) unsafe behaviour; see option
537 .ShortOpt S .
538 .
539 .
540 .OptDef v version
541 Output version information of
542 .B groff
543 and of all programs that are run by it; that is, the given command line
544 is parsed in the usual way, passing
545 .ShortOpt v
546 to all subprograms.
547 .
548 .
549 .OptDef V
550 Output the pipeline that would be run by
551 .BR groff
552 (as a wrapper program), but do not execute it.
553 .
554 .
555 .OptDef X
556 Use
557 .B gxditview
558 instead of using the usual postprocessor to (pre)view a document.
559 .
560 The printing spooler behavior as outlined with options
561 .ShortOpt l
562 and
563 .ShortOpt L
564 is carried over to
565 .BR \%gxditview (1)
566 by determining an argument for the
567 .B -printCommand
568 option of
569 .BR \%gxditview (1).
570 .
571 This sets the default
572 .B Print
573 action and the corresponding menu entry to that value.
574 .
575 .ShortOpt X
576 only produces good results with
577 .ShortOpt Tps ,
578 .ShortOpt TX75 ,
579 .ShortOpt TX75-12 ,
580 .ShortOpt TX100 ,
581 and
582 .ShortOpt TX100-12 .
583 .
584 The default resolution for previewing
585 .ShortOpt Tps
586 output is 75\|dpi; this can be changed by passing the
587 .ShortOpt resolution
588 option to
589 .BR gxditview ,
590 for example
591 .
592 .IP
593 .ShellCommand groff -X -P-resolution -P100 -man foo.1
594 .
595 .
596 .OptDef z
597 Suppress output generated by
598 .BR troff .
599 Only error messages will be printed.
600 .
601 .
602 .OptDef Z
603 Do not postprocess the output of
604 .B troff
605 that is normally
606 called automatically by
607 .BR groff .
608 This will print the intermediate output to standard output; see
609 .BR \%groff_out (5).
610 .
611 .
612 .\" --------------------------------------------------------------------
613 .SS Tranparent Options
614 .\" --------------------------------------------------------------------
615 .
616 The following options are transparently handed over to the formatter
617 program
618 .B troff
619 that is called by groff subsequently.
620 .
621 These options are described in more detail in
622 .BR troff (1).
623 .
624 .OptDef a
625 ascii approximation of output.
626 .
627 .OptDef b
628 backtrace on error or warning.
629 .
630 .OptDef c
631 disable color output.
632 .
633 .OptDef C
634 enable compatibility mode.
635 .
636 .OptDef d "" cs
637 .OptDef+ d "" name=s
638 define string.
639 .
640 .OptDef E
641 disable
642 .B troff
643 error messages.
644 .
645 .OptDef f "" fam
646 set default font family.
647 .
648 .OptDef F "" dir
649 set path for font DESC files.
650 .
651 .OptDef i
652 process standard input after the specified input files.
653 .
654 .OptDef m "" name
655 include macro file \f[I]name\f[]\f[B].tmac\f[] (or
656 \f[B]tmac.\f[]\f[I]name\f[]); see also
657 .BR \%groff_tmac (5).
658 .
659 .OptDef M "" dir
660 path for macro files.
661 .
662 .OptDef n "" num
663 number the first page
664 .IR num .
665 .
666 .OptDef o "" list
667 output only pages in
668 .IR list .
669 .
670 .OptDef r "" cn
671 .OptDef+ r "" name=n
672 set number register.
673 .
674 .OptDef w "" name
675 enable warning
676 .IR name .
677 .
678 .OptDef W "" name
679 disable warning
680 .IR name .
681 .
682 .
683 .\" --------------------------------------------------------------------
684 .SH "USING GROFF"
685 .\" --------------------------------------------------------------------
686 .
687 The
688 .I groff system
689 implements the infrastructure of classical roff; see
690 .BR roff (7)
691 for a survey on how a roff system works in general.
692 .
693 Due to the front-end programs available within the groff system, using
694 .I groff
695 is much easier than
696 .IR "classical roff" .
697 .
698 This section gives an overview of the parts that consitute the groff
699 system.
700 .
701 It complements
702 .BR roff (7)
703 with groff-specific features.
704 .
705 This section can be regarded as a guide to the documentation around
706 the groff system.
707 .
708 .
709 .\" --------------------------------------------------------------------
710 .SS Front-ends
711 .\" --------------------------------------------------------------------
712 .
713 The
714 .B groff
715 program is a wrapper around the
716 .BR troff (1)
717 program.
718 .
719 It allows to specify the preprocessors by command line options and
720 automatically runs the postprocessor that is appropriate for the
721 selected device.
722 .
723 Doing so, the sometimes tedious piping mechanism of classical
724 .BR roff (7)
725 can be avoided.
726 .
727 .P
728 The
729 .BR grog (1)
730 program can be used for guessing the correct groff command line to
731 format a file.
732 .
733 .P
734 The
735 .BR \%groffer (1)
736 program is an allround-viewer for groff files and man pages.
737 .
738 .
739 .\" --------------------------------------------------------------------
740 .SS Preprocessors
741 .\" --------------------------------------------------------------------
742 .
743 The groff preprocessors are reimplementations of the classical
744 preprocessors with moderate extensions.
745 .
746 The preprocessors distributed with the
747 .I groff
748 package are
749 .
750 .TP
751 .BR eqn (1)
752 for mathematical formul\(ae,
753 .TP
754 .BR grn (1)
755 for including
756 .BR gremlin (1)
757 pictures,
758 .TP
759 .BR pic (1)
760 for drawing diagrams,
761 .TP
762 .BR \%refer (1)
763 for bibliographic references,
764 .TP
765 .BR \%soelim (1)
766 for including macro files from standard locations,
767 .
768 .P
769 and
770 .TP
771 .BR tbl (1)
772 for tables.
773 .
774 .P
775 Besides these, there are some internal preprocessors that are
776 automatically run with some devices.
777 .
778 These aren't visible to the user.
779 .
780 .
781 .\" --------------------------------------------------------------------
782 .SS "Macro Packages"
783 .\" --------------------------------------------------------------------
784 .
785 Macro packages can be included by option
786 .ShortOpt m .
787 .
788 The groff system implements and extends all classical macro packages
789 in a compatible way and adds some packages of its own.
790 .
791 Actually, the following macro packages come with
792 .IR groff :
793 .
794 .TP
795 .B man
796 The traditional man page format; see
797 .BR \%groff_man (7).
798 It can be specified on the command line as
799 .ShortOpt man
800 or
801 .ShortOpt m
802 .BR man .
803 .
804 .TP
805 .B mandoc
806 The general package for man pages; it automatically recognizes
807 whether the documents uses the
808 .I man
809 or the
810 .I mdoc
811 format and branches to the corresponding macro package.
812 .
813 It can be specified on the command line as
814 .ShortOpt mandoc
815 or
816 .ShortOpt m
817 .BR mandoc .
818 .
819 .TP
820 .B mdoc
821 The BSD-style man page format; see
822 .BR \%groff_mdoc (7).
823 It can be specified on the command line as
824 .ShortOpt mdoc
825 or
826 .ShortOpt m
827 .BR mdoc .
828 .
829 .TP
830 .B me
831 The classical
832 .I me
833 document format; see
834 .BR \%groff_me (7).
835 It can be specified on the command line as
836 .ShortOpt me
837 or
838 .ShortOpt m
839 .BR me .
840 .
841 .TP
842 .B mm
843 The classical
844 .I mm
845 document format; see
846 .BR \%groff_mm (7).
847 It can be specified on the command line as
848 .ShortOpt mm
849 or
850 .ShortOpt m
851 .BR mm .
852 .
853 .TP
854 .B ms
855 The classical
856 .I ms
857 document format; see
858 .BR \%groff_ms (7).
859 It can be specified on the command line as
860 .ShortOpt ms
861 or
862 .ShortOpt m
863 .BR ms .
864 .
865 .TP
866 .B www
867 HTML-like macros for inclusion in arbitrary groff documents; see
868 .BR \%groff_www (7).
869 .
870 .P
871 Details on the naming of macro files and their placement can be found
872 in
873 .BR \%groff_tmac (5).
874 .
875 .
876 .\" --------------------------------------------------------------------
877 .SS "Programming Language"
878 .\" --------------------------------------------------------------------
879 .
880 General concepts common to all roff programming languages are
881 described in
882 .BR roff (7).
883 .
884 .P
885 The groff extensions to the classical troff language are documented in
886 .BR \%groff_diff (7).
887 .
888 .P
889 The groff language as a whole is described in the (still incomplete)
890 .IR "groff info file" ;
891 a short (but complete) reference can be found in
892 .BR groff (7).
893 .
894 .
895 .\" --------------------------------------------------------------------
896 .SS Formatters
897 .\" --------------------------------------------------------------------
898 .
899 The central roff formatter within the groff system is
900 .BR troff (1).
901 It provides the features of both the classical troff and nroff, as
902 well as the groff extensions.
903 .
904 The command line option
905 .ShortOpt C
906 switches
907 .B troff
908 into
909 .I "compatibility mode"
910 which tries to emulate classical roff as much as possible.
911 .
912 .P
913 There is a shell script
914 .BR nroff (1)
915 that emulates the behavior of classical nroff.
916 .
917 It tries to automatically select the proper output encoding, according to
918 the current locale.
919 .
920 .P
921 The formatter program generates
922 .IR "intermediate output" ;
923 see
924 .BR \%groff_out (7).
925 .
926 .
927 .\" --------------------------------------------------------------------
928 .SS Devices
929 .\" --------------------------------------------------------------------
930 .
931 In roff, the output targets are called
932 .IR devices .
933 A device can be a piece of hardware, e.g. a printer, or a software
934 file format.
935 .
936 A device is specified by the option
937 .ShortOpt T .
938 The groff devices are as follows.
939 .
940 .TP
941 .B ascii
942 Text output using the
943 .BR ascii (7)
944 character set.
945 .
946 .TP
947 .B cp1047
948 Text output using the EBCDIC code page IBM cp1047 (e.g. OS/390 Unix).
949 .
950 .TP
951 .B nippon
952 Text output using the Japanese-EUC character set.
953 .
954 .TP
955 .B dvi
956 TeX DVI format.
957 .
958 .TP
959 .B html
960 HTML output.
961 .
962 .TP
963 .B ascii8
964 For typewriter-like devices. Unlike
965 .BR ascii ,
966 this device is 8 bit clean. This device is intended to be used
967 for codesets other than ASCII and ISO-8859-1.
968 .TP
969 .B latin1
970 Text output using the ISO Latin-1 (ISO 8859-1) character set; see
971 .BR iso_8859_1 (7).
972 .
973 .TP
974 .B lbp
975 Output for Canon CAPSL printers (LBP-4 and LBP-8 series laser printers).
976 .
977 .TP
978 .B lj4
979 HP LaserJet4-compatible (or other PCL5-compatible) printers.
980 .
981 .TP
982 .B ps
983 PostScript output; suitable for printers and previewers like
984 .BR gv (1).
985 .
986 .TP
987 .B utf8
988 Text output using the Unicode (ISO 10646) character set with UTF-8
989 encoding; see
990 .BR unicode (7).
991 .
992 .TP
993 .B X75
994 75dpi X Window System output suitable for the previewers
995 .BR xditview (1x)
996 and
997 .BR \%gxditview (1).
998 A variant for a 12\|pt document base font is
999 .BR X75-12 .
1000 .
1001 .TP
1002 .B X100
1003 100dpi X Window System output suitable for the previewers
1004 .BR xditview (1x)
1005 and
1006 .BR \%gxditview (1).
1007 A variant for a 12\|pt document base font is
1008 .BR X100-12 .
1009 .
1010 .P
1011 The postprocessor to be used for a device is specified by the
1012 .B postpro
1013 command in the device description file; see
1014 .BR \%groff_font (5).
1015 .
1016 This can be overridden with the
1017 .B \-X
1018 option.
1019 .
1020 .P
1021 The default device is
1022 .BR ps .
1023 .
1024 .
1025 .\" --------------------------------------------------------------------
1026 .SS Postprocessors
1027 .\" --------------------------------------------------------------------
1028 .
1029 groff provides 3\~hardware postprocessors:
1030 .
1031 .TP
1032 .BR \%grolbp (1)
1033 for some Canon printers,
1034 .TP
1035 .BR \%grolj4 (1)
1036 for printers compatible to the HP LaserJet\~4 and PCL5,
1037 .TP
1038 .BR \%grotty (1)
1039 for text output using various encodings, e.g. on text-oriented
1040 terminals or line-printers.
1041 .
1042 .P
1043 Today, most printing or drawing hardware is handled by the operating
1044 system, by device drivers, or by software interfaces, usally accepting
1045 PostScript.
1046 .
1047 Consequently, there isn't an urgent need for more hardware device
1048 postprocessors.
1049 .
1050 .P
1051 The groff software devices for conversion into other document file
1052 formats are
1053 .
1054 .TP
1055 .BR \%grodvi (1)
1056 for the DVI format,
1057 .TP
1058 .BR \%grohtml (1)
1059 for HTML format,
1060 .TP
1061 .BR grops (1)
1062 for PostScript.
1063 .
1064 .P
1065 Combined with the many existing free conversion tools this should
1066 be sufficient to convert a troff document into virtually any existing
1067 data format.
1068 .
1069 .
1070 .\" --------------------------------------------------------------------
1071 .SS Utilities
1072 .\" --------------------------------------------------------------------
1073 .
1074 The following utility programs around groff are available.
1075 .
1076 .TP
1077 .BR \%addftinfo (1)
1078 Add information to troff font description files for use with groff.
1079 .
1080 .TP
1081 .BR \%afmtodit (1)
1082 Create font description files for PostScript device.
1083 .
1084 .TP
1085 .BR \%groffer (1)
1086 General viewer program for groff files and man pages.
1087 .
1088 .TP
1089 .BR \%gxditview (1)
1090 The groff X viewer, the GNU version of xditview.
1091 .
1092 .TP
1093 .BR \%hpftodit (1)
1094 Create font description files for lj4 device.
1095 .
1096 .TP
1097 .BR \%indxbib (1)
1098 Make inverted index for bibliographic databases.
1099 .
1100 .TP
1101 .BR lkbib (1)
1102 Search bibliographic databases.
1103 .
1104 .TP
1105 .BR \%lookbib (1)
1106 Interactively search bibliographic databases.
1107 .
1108 .TP
1109 .BR \%pfbtops (1)
1110 Translate a PostScript font in .pfb format to ASCII.
1111 .
1112 .TP
1113 .BR \%tfmtodit (1)
1114 Create font description files for TeX DVI device.
1115 .
1116 .TP
1117 .BR \%xditview (1x)
1118 roff viewer distributed with X window.
1119 .
1120 .
1121 .\" --------------------------------------------------------------------
1122 .SH ENVIRONMENT
1123 .\" --------------------------------------------------------------------
1124 .
1125 Normally, the path separator in the following environment variables is the
1126 colon; this may vary depending on the operating system.
1127 .
1128 For example, DOS and Windows use a semicolon instead.
1129 .
1130 .TP
1131 .EnvVar GROFF_BIN_PATH
1132 This search path, followed by
1133 .EnvVar $PATH ,
1134 will be used for commands that are executed by
1135 .BR groff .
1136 .
1137 If it is not set then the directory where the groff binaries were
1138 installed is prepended to
1139 .EnvVar PATH .
1140 .
1141 .TP
1142 .EnvVar GROFF_COMMAND_PREFIX
1143 When there is a need to run different roff implementations at the same
1144 time
1145 .I groff
1146 provides the facility to prepend a prefix to most of its programs that
1147 could provoke name clashings at run time (default is to have none).
1148 .
1149 Historically, this prefix was the character
1150 .BR g ,
1151 but it can be anything.
1152 .
1153 For example,
1154 .BR gtroff
1155 stood for
1156 .IR groff 's
1157 .BR troff ,
1158 .BR gtbl
1159 for the
1160 .I groff
1161 version of
1162 .BR tbl .
1163 .
1164 By setting
1165 .EnvVar GROFF_COMMAND_PREFIX
1166 to different values, the different roff installations can be
1167 addressed.
1168 .
1169 More exactly, if it is set to prefix
1170 .I xxx
1171 then
1172 .B groff
1173 as a wrapper program will internally call
1174 .IB xxx troff
1175 instead of
1176 .BR troff .
1177 This also applies to the preprocessors
1178 .BR \%eqn ,
1179 .BR \%grn ,
1180 .BR \%pic ,
1181 .BR \%refer ,
1182 .BR \%tbl ,
1183 .BR \%soelim ,
1184 and to the utilities
1185 .B \%indxbib
1186 and
1187 .BR \%lookbib .
1188 .
1189 This feature does not apply to any programs different from the ones
1190 above (most notably
1191 .B groff
1192 itself) since they are unique to the groff package.
1193 .
1194 .
1195 .TP
1196 .EnvVar GROFF_FONT_PATH
1197 A list of directories in which to search for the
1198 .BI dev name
1199 directory in addition to the default ones.
1200 .
1201 See
1202 .BR troff (1)
1203 and
1204 .BR \%groff_font (5)
1205 for more details.
1206 .
1207 .
1208 .TP
1209 .EnvVar GROFF_TMAC_PATH
1210 A list of directories in which to search for macro files in addition to
1211 the default directories.
1212 .
1213 See
1214 .BR troff (1)
1215 and
1216 .BR \%groff_tmac (5)
1217 for more details.
1218 .
1219 .
1220 .TP
1221 .EnvVar GROFF_TMPDIR
1222 The directory in which temporary files will be created.
1223 .
1224 If this is not set but the environment variable
1225 .EnvVar TMPDIR
1226 instead, temporary files will be created in the directory
1227 .EnvVar $TMPDIR .
1228 .
1229 Otherwise temporary files will be created in
1230 .BR /tmp .
1231 The
1232 .BR \%refer (1),
1233 .BR \%groffer (1),
1234 .BR \%grohtml (1),
1235 and
1236 .BR grops (1)
1237 commands use temporary files.
1238 .
1239 .
1240 .TP
1241 .EnvVar GROFF_TYPESETTER
1242 Preset the default device.
1243 .
1244 If this is not set the
1245 .B ps
1246 device is used as default.
1247 .
1248 This device name is overwritten by the option
1249 .ShortOpt T .
1250 .
1251 .
1252 .\" --------------------------------------------------------------------
1253 .SH FILES
1254 .\" --------------------------------------------------------------------
1255 .
1256 There are some directories in which
1257 .I groff
1258 installs all of its data files.
1259 .
1260 Due to different installation habits on different operating systems,
1261 their locations are not absolutely fixed, but their function is
1262 clearly defined and coincides on all systems.
1263 .
1264 .
1265 .\" --------------------------------------------------------------------
1266 .SS "groff Macro Directory"
1267 .\" --------------------------------------------------------------------
1268 .
1269 This contains all information related to macro packages.
1270 .
1271 Note that more than a single directory is searched for those files
1272 as documented in
1273 .BR \%groff_tmac (5).
1274 .
1275 For the groff installation corresponding to this document, it is
1276 located at
1277 .IR /usr/share/groff/1.18.1/tmac .
1278 .
1279 The following files contained in the
1280 .I groff macro directory
1281 have a special meaning:
1282 .
1283 .
1284 .TP
1285 .B troffrc
1286 Initialization file for troff.
1287 .
1288 This is interpreted by
1289 .B troff
1290 before reading the macro sets and any input.
1291 .
1292 .
1293 .TP
1294 .B troffrc-end
1295 Final startup file for troff, it is parsed after all macro sets have
1296 been read.
1297 .
1298 .
1299 .TP
1300 .IB name .tmac
1301 .TP+
1302 .BI tmac. name
1303 Macro file for macro package
1304 .IR name .
1305 .
1306 .
1307 .\" --------------------------------------------------------------------
1308 .SS "groff Font Directory"
1309 .\" --------------------------------------------------------------------
1310 .
1311 This contains all information related to output devices.
1312 .
1313 Note that more than a single directory is searched for those files; see
1314 .BR troff (1).
1315 .
1316 For the groff installation corresponding to this document, it is
1317 located at
1318 .IR /usr/share/groff/1.18.1/font .
1319 .
1320 The following files contained in the
1321 .I groff font directory
1322 have a special meaning:
1323 .
1324 .
1325 .TP
1326 .BI dev name /DESC
1327 Device description file for device
1328 .IR name ,
1329 see
1330 .BR \%groff_font (5).
1331 .
1332 .
1333 .TP
1334 .BI dev name / F
1335 Font file for font
1336 .I F
1337 of device
1338 .IR name .
1339 .
1340 .
1341 .\" --------------------------------------------------------------------
1342 .SH EXAMPLES
1343 .\" --------------------------------------------------------------------
1344 .
1345 The following example illustrates the power of the
1346 .B groff
1347 program as a wrapper around
1348 .BR troff .
1349 .
1350 .P
1351 To process a roff file using the preprocessors
1352 .B tbl
1353 and
1354 .B pic
1355 and the
1356 .B me
1357 macro set, classical troff had to be called by
1358 .
1359 .P
1360 .ShellCommand pic foo.me | tbl | troff -me -Tlatin1 | grotty
1361 .
1362 .P
1363 Using
1364 .BR groff ,
1365 this pipe can be shortened to the equivalent command
1366 .P
1367 .ShellCommand groff -p -t -me -T latin1 foo.me
1368 .
1369 .P
1370 An even easier way to call this is to use
1371 .BR grog (1)
1372 to guess the preprocessor and macro options and execute the generated
1373 command (by specifying shell left quotes)
1374 .P
1375 .ShellCommand `grog -Tlatin1 foo.me`
1376 .
1377 .P
1378 The simplest way is to view the contents in an automated way by
1379 calling
1380 .
1381 .P
1382 .ShellCommand groffer foo.me
1383 .
1384 .
1385 .\" --------------------------------------------------------------------
1386 .SH BUGS
1387 .\" --------------------------------------------------------------------
1388 .
1389 .P
1390 On EBCDIC hosts (e.g. OS/390 Unix), output devices
1391 .B ascii
1392 and
1393 .B latin1
1394 aren't available.
1395 .
1396 Similarly, output for EBCDIC code page
1397 .B cp1047
1398 is not available on ASCII based operating systems.
1399 .
1400 .P
1401 Report bugs to bug-groff@gnu.org.
1402 .
1403 Include a complete, self-contained example that will allow the bug to
1404 be reproduced, and say which version of groff you are using.
1405 .
1406 .
1407 .\" --------------------------------------------------------------------
1408 .SH AVAILABILITY
1409 .\" --------------------------------------------------------------------
1410 .
1411 Information on how to get groff and related information is available
1412 at the
1413 .URL http://\:www.gnu.org/\:software/\:groff "GNU website" .
1414 The most recent released version of groff is available for anonymous
1415 ftp at the
1416 .URL ftp://ftp.ffii.org/\:pub/\:groff/\:devel/\:groff-current.tar.gz \
1417 "groff development site" .
1418 .
1419 .P
1420 Three groff mailing lists are available:
1421 .TP
1422 .MTO bug-groff@gnu.org
1423 for reporting bugs,
1424 .
1425 .TP
1426 .MTO groff@gnu.org
1427 for general discussion of groff,
1428 .
1429 .TP
1430 .MTO groff-commit@ffii.org
1431 a read-only list showing logs of commitments to the CVS repository.
1432 .
1433 .P
1434 Details on CVS access and much more can be found in the file
1435 .B README
1436 at the top directory of the groff source package.
1437 .
1438 .P
1439 There is a free implementation of the
1440 .B grap
1441 preprocessor, written by
1442 .MTO faber@lunabase.org " Ted Faber" .
1443 .
1444 The actual version can be found at the
1445 .
1446 .URL http://\:www.lunabase.org/\:~faber/\:Vault/\:software/\:grap/ \
1447 "grap website" .
1448 This is the only grap version supported by groff.
1449 .
1450 .
1451 .\" --------------------------------------------------------------------
1452 .SH AUTHORS
1453 .\" --------------------------------------------------------------------
1454 .
1455 Copyright \(co 1989, 2002 Free Software Foundation, Inc.
1456 .
1457 .P
1458 This document is distributed under the terms of the FDL (GNU Free
1459 Documentation License) version 1.1 or later.
1460 .
1461 You should have received a copy of the FDL on your system, it is also
1462 available on-line at the
1463 .URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" .
1464 .
1465 .P
1466 This document is based on the original groff man page written by
1467 .MTO jjc@jclark.com "James Clark" .
1468 .
1469 It was rewritten, enhanced, and put under the FDL license by
1470 .MTO bwarken@mayn.de "Bernd Warken" .
1471 .
1472 It is maintained by
1473 .MTO wl@gnu.org "Werner Lemberg" .
1474 .
1475 .P
1476 .I groff
1477 is a GNU free software project.
1478 .
1479 All parts of the
1480 .I groff package
1481 are protected by GNU copyleft licenses.
1482 .
1483 The software files are distributed under the terms of the GNU General
1484 Public License (GPL), while the documentation files mostly use the GNU
1485 Free Documentation License (FDL).
1486 .
1487 .
1488 .\" --------------------------------------------------------------------
1489 .SH "SEE ALSO"
1490 .\" --------------------------------------------------------------------
1491 .
1492 The
1493 .IR "groff info file"
1494 contains all information on the groff system within a single document.
1495 .
1496 Beneath the detailed documentation of all aspects, it provides
1497 examples and background information.
1498 .
1499 See
1500 .BR info (1)
1501 on how to read it.
1502 .
1503 .P
1504 Due to its complex structure, the groff system has many man pages.
1505 .
1506 They can be read with
1507 .BR man (1)
1508 or
1509 .BR \%groffer (1).
1510 .
1511 .TP
1512 Introduction, history and further readings:
1513 .BR roff (7).
1514 .
1515 .TP
1516 Viewer for groff files:
1517 .BR \%groffer (1),
1518 .BR \%gxditview (1),
1519 .BR \%xditview (1x).
1520 .
1521 .TP
1522 Wrapper programs for formatters:
1523 .BR \%groff (1),
1524 .BR \%grog (1).
1525 .
1526 .TP
1527 Roff preprocessors:
1528 .BR \%eqn (1),
1529 .BR \%grn (1),
1530 .BR \%pic (1),
1531 .BR \%refer (1),
1532 .BR \%soelim (1),
1533 .BR \%tbl (1),
1534 .BR grap (1).
1535 .
1536 .TP
1537 Roff language with the groff extensions:
1538 .BR \%groff (7),
1539 .BR \%groff_char (7),
1540 .BR \%groff_diff (7),
1541 .BR \%groff_font (5).
1542 .
1543 .TP
1544 Roff formatter programs:
1545 .BR \%nroff (1),
1546 .BR \%troff (1),
1547 .BR ditroff (7).
1548 .
1549 .TP
1550 The intermediate output language:
1551 .BR \%groff_out (7).
1552 .
1553 .TP
1554 Postprocessors for the output devices:
1555 .BR \%grodvi (1),
1556 .BR \%grohtml (1),
1557 .BR \%grolbp (1),
1558 .BR \%grolj4 (1),
1559 .BR \%grops (1),
1560 .BR \%grotty (1).
1561 .
1562 .TP
1563 Groff macro packages and macro-specific utilities:
1564 .BR \%groff_tmac (5),
1565 .BR \%groff_man (7),
1566 .BR \%groff_mdoc (7),
1567 .BR \%groff_me (7),
1568 .BR \%groff_mm (7),
1569 .BR \%groff_mmse (7),
1570 .BR \%groff_mom (7),
1571 .BR \%groff_ms (7),
1572 .BR \%groff_www (7),
1573 .BR \%mmroff (7).
1574 .
1575 .TP
1576 The following utilities are available:
1577 .BR \%addftinfo (1),
1578 .BR \%afmtodit (1),
1579 .BR \%eqn2graph (1),
1580 .BR \%groffer (1),
1581 .BR \%gxditview (1),
1582 .BR \%hpftodit (1),
1583 .BR \%indxbib (1),
1584 .BR \%lookbib (1),
1585 .BR \%pfbtops (1),
1586 .BR \%pic2graph (1),
1587 .BR \%tfmtodit (1).
1588 .
1589 .
1590 .\" --------------------------------------------------------------------
1591 .\" Emacs setup
1592 .\" --------------------------------------------------------------------
1593 .
1594 .\" Local Variables:
1595 .\" mode: nroff
1596 .\" End: