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