1GROFF(1)                    General Commands Manual                   GROFF(1)
2
3
4

NAME

6       groff - front-end for the groff document formatting system
7

SYNOPSIS

9       groff [-abcegilpstzCEGNRSUVXZ] [-d cs] [-f fam] [-F dir] [-I dir]
10             [-L arg] [-m name] [-M dir] [-n num] [-o list] [-P arg] [-r cn]
11             [-T dev] [-w name] [-W name] [file ...]
12       groff -h | --help
13       groff -v | --version [option ...]
14
15       The  command line is parsed according to the usual GNU convention.  The
16       whitespace between a command line option and its argument is  optional.
17       Options can be grouped behind a single - (minus character).  A filename
18       of - (minus character) denotes the standard input.
19

DESCRIPTION

21       This document describes the groff program, the main front-end  for  the
22       groff document formatting system.  The groff program and macro suite is
23       the implementation of a roff(7) system within the free software collec‐
24       tion  GNU  ⟨http://www.gnu.org⟩.   The groff system has all features of
25       the classical roff, but adds many extensions.
26
27       The groff program allows to control the whole groff system  by  command
28       line  options.   This  is  a  great simplification in comparison to the
29       classical case (which uses pipes only).
30

OPTIONS

32       As groff is a wrapper program for troff both programs share  a  set  of
33       options.  But the groff program has some additional, native options and
34       gives a new meaning to some troff options.  On the other hand, not  all
35       troff options can be fed into groff.
36
37   Native groff Options
38       The  following options either do not exist for troff or are differently
39       interpreted by groff.
40
41       -e     Preprocess with eqn.
42
43       -g     Preprocess with grn.
44
45       -G     Preprocess with grap.
46
47       -h --help
48              Print a help message.
49
50       -I dir Add search directory for soelim(1).  This option implies the  -s
51              option.
52
53       -l     Send  the output to a spooler program for printing.  The command
54              that should be used for this is specified by the  print  command
55              in the device description file, see groff_font(5).  If this com‐
56              mand is not present, the output is piped into the lpr(1) program
57              by default.  See options -L and -X.
58
59       -L arg Pass  arg  to  the spooler program.  Several arguments should be
60              passed with a separate -L option each.  Note that groff does not
61              prepend - (a minus sign) to arg before passing it to the spooler
62              program.
63
64       -N     Don't allow newlines within eqn delimiters.  This is the same as
65              the -N option in eqn.
66
67       -p     Preprocess with pic.
68
69       -P -option
70       -P -option -P arg
71              Pass  -option  or  -option arg to the postprocessor.  The option
72              must be specified with the necessary preceding minus sign(s) ‘-’
73              or ‘--’ because groff does not prepend any dashes before passing
74              it to the postprocessor.  For example, to pass a  title  to  the
75              gxditview postprocessor, the shell command
76
77              sh# groff -X -P -title -P 'groff it' foo
78
79              is equivalent to
80
81              sh# groff -X -Z foo | gxditview -title 'groff it' -
82
83       -R     Preprocess with refer.  No mechanism is provided for passing ar‐
84              guments to refer because most refer options have equivalent lan‐
85              guage  elements  that can be specified within the document.  See
86              refer(1) for more details.
87
88       -s     Preprocess with soelim.
89
90       -S     Safer mode.  Pass the -S option to pic and disable the following
91              troff requests: .open, .opena, .pso, .sy, and .pi.  For security
92              reasons, safer mode is enabled by default.
93
94       -t     Preprocess with tbl.
95
96       -T dev Set output device to dev.  The  possible  values  in  groff  are
97              ascii,  cp1047,  dvi, html, latin1, lbp, lj4, ps, utf8, X75, and
98              X100.  Additionally, X75-12 and X100-12 are available for  docu‐
99              ments which use 12pt as the base document size.  The default de‐
100              vice is ps.
101
102       -U     Unsafe mode.  Reverts to the (old) unsafe behaviour; see  option
103              -S.
104
105       -v --version
106              Output version information of groff and of all programs that are
107              run by it; that is, the given command line is parsed in the usu‐
108              al way, passing -v to all subprograms.
109
110       -V     Output  the  pipeline  that  would be run by groff (as a wrapper
111              program), but do not execute it.
112
113       -X     Use gxditview  instead  of  using  the  usual  postprocessor  to
114              (pre)view a document.  The printing spooler behavior as outlined
115              with options -l and -L is carried over to gxditview(1) by deter‐
116              mining an argument for the -printCommand option of gxditview(1).
117              This sets the default Print action and  the  corresponding  menu
118              entry  to  that value.  -X only produces good results with -Tps,
119              -TX75, -TX75-12, -TX100, and -TX100-12.  The default  resolution
120              for  previewing  -Tps  output  is  75dpi; this can be changed by
121              passing the -resolution option to gxditview, for example
122
123              sh# groff -X -P-resolution -P100 -man foo.1
124
125       -z     Suppress output generated by troff.  Only error messages will be
126              printed.
127
128       -Z     Do  not  postprocess the output of troff that is normally called
129              automatically by groff.  This will print the intermediate output
130              to standard output; see groff_out(5).
131
132   Transparent Options
133       The  following  options  are transparently handed over to the formatter
134       program troff that is called by groff subsequently.  These options  are
135       described in more detail in troff(1).
136
137       -a     ascii approximation of output.
138
139       -b     backtrace on error or warning.
140
141       -c     disable color output.
142
143       -C     enable compatibility mode.
144
145       -d cs
146       -d name=s
147              define string.
148
149       -E     disable troff error messages.
150
151       -f fam set default font family.
152
153       -F dir set path for font DESC files.
154
155       -i     process standard input after the specified input files.
156
157       -m name
158              include   macro   file   name.tmac   (or  tmac.name);  see  also
159              groff_tmac(5).
160
161       -M dir path for macro files.
162
163       -n num number the first page num.
164
165       -o list
166              output only pages in list.
167
168       -r cn
169       -r name=n
170              set number register.
171
172       -w name
173              enable warning name.
174
175       -W name
176              disable warning name.
177

