1GROFF(1) General Commands Manual GROFF(1)
2
3
4
6 groff - front-end for the groff document formatting system
7
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
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
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
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
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
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
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
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
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
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
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 11 November 2010 GROFF(1)