1GROFF(1) General Commands Manual GROFF(1)
2
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 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 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 Native groff Options
38 The following options either do not exist for troff or are differently
39 interpreted by groff.
40 -e Preprocess with eqn.
42 -g Preprocess with grn.
44 -G Preprocess with grap.
46 -h --help
48 Print a help message.
49 -I dir Add search directory for soelim(1). This option implies the -s
51 option.
52 -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 -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 -N Don't allow newlines within eqn delimiters. This is the same as
65 the -N option in eqn.
66 -p Preprocess with pic.
68 -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 sh# groff -X -P -title -P 'groff it' foo
78 is equivalent to
80 sh# groff -X -Z foo | gxditview -title 'groff it' -
82 -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 -s Preprocess with soelim.
89 -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 -t Preprocess with tbl.
95 -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 -U Unsafe mode. Reverts to the (old) unsafe behaviour; see option
103 -S.
104 -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 -V Output the pipeline that would be run by groff (as a wrapper
111 program), but do not execute it.
112 -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 sh# groff -X -P-resolution -P100 -man foo.1
124 -z Suppress output generated by troff. Only error messages will be
126 printed.
127 -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 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 -a ascii approximation of output.
138 -b backtrace on error or warning.
140 -c disable color output.
142 -C enable compatibility mode.
144 -d cs
146 -d name=s
147 define string.
148 -E disable troff error messages.
150 -f fam set default font family.
152 -F dir set path for font DESC files.
154 -i process standard input after the specified input files.
156 -m name
158 include macro file name.tmac (or tmac.name); see also
159 groff_tmac(5).
160 -M dir path for macro files.
162 -n num number the first page num.
164 -o list
166 output only pages in list.
167 -r cn
169 -r name=n
170 set number register.
171 -w name
173 enable warning name.
174 -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 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 The grog(1) program can be used for guessing the correct groff command
195 line to format a file.
196 The groffer(1) program is an allround-viewer for groff files and man
198 pages.
199 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 eqn(1) for mathematical formulæ,
206 grn(1) for including gremlin(1) pictures,
208 pic(1) for drawing diagrams,
210 refer(1)
212 for bibliographic references,
213 soelim(1)
215 for including macro files from standard locations,
216 and
218 tbl(1) for tables.
220 Besides these, there are some internal preprocessors that are automati‐
222 cally run with some devices. These aren't visible to the user.
223 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 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 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 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 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 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 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 www HTML-like macros for inclusion in arbitrary groff documents; see
251 groff_www(7).
252 Details on the naming of macro files and their placement can be found
254 in groff_tmac(5).
255 Programming Language
257 General concepts common to all roff programming languages are described
258 in roff(7).
259 The groff extensions to the classical troff language are documented in
261 groff_diff(7).
262 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 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 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 The formatter program generates intermediate output; see groff_out(7).
279 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 ascii Text output using the ascii(7) character set.
286 cp1047 Text output using the EBCDIC code page IBM cp1047 (e.g. OS/390
288 Unix).
289 nippon Text output using the Japanese-EUC character set.
291 dvi TeX DVI format.
293 html HTML output.
295 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 latin1 Text output using the ISO Latin-1 (ISO 8859-1) character set;
301 see iso_8859_1(7).
302 lbp Output for Canon CAPSL printers (LBP-4 and LBP-8 series laser
304 printers).
305 lj4 HP LaserJet4-compatible (or other PCL5-compatible) printers.
307 ps PostScript output; suitable for printers and previewers like
309 gv(1).
310 utf8 Text output using the Unicode (ISO 10646) character set with
312 UTF-8 encoding; see unicode(7).
313 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 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 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 The default device is ps.
327 Postprocessors
329 groff provides 3 hardware postprocessors:
330 grolbp(1)
332 for some Canon printers,
333 grolj4(1)
335 for printers compatible to the HP LaserJet 4 and PCL5,
336 grotty(1)
338 for text output using various encodings, e.g. on text-oriented
339 terminals or line-printers.
340 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 The groff software devices for conversion into other document file for‐
347 mats are
348 grodvi(1)
350 for the DVI format,
351 grohtml(1)
353 for HTML format,
354 grops(1)
356 for PostScript.
357 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 Utilities
363 The following utility programs around groff are available.
364 addftinfo(1)
366 Add information to troff font description files for use with
367 groff.
368 afmtodit(1)
370 Create font description files for PostScript device.
371 groffer(1)
373 General viewer program for groff files and man pages.
374 gxditview(1)
376 The groff X viewer, the GNU version of xditview.
377 hpftodit(1)
379 Create font description files for lj4 device.
380 indxbib(1)
382 Make inverted index for bibliographic databases.
383 lkbib(1)
385 Search bibliographic databases.
386 lookbib(1)
388 Interactively search bibliographic databases.
389 pfbtops(1)
391 Translate a PostScript font in .pfb format to ASCII.
392 tfmtodit(1)
394 Create font description files for TeX DVI device.
395 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 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 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 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 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 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 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 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 troffrc
463 Initialization file for troff. This is interpreted by troff be‐
464 fore reading the macro sets and any input.
465 troffrc-end
467 Final startup file for troff, it is parsed after all macro sets
468 have been read.
469 name.tmac
471 tmac.name
472 Macro file for macro package name.
473 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 devname/DESC
482 Device description file for device name, see groff_font(5).
483 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 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 sh# pic foo.me | tbl | troff -me -Tlatin1 | grotty
495 Using groff, this pipe can be shortened to the equivalent command
497 sh# groff -p -t -me -T latin1 foo.me
499 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 sh# `grog -Tlatin1 foo.me`
505 The simplest way is to view the contents in an automated way by calling
507 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 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 Three groff mailing lists are available:
527 bug-groff@gnu.org
529 for reporting bugs,
530 groff@gnu.org
532 for general discussion of groff,
533 groff-commit@ffii.org
535 a read-only list showing logs of commitments to the CVS reposi‐
536 tory.
537 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 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 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 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 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 Due to its complex structure, the groff system has many man pages.
572 They can be read with man(1) or groffer(1).
573 Introduction, history and further readings:
575 roff(7).
576 Viewer for groff files:
578 groffer(1), gxditview(1), xditview(1x).
579 Wrapper programs for formatters:
581 groff(1), grog(1).
582 Roff preprocessors:
584 eqn(1), grn(1), pic(1), refer(1), soelim(1), tbl(1), grap(1).
585 Roff language with the groff extensions:
587 groff(7), groff_char(7), groff_diff(7), groff_font(5).
588 Roff formatter programs:
590 nroff(1), troff(1), ditroff(7).
591 The intermediate output language:
593 groff_out(7).
594 Postprocessors for the output devices:
596 grodvi(1), grohtml(1), grolbp(1), grolj4(1), grops(1),
597 grotty(1).
598 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 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).
608Groff Version 1.18.1.4 25 January 2008 GROFF(1)