USING GROFF

179       The groff system implements the infrastructure of classical  roff;  see
180       roff(7) for a survey on how a roff system works in general.  Due to the
181       front-end programs available within the groff system,  using  groff  is
182       much easier than classical roff.  This section gives an overview of the
183       parts that constitute the groff system.  It  complements  roff(7)  with
184       groff-specific  features.   This  section can be regarded as a guide to
185       the documentation around the groff system.
186
187   Front-ends
188       The groff program is a wrapper around the troff(1) program.  It  allows
189       to  specify the preprocessors by command line options and automatically
190       runs the postprocessor that is appropriate  for  the  selected  device.
191       Doing  so,  the sometimes tedious piping mechanism of classical roff(7)
192       can be avoided.
193
194       The grog(1) program can be used for guessing the correct groff  command
195       line to format a file.
196
197       The  groffer(1)  program  is an allround-viewer for groff files and man
198       pages.
199
200   Preprocessors
201       The groff preprocessors are reimplementations  of  the  classical  pre‐
202       processors  with  moderate  extensions.   The preprocessors distributed
203       with the groff package are
204
205       eqn(1) for mathematical formulæ,
206
207       grn(1) for including gremlin(1) pictures,
208
209       pic(1) for drawing diagrams,
210
211       refer(1)
212              for bibliographic references,
213
214       soelim(1)
215              for including macro files from standard locations,
216
217       and
218
219       tbl(1) for tables.
220
221       Besides these, there are some internal preprocessors that are automati‐
222       cally run with some devices.  These aren't visible to the user.
223
224   Macro Packages
225       Macro  packages  can be included by option -m.  The groff system imple‐
226       ments and extends all classical macro packages in a compatible way  and
227       adds  some packages of its own.  Actually, the following macro packages
228       come with groff:
229
230       man    The traditional man page format; see groff_man(7).   It  can  be
231              specified on the command line as -man or -m man.
232
233       mandoc The  general  package for man pages; it automatically recognizes
234              whether the documents uses  the  man  or  the  mdoc  format  and
235              branches  to  the corresponding macro package.  It can be speci‐
236              fied on the command line as -mandoc or -m mandoc.
237
238       mdoc   The BSD-style man page format; see  groff_mdoc(7).   It  can  be
239              specified on the command line as -mdoc or -m mdoc.
240
241       me     The  classical  me  document format; see groff_me(7).  It can be
242              specified on the command line as -me or -m me.
243
244       mm     The classical mm document format; see groff_mm(7).   It  can  be
245              specified on the command line as -mm or -m mm.
246
247       ms     The  classical  ms  document format; see groff_ms(7).  It can be
248              specified on the command line as -ms or -m ms.
249
250       www    HTML-like macros for inclusion in arbitrary groff documents; see
251              groff_www(7).
252
253       Details  on  the naming of macro files and their placement can be found
254       in groff_tmac(5).
255
256   Programming Language
257       General concepts common to all roff programming languages are described
258       in roff(7).
259
260       The  groff extensions to the classical troff language are documented in
261       groff_diff(7).
262
263       The groff language as a whole is described in  the  (still  incomplete)
264       groff  info  file;  a  short  (but  complete) reference can be found in
265       groff(7).
266
267   Formatters
268       The central roff formatter within the groff  system  is  troff(1).   It
269       provides the features of both the classical troff and nroff, as well as
270       the groff extensions.  The command line option -C switches  troff  into
271       compatibility  mode  which  tries  to emulate classical roff as much as
272       possible.
273
274       There is a shell script nroff(1) that emulates the behavior of  classi‐
275       cal  nroff.   It tries to automatically select the proper output encod‐
276       ing, according to the current locale.
277
278       The formatter program generates intermediate output; see groff_out(7).
279
280   Devices
281       In roff, the output targets are called devices.   A  device  can  be  a
282       piece of hardware, e.g. a printer, or a software file format.  A device
283       is specified by the option -T.  The groff devices are as follows.
284
285       ascii  Text output using the ascii(7) character set.
286
287       cp1047 Text output using the EBCDIC code page IBM cp1047  (e.g.  OS/390
288              Unix).
289
290       nippon Text output using the Japanese-EUC character set.
291
292       dvi    TeX DVI format.
293
294       html   HTML output.
295
296       ascii8 For typewriter-like devices.  Unlike ascii, this device is 8 bit
297              clean.  This device is intended to be used  for  codesets  other
298              than ASCII and ISO-8859-1.
299
300       latin1 Text  output  using  the ISO Latin-1 (ISO 8859-1) character set;
301              see iso_8859_1(7).
302
303       lbp    Output for Canon CAPSL printers (LBP-4 and  LBP-8  series  laser
304              printers).
305
306       lj4    HP LaserJet4-compatible (or other PCL5-compatible) printers.
307
308       ps     PostScript  output;  suitable  for  printers and previewers like
309              gv(1).
310
311       utf8   Text output using the Unicode (ISO  10646)  character  set  with
312              UTF-8 encoding; see unicode(7).
313
314       X75    75dpi  X  Window  System  output  suitable  for  the  previewers
315              xditview(1x) and gxditview(1).  A variant for  a  12pt  document
316              base font is X75-12.
317
318       X100   100dpi  X  Window  System  output  suitable  for  the previewers
319              xditview(1x) and gxditview(1).  A variant for  a  12pt  document
320              base font is X100-12.
321
322       The  postprocessor  to be used for a device is specified by the postpro
323       command in the device description file; see groff_font(5).  This can be
324       overridden with the -X option.
325
326       The default device is ps.
327
328   Postprocessors
329       groff provides 3 hardware postprocessors:
330
331       grolbp(1)
332              for some Canon printers,
333
334       grolj4(1)
335              for printers compatible to the HP LaserJet 4 and PCL5,
336
337       grotty(1)
338              for  text  output using various encodings, e.g. on text-oriented
339              terminals or line-printers.
340
341       Today, most printing or drawing hardware is handled  by  the  operating
342       system, by device drivers, or by software interfaces, usually accepting
343       PostScript.  Consequently, there isn't an urgent need for more hardware
344       device postprocessors.
345
346       The groff software devices for conversion into other document file for‐
347       mats are
348
349       grodvi(1)
350              for the DVI format,
351
352       grohtml(1)
353              for HTML format,
354
355       grops(1)
356              for PostScript.
357
358       Combined with the many existing free conversion tools  this  should  be
359       sufficient to convert a troff document into virtually any existing data
360       format.
361
362   Utilities
363       The following utility programs around groff are available.
364
365       addftinfo(1)
366              Add information to troff font description  files  for  use  with
367              groff.
368
369       afmtodit(1)
370              Create font description files for PostScript device.
371
372       groffer(1)
373              General viewer program for groff files and man pages.
374
375       gxditview(1)
376              The groff X viewer, the GNU version of xditview.
377
378       hpftodit(1)
379              Create font description files for lj4 device.
380
381       indxbib(1)
382              Make inverted index for bibliographic databases.
383
384       lkbib(1)
385              Search bibliographic databases.
386
387       lookbib(1)
388              Interactively search bibliographic databases.
389
390       pfbtops(1)
391              Translate a PostScript font in .pfb format to ASCII.
392
393       tfmtodit(1)
394              Create font description files for TeX DVI device.
395
396       xditview(1x)
397              roff viewer distributed with X window.
398

