Man page 1 : groff

. The following options either do not exist for

troff or are differently interpreted by

R groff . . .

• -D  arg
      Set default input encoding used by

preconv to arg . . Implies

R -k . . .

-e

    Preprocess with

R eqn . . .

-g

    Preprocess with

R grn . . .

-G

    Preprocess with

R grap . . .

-h

    

--help Print a help message. . .

• -I  dir
      This option may be used to specify a directory to search for files (both those on the command line and those named in

.psbb and

.so requests, and

\X'ps: import' and

\X'ps: file' escapes). The current directory is always searched first. This option may be specified more than once; the directories are searched in the order specified. No directory search is performed for files specified using an absolute path. This option implies the

-s option. . .

-k

    Preprocess with

R preconv . This is run before any other preprocessor. . Please refer to

R preconv 's manual page for its behaviour if no

-K (or

R -D ) option is specified. . .

• -K  arg
      Set input encoding used by

preconv to arg . . Implies

R -k . . .

-l

    Send the output to a spooler program for printing. . The command that should be used for this is specified by the

print command in the device description file, see

R groff_font (5). If this command is not present, the output is piped into the

R lpr (1) program by default. . See options

-L and

R -X . . .

• -L  arg
      Pass argto the spooler program. Several arguments should be passed with a separate -L option each. . Note that

groff does not prepend `-' (a minus sign) to argbefore passing it to the spooler program. . .

-N

    Don't allow newlines within eqndelimiters. . This is the same as the

-N option in

R eqn . . .

-p

    Preprocess with

R pic . . .

• -P  -option
      
  -P  -option  -P  arg Pass -optionor "-option\~arg"to the postprocessor. . The option must be specified with the necessary preceding minus sign(s) .Quoted - or .Quoted -- because

groff does not prepend any dashes before passing it to the postprocessor. . For example, to pass a title to the

gxditview postprocessor, the shell command .

groff -X -P -title -P 'groff it' \f[I]foo\f[]

.

is equivalent to .

groff -X -Z \f[I]foo\f[] | \
gxditview -title 'groff it' -

. .

-R

    Preprocess with

R refer . . No mechanism is provided for passing arguments to

refer because most

refer options have equivalent language elements that can be specified within the document. . See

R refer (1) for more details. . .

-s

    Preprocess with

R soelim . . .

-S

    Safer mode. . Pass the

-S option to

pic and disable the following

troff requests:

R .open ,

R .opena ,

R .pso ,

R .sy , and

R .pi . For security reasons, safer mode is enabled by default. . .

-t

    Preprocess with

R tbl . . .

• -T  dev
      Set output device to dev . For this device,

troff generates the intermediate output ; see

R groff_out (5). . Then

groff calls a postprocessor to convert

R troff 's intermediate outputto its final format. . Real devices in

groff are .

• dvi
      TeX DVI format (postprocessor is

R grodvi ). .

• html
      
  xhtml HTML and XHTML output (preprocessors are

soelim and

R pre-grohtml , postprocessor is

R post-grohtml ). .

• lbp
      Canon CAPSL printers (LBP-4 and LBP-8 series laser printers; postprocessor is

R grolbp ). .

• lj4
      HP LaserJet4 compatible (or other PCL5 compatible) printers (postprocessor is

R grolj4 ). .

• ps
      PostScript output (postprocessor is

R grops ). . .

For the following TTY output devices (postprocessor is always

R grotty ),

-T selects the output encoding: .

• ascii
      7bit \f[CR]ASCII\f[]. .
• cp1047
      Latin-1 character set for EBCDIC hosts. .
• latin1
      ISO 8859-1. .
• utf8
      Unicode character set in UTF-8 encoding. . .

The following arguments select

gxditview as the `postprocessor' (it is rather a viewing program): .

• X75
      75 dpi resolution, 10 pt document base font.
• X75-12
      75 dpi resolution, 12 pt document base font.
• X100
      100 dpi resolution, 10 pt document base font.
• X100-12
      100 dpi resolution, 12 pt document base font. .

The default device is

R ps . . .

-U

    Unsafe mode. . Reverts to the (old) unsafe behaviour; see option

R -S . . .

-v

    

--version Output version information of

groff and of all programs that are run by it; that is, the given command line is parsed in the usual way, passing

-v to all subprograms. . .

-V

    Output the pipeline that would be run by

R groff (as a wrapper program) on the standard output, but do not execute it. If given more than once, the commands are both printed on the standard error and run. . .

-X

    Use

gxditview instead of using the usual postprocessor to (pre)view a document. . The printing spooler behavior as outlined with options

-l and

-L is carried over to

R gxditview (1) by determining an argument for the

-printCommand option of

