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