ENVIRONMENT

400       Normally,  the path separator in the following environment variables is
401       the colon; this may vary depending on the operating system.  For  exam‐
402       ple, DOS and Windows use a semicolon instead.
403
404       GROFF_BIN_PATH
405              This  search  path, followed by $PATH, will be used for commands
406              that are executed by groff.  If it is not set then the directory
407              where the groff binaries were installed is prepended to PATH.
408
409       GROFF_COMMAND_PREFIX
410              When  there  is  a need to run different roff implementations at
411              the same time groff provides the facility to prepend a prefix to
412              most  of  its  programs that could provoke name clashings at run
413              time (default is to have none).  Historically, this  prefix  was
414              the  character  g,  but it can be anything.  For example, gtroff
415              stood for groff's troff, gtbl for the groff version of tbl.   By
416              setting  GROFF_COMMAND_PREFIX to different values, the different
417              roff installations can be addressed.  More exactly, if it is set
418              to  prefix  xxx  then groff as a wrapper program will internally
419              call xxxtroff instead of troff.  This also applies to  the  pre‐
420              processors  eqn, grn, pic, refer, tbl, soelim, and to the utili‐
421              ties indxbib and lookbib.  This feature does not  apply  to  any
422              programs  different  from the ones above (most notably groff it‐
423              self) since they are unique to the groff package.
424
425       GROFF_FONT_PATH
426              A list of directories in which to search for the devname  direc‐
427              tory  in  addition  to  the  default  ones.   See  troff(1)  and
428              groff_font(5) for more details.
429
430       GROFF_TMAC_PATH
431              A list of directories in which to search for macro files in  ad‐
432              dition   to   the   default   directories.    See  troff(1)  and
433              groff_tmac(5) for more details.
434
435       GROFF_TMPDIR
436              The directory in which temporary files will be created.  If this
437              is  not  set but the environment variable TMPDIR instead, tempo‐
438              rary files will be created in the directory $TMPDIR.   Otherwise
439              temporary   files  will  be  created  in  /tmp.   The  refer(1),
440              groffer(1), grohtml(1),  and  grops(1)  commands  use  temporary
441              files.
442
443       GROFF_TYPESETTER
444              Preset  the default device.  If this is not set the ps device is
445              used as default.  This device name is overwritten by the  option
446              -T.
447

