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