R gxditview (1). . This sets the default

Print action and the corresponding menu entry to that value. .

-X only produces good results with

R -Tps ,

R -TX75 ,

R -TX75-12 ,

R -TX100 , and

R -TX100-12 . . The default resolution for previewing

-Tps output is 75 dpi; this can be changed by passing the

-resolution option to

R gxditview , for example .

groff -X -P-resolution -P100 -man foo.1

. .

-z

    Suppress output generated by

R troff . Only error messages are printed. . .

-Z

    Do not automatically postprocess groff intermediate outputin the usual manner. This will cause the

troff outputto appear on standard output, replacing the usual postprocessor output; see

R groff_out (5). . .

. The following options are transparently handed over to the formatter program

troff that is called by

groff subsequently. . These options are described in more detail in

R troff (1). .

-a

    \f[CR]ASCII\f[] approximation of output. .

-b

    Backtrace on error or warning. .

-c

    Disable color output. . Please consult the

R grotty (1) man page for more details. .

-C

    Enable compatibility mode. .

• -d  cs
      
  -d  name = s Define string. .

-E

    Disable

troff error messages. .

• -f  fam
      Set default font family. .
• -F  dir
      Set path for font DESC files. .

-i

    Process standard input after the specified input files. .

• -m  name
      Include macro file .IB name .tmac (or tmac. name\c ); see also

R groff_tmac (5). .

• -M  dir
      Path for macro files. .
• -n  num
      Number the first page num . .
• -o  list
      Output only pages in list . .
• -r  cn
      
  -r  name = n Set number register. .
• -w  name
      Enable warning name . .
• -W  name
      disable warning name . . .

. The virtualpaper size used by

troff to format the input is controlled globally with the requests

R .po ,

R .pl , and

R .ll . See