FILES

449       There  are  some  directories  in  which groff installs all of its data
450       files.  Due to different installation  habits  on  different  operating
451       systems,  their  locations are not absolutely fixed, but their function
452       is clearly defined and coincides on all systems.
453
454   groff Macro Directory
455       This contains all information related to  macro  packages.   Note  that
456       more  than a single directory is searched for those files as documented
457       in groff_tmac(5).  For the groff  installation  corresponding  to  this
458       document, it is located at /usr/share/groff/1.18.1.4/tmac.  The follow‐
459       ing files contained in the groff macro directory have a  special  mean‐
460       ing:
461
462       troffrc
463              Initialization file for troff.  This is interpreted by troff be‐
464              fore reading the macro sets and any input.
465
466       troffrc-end
467              Final startup file for troff, it is parsed after all macro  sets
468              have been read.
469
470       name.tmac
471       tmac.name
472              Macro file for macro package name.
473
474   groff Font Directory
475       This  contains  all  information  related to output devices.  Note that
476       more than a single directory is searched for those files; see troff(1).
477       For the groff installation corresponding to this document, it is locat‐
478       ed at /usr/share/groff/1.18.1.4/font.  The following files contained in
479       the groff font directory have a special meaning:
480
481       devname/DESC
482              Device description file for device name, see groff_font(5).
483
484       devname/F
485              Font file for font F of device name.
486

EXAMPLES

488       The  following  example illustrates the power of the groff program as a
489       wrapper around troff.
490
491       To process a roff file using the preprocessors tbl and pic and  the  me
492       macro set, classical troff had to be called by
493
494       sh# pic foo.me | tbl | troff -me -Tlatin1 | grotty
495
496       Using groff, this pipe can be shortened to the equivalent command
497
498       sh# groff -p -t -me -T latin1 foo.me
499
500       An  even  easier  way  to call this is to use grog(1) to guess the pre‐
501       processor and macro options and execute the generated command (by spec‐
502       ifying shell left quotes)
503
504       sh# `grog -Tlatin1 foo.me`
505
506       The simplest way is to view the contents in an automated way by calling
507
508       sh# groffer foo.me
509

