- Render a man page as plain text, and display the result:groff -man -T utf8 [manpage.1]- Render a man page using the ASCII output device, and display it using a pager:groff -man -T ascii [manpage.1] | less- Render a man page into an HTML file:groff -man -T html [manpage.1] > [page.html]- Process a roff file using the `tbl` and `pic` preprocessors, and the `me` macro set:groff -t -p -me -T utf8 [foo.me]- Run a `groff` command with preprocessor and macro options guessed by the `grog` utility:eval "$(grog -T utf8 [foo.me])"
[ -abcegijklpstzCEGNRSUVXZ ] [ -d cs ] [ -D arg ] [ -f fam ] [ -F dir ] [ -I dir ] [ -K arg ] [ -L arg ] [ -m name ] [ -M dir ] [ -n num ] [ -o list ] [ -P arg ] [ -r cn ] [ -T dev ] [ -w name ] [ -W name ] [file~...] -h | --help -v | --version [option~...]
This document describes the groff program, the main front-end for the groff document formatting system. The groff program and macro suite is the implementation of a roff(7) system within the free software collection GNU The groff system has all features of the classical roff, but adds many extensions.
The groff program allows to control the whole groff system by command line options. This is a great simplification in comparison to the classical case (which uses pipes only).
The command line is parsed according to the usual GNU convention. The whitespace between a command line option and its argument is optional. Options can be grouped behind a single '-' (minus character). A filename of - (minus character) denotes the standard input.
As groff is a wrapper program for troff both programs share a set of options. But the groff program has some additional, native options and gives a new meaning to some troff options. On the other hand, not all troff options can be fed into groff.
The groff system implements the infrastructure of classical roff; see roff(7) for a survey on how a roff system works in general. Due to the front-end programs available within the groff system, using groff is much easier than classical roff. This section gives an overview of the parts that constitute the groff system. It complements roff(7) with groff-specific features. This section can be regarded as a guide to the documentation around the groff system.
The physical paper size, giving the actual dimensions of the paper sheets, is controlled by output devices like grops with the command line options -p and -l. See groff_font(5) and the man pages of the output devices for more details. groff uses the command line option -P to pass options to output devices; for example, the following selects A4 paper in landscape orientation for the PS device:
The grog(1) program can be used for guessing the correct groff command line to format a file.
The groffer(1) program is an allround-viewer for groff files and man pages.
A new preprocessor not available in classical troff is preconv(1) which converts various input encodings to something groff can understand. It is always run first before any other preprocessor.
Besides these, there are some internal preprocessors that are automatically run with some devices. These aren't visible to the user.
Details on the naming of macro files and their placement can be found in groff_tmac(5); this man page also documents some other, minor auxiliary macro packages not mentioned here.
The groff extensions to the classical troff language are documented in groff_diff(7).
The groff language as a whole is described in the (still incomplete) groff info file; a short (but complete) reference can be found in groff(7).
There is a shell script nroff(1) that emulates the behavior of classical nroff. It tries to automatically select the proper output encoding, according to the current locale.
The formatter program generates intermediate output; see groff_out(7).
The postprocessor to be used for a device is specified by the postpro command in the device description file; see groff_font(5). This can be overridden with the -X option.
The default device is ps.
Today, most printing or drawing hardware is handled by the operating system, by device drivers, or by software interfaces, usually accepting PostScript. Consequently, there isn't an urgent need for more hardware device postprocessors.
The groff software devices for conversion into other document file formats are
Combined with the many existing free conversion tools this should be sufficient to convert a troff document into virtually any existing data format.
Normally, the path separator in the following environment variables is the colon; this may vary depending on the operating system. For example, DOS and Windows use a semicolon instead.
The following example illustrates the power of the groff program as a wrapper around troff.
To process a roff file using the preprocessors tbl and pic and the me macro set, classical troff had to be called by
Using groff, this pipe can be shortened to the equivalent command
An even easier way to call this is to use grog(1) to guess the preprocessor and macro options and execute the generated command (by using backquotes to specify shell command substitution)
The simplest way is to view the contents in an automated way by calling
On EBCDIC hosts (e.g., OS/390 Unix), output devices ascii and latin1 aren't available. Similarly, output for EBCDIC code page cp1047 is not available on ASCII based operating systems.
Report bugs to the groff mailing list Include a complete, self-contained example that allows the bug to be reproduced, and say which version of groff you are using.
There are some directories in which groff installs all of its data files. Due to different installation habits on different operating systems, their locations are not absolutely fixed, but their function is clearly defined and coincides on all systems.
Information on how to get groff and related information is available at the groff GNU website
Three groff mailing lists are available:
Details on repository access and much more can be found in the file README at the top directory of the groff source package.
There is a free implementation of the grap preprocessor, written by Ted Faber The actual version can be found at the grap website This is the only grap version supported by groff.
The groff info file contains all information on the groff system within a single document, providing many examples and background information. See info(1) on how to read it.
Due to its complex structure, the groff system has many man pages. They can be read with man(1) or groffer(1).
But there are special sections of man-pages. groff has man-pages in sections 1, 5,and 7. When there are several man-pages with the same name in the same man section, the one with the lowest section is should as first. The other man-pages can be shown anyway by adding the section number as argument before the man-page name. Reading the man-page about the groff language is done by one of
man 7 groff groffer 7 groff
Copyright © 1989-2014 Free Software Foundation, Inc.
Rewritten in 2002 by Bernd Warken <email@example.com>
This document is part of groff, a free GNU software project.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with the Invariant Sections being the macro definition or .co and .au, with no Front-Cover Texts, and with no Back-Cover Texts.
A copy of the Free Documentation License is included as a file called FDL in the main directory of the groff source package.
It is also available in the internet at the GNU copyleft site
This document is based on the original groff man page written by James Clark It was rewritten, enhanced, and put under the FDL license by Bernd Warken <firstname.lastname@example.org>. It is maintained by Werner Lemberg