R groff_tmac (5) for the `papersize' macro package which provides a convenient interface. .

The physicalpaper size, giving the actual dimensions of the paper sheets, is controlled by output devices like

R grops with the command line options

-p and

R -l . See

R 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: .

groff -Tps -P-pa4 -P-l ...

. .

. The

groff program is a wrapper around the

R troff (1) program. . It allows to specify the preprocessors by command line options and automatically runs the postprocessor that is appropriate for the selected device. . Doing so, the sometimes tedious piping mechanism of classical

R roff (7) can be avoided. .

The

R grog (1) program can be used for guessing the correct groffcommand line to format a file. .

The

R groffer (1) program is an allround-viewer for grofffiles and man pages. . .

. The groffpreprocessors are reimplementations of the classical preprocessors with moderate extensions. . The standard preprocessors distributed with the groffpackage are .

R eqn (1)

    for mathematical formul(ae, .

R grn (1)

    for including

R gremlin (1) pictures, .

R pic (1)

    for drawing diagrams, .

R chem (1)

    for chemical structure diagrams, .

R refer (1)

    for bibliographic references, .

R soelim (1)

    for including macro files from standard locations, .

and .

R tbl (1)

    for tables. .

A new preprocessor not available in classical troffis

R 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. . .

. Macro packages can be included by option

R -m . . The groffsystem implements and extends all classical macro packages in a compatible way and adds some packages of its own. . Actually, the following macro packages come with groff : .

man

    The traditional man page format; see

R groff_man (7). It can be specified on the command line as

-man or

R -m\~man . .

mandoc

    The general package for man pages; it automatically recognizes whether the documents uses the manor the mdocformat and branches to the corresponding macro package. . It can be specified on the command line as

-mandoc or

R -m\~mandoc . .

mdoc

    The \f[CR]BSD\f[]-style man page format; see

R groff_mdoc (7). It can be specified on the command line as

-mdoc or

R -m\~mdoc . .

me

    The classical medocument format; see

R groff_me (7). It can be specified on the command line as

-me or

R -m\~me . .

mm

    The classical mmdocument format; see

R groff_mm (7). It can be specified on the command line as

-mm or

R -m\~mm . .

ms

    The classical msdocument format; see

R groff_ms (7). It can be specified on the command line as

-ms or

R -m\~ms . .

www

    HTML-like macros for inclusion in arbitrary groffdocuments; see

R groff_www (7). .

Details on the naming of macro files and their placement can be found in

R groff_tmac (5); this man page also documents some other, minor auxiliary macro packages not mentioned here. . .

. General concepts common to all roffprogramming languages are described in

R roff (7). .

The groffextensions to the classical trofflanguage are documented in

R groff_diff (7). .

The grofflanguage as a whole is described in the (still incomplete) "groff info file" ; a short (but complete) reference can be found in

R groff (7). . .

. The central roffformatter within the groffsystem is

R troff (1). It provides the features of both the classical troffand nroff , as well as the groffextensions. . The command line option

-C switches

troff into "compatibility mode"which tries to emulate classical roffas much as possible. .

There is a shell script

R nroff (1) that emulates the behavior of classical

R nroff . . It tries to automatically select the proper output encoding, according to the current locale. .

The formatter program generates "intermediate output" ; see

R groff_out (7). . .

. In roff , the output targets are called devices . A device can be a piece of hardware, e.g., a printer, or a software file format. . A device is specified by the option

R -T . The groffdevices are as follows. .

ascii

    Text output using the

R ascii (7) character set. .

cp1047

    Text output using the EBCDIC code page IBM cp1047 (e.g., OS/390 Unix). .

dvi

    TeX DVI format. .

html

    HTML output. .

latin1

    Text output using the ISO Latin-1 (ISO 8859-1) character set; see

R iso_8859_1 (7). .

lbp

    Output for Canon CAPSL printers (LBP-4 and LBP-8 series laser printers). .

lj4

    HP LaserJet4-compatible (or other PCL5-compatible) printers. .

ps

    PostScript output; suitable for printers and previewers like

R gv (1). .

utf8

    Text output using the Unicode (ISO 10646) character set with UTF-8 encoding; see

R unicode (7). .

xhtml

    XHTML output. .

X75

    75dpi X Window System output suitable for the previewers

R xditview (1x) and

R gxditview (1). . A variant for a 12 pt document base font is

R X75-12 . .

X100

    100dpi X Window System output suitable for the previewers

R xditview (1x) and

R gxditview (1). . A variant for a 12 pt document base font is

R X100-12 . .

The postprocessor to be used for a device is specified by the

postpro command in the device description file; see

R groff_font (5). . This can be overridden with the

-X option. .

The default device is

R ps . . .

. groffprovides 3\~hardware postprocessors: .

R grolbp (1)

    for some Canon printers, .

R grolj4 (1)

    for printers compatible to the HP LaserJet\~4 and PCL5, .

R grotty (1)

    for text output using various encodings, e.g., on text-oriented terminals or line-printers. .

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 groffsoftware devices for conversion into other document file formats are .

R grodvi (1)

    for the DVI format, .

R grohtml (1)

    for HTML and XHTML formats, .

R grops (1)

    for PostScript. .

Combined with the many existing free conversion tools this should be sufficient to convert a troffdocument into virtually any existing data format. . .

. The following utility programs around groffare available. .

R addftinfo (1)

    Add information to trofffont description files for use with groff . .

R afmtodit (1)

    Create font description files for PostScript device. .

R eqn2graph (1)

    Convert an

eqn image into a cropped image. .

R gdiffmk (1)

    Mark differences between groff , nroff , or trofffiles. .

R grap2graph (1)

    Convert a

grap diagram into a cropped bitmap image. .

R groffer (1)

    General viewer program for grofffiles and man pages. .

R gxditview (1)

    The groffX viewer, the \f[CR]GNU\f[] version of

R xditview . .

R hpftodit (1)

    Create font description files for lj4 device. .

R indxbib (1)

    Make inverted index for bibliographic databases. .

R lkbib (1)

    Search bibliographic databases. .

R lookbib (1)

    Interactively search bibliographic databases. .

R pdfroff (1)

    Create PDF documents using

R groff . .

R pfbtops (1)

    Translate a PostScript font in .pfb format to \f[CR]ASCII\f[]. .

R pic2graph (1)

    Convert a

pic diagram into a cropped image. .

R tfmtodit (1)

    Create font description files for TeX DVI device. .

R xditview (1x)

    .I roff viewer distributed with X window. .

R xtotroff (1)

    Convert X font metrics into \f[CR]GNU\f[] trofffont metrics. . .

. This contains all information related to macro packages. . Note that more than a single directory is searched for those files as documented in

R groff_tmac (5). . For the groffinstallation corresponding to this document, it is located at /usr/share/groff/1.20.1/tmac . . The following files contained in the groff macro directoryhave a special meaning: . .

troffrc

    Initialization file for troff . . This is interpreted by

troff before reading the macro sets and any input. . .

troffrc-end

    Final startup file for troff . . It is parsed after all macro sets have been read. . .

• .IB name .tmac
      
  tmac. name Macro file for macro package name . . .

. This contains all information related to output devices. . Note that more than a single directory is searched for those files; see

R troff (1). . For the groffinstallation corresponding to this document, it is located at /usr/share/groff/1.20.1/font . . The following files contained in the "groff font directory"have a special meaning: . .

• dev name /DESC
      Device description file for device name , see

R groff_font (5). . .

• dev name / F
      Font file for font Fof device name . . .