BUGS

511       On  EBCDIC  hosts  (e.g.  OS/390 Unix), output devices ascii and latin1
512       aren't available.  Similarly, output for EBCDIC code page cp1047 is not
513       available on ASCII based operating systems.
514
515       Report  bugs  to bug-groff@gnu.org.  Include a complete, self-contained
516       example that will allow the bug to be reproduced, and say which version
517       of groff you are using.
518

AVAILABILITY

520       Information on how to get groff and related information is available at
521       the GNU website ⟨http://www.gnu.org/software/groff⟩.  The  most  recent
522       released version of groff is available for anonymous ftp at the groff
523       development site ⟨ftp://ftp.ffii.org/pub/groff/devel/
524       groff-current.tar.gz⟩.
525
526       Three groff mailing lists are available:
527
528       bug-groff@gnu.org
529              for reporting bugs,
530
531       groff@gnu.org
532              for general discussion of groff,
533
534       groff-commit@ffii.org
535              a  read-only list showing logs of commitments to the CVS reposi‐
536              tory.
537
538       Details on CVS access and much more can be found in the file README  at
539       the top directory of the groff source package.
540
541       There is a free implementation of the grap preprocessor, written by Ted
542       Faber ⟨faber@lunabase.org⟩.  The actual version can be found at the
543       grap   website   ⟨http://www.lunabase.org/~faber/Vault/software/grap/⟩.
544       This is the only grap version supported by groff.
545

AUTHORS

547       Copyright © 1989, 2002 Free Software Foundation, Inc.
548
549       This document is distributed under the terms of the FDL (GNU Free Docu‐
550       mentation  License)  version  1.1 or later.  You should have received a
551       copy of the FDL on your system, it is also available on-line at the GNU
552       copyleft site ⟨http://www.gnu.org/copyleft/fdl.html⟩.
553
554       This  document is based on the original groff man page written by James
555       Clark ⟨jjc@jclark.com⟩.  It was rewritten, enhanced, and put under  the
556       FDL  license  by  Bernd  Warken ⟨bwarken@mayn.de⟩.  It is maintained by
557       Werner Lemberg ⟨wl@gnu.org⟩.
558
559       groff is a GNU free software project.  All parts of the  groff  package
560       are  protected  by  GNU copyleft licenses.  The software files are dis‐
561       tributed under the terms of the GNU General Public License (GPL), while
562       the  documentation  files mostly use the GNU Free Documentation License
563       (FDL).
564

SEE ALSO

566       The groff info file contains all information on the groff system within
567       a  single document.  Beneath the detailed documentation of all aspects,
568       it provides examples and background information.  See info(1) on how to
569       read it.
570
571       Due  to  its  complex  structure,  the groff system has many man pages.
572       They can be read with man(1) or groffer(1).
573
574       Introduction, history and further readings:
575              roff(7).
576
577       Viewer for groff files:
578              groffer(1), gxditview(1), xditview(1x).
579
580       Wrapper programs for formatters:
581              groff(1), grog(1).
582
583       Roff preprocessors:
584              eqn(1), grn(1), pic(1), refer(1), soelim(1), tbl(1), grap(1).
585
586       Roff language with the groff extensions:
587              groff(7), groff_char(7), groff_diff(7), groff_font(5).
588
589       Roff formatter programs:
590              nroff(1), troff(1), ditroff(7).
591
592       The intermediate output language:
593              groff_out(7).
594
595       Postprocessors for the output devices:
596              grodvi(1),   grohtml(1),   grolbp(1),    grolj4(1),    grops(1),
597              grotty(1).
598
599       Groff macro packages and macro-specific utilities:
600              groff_tmac(5),    groff_man(7),    groff_mdoc(7),   groff_me(7),
601              groff_mm(7),    groff_mmse(7),    groff_mom(7),     groff_ms(7),
602              groff_www(7), mmroff(7).
603
604       The following utilities are available:
605              addftinfo(1),     afmtodit(1),     eqn2graph(1),     groffer(1),
606              gxditview(1), hpftodit(1), indxbib(1),  lookbib(1),  pfbtops(1),
607              pic2graph(1), tfmtodit(1).
608
609
610
611Groff Version 1.18.1.4          25 January 2008                       GROFF(1)
Impressum