• NAME
  
  groff - front-end for the groff document formatting system . .
• SYNOPSIS
  
  . [ file . | . | [ option . 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. . .
• DESCRIPTION
  
  . 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 . 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). . .
• OPTIONS
  
  . 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 . . . Native groff Options . The following options either do not exist for troff or are differently interpreted by groff . . . Preprocess with eqn . . . Preprocess with grn . . . Preprocess with grap . . . Print a help message. . . Add search directory for %soelim(1) . This option implies the option. . . 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 %groff_font(5) . If this command is not present, the output is piped into the lpr(1) program by default. . See options and . . Pass arg to the spooler program. Several arguments should be passed with a separate option each. . Note that groff does not prepend (a minus sign) to arg before passing it to the spooler program. . . Don't allow newlines within eqn delimiters. . This is the same as the option in eqn . . . Preprocess with pic . . . Pass -option or -option arg to the postprocessor. . The option must be specified with the necessary preceding minus sign(s) or 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 is equivalent to . . Preprocess with 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 %refer(1) for more details. . . Preprocess with soelim . . . Safer mode. . Pass the option to pic and disable the following troff requests: .open , .opena , .pso , .sy , and .pi . For security reasons, safer mode is enabled by default. . . Preprocess with tbl . . . Set output device to dev . The possible values in groff are ascii , cp1047 , dvi , html , latin1 , lbp , lj4 , ps , utf8 , X75 , and X100 . . Additionally, X75-12 and X100-12 are available for documents which use 12pt as the base document size. . The default device is ps . . . Unsafe mode. . Reverts to the (old) unsafe behaviour; see option . . 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 to all subprograms. . . Output the pipeline that would be run by groff (as a wrapper program), but do not execute it. . . Use gxditview instead of using the usual postprocessor to (pre)view a document. . The printing spooler behavior as outlined with options and is carried over to %gxditview(1) by determining an argument for the -printCommand option of %gxditview(1) . . This sets the default Print action and the corresponding menu entry to that value. . only produces good results with and . The default resolution for previewing output is 75dpi; this can be changed by passing the option to gxditview , for example . . . Suppress output generated by troff . Only error messages will be printed. . . Do not postprocess the output of troff that is normally called automatically by groff . This will print the intermediate output to standard output; see %groff_out(5) . . . Transparent Options . 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 troff(1) . . ascii approximation of output. . backtrace on error or warning. . disable color output. . enable compatibility mode. . define string. . disable troff error messages. . set default font family. . set path for font DESC files. . process standard input after the specified input files. . include macro file <[>I]name<[>]<[>B].tmac<[>] (or <[>B]tmac.<[>]<[>I]name<[>]); see also %groff_tmac(5) . . path for macro files. . number the first page num . . output only pages in list . . set number register. . enable warning name . . disable warning name . . .
• USING 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. . . Front-ends . The groff program is a wrapper around the 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 roff(7) can be avoided. . 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. . . Preprocessors . The groff preprocessors are reimplementations of the classical preprocessors with moderate extensions. . The preprocessors distributed with the groff package are .

  eqn(1)

  for mathematical formul(ae,

  grn(1)

  for including gremlin(1) pictures,

  pic(1)

  for drawing diagrams,

  %refer(1)

  for bibliographic references,

  %soelim(1)

  for including macro files from standard locations, . and

  tbl(1)

  for tables. . Besides these, there are some internal preprocessors that are automatically run with some devices. . These aren't visible to the user. . .

  "Macro Packages" . Macro packages can be included by option . The groff system 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 %groff_man(7) . It can be specified on the command line as or man . .

  mandoc

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

  mdoc

  The BSD-style man page format; see %groff_mdoc(7) . It can be specified on the command line as or mdoc . .

  me

  The classical me document format; see %groff_me(7) . It can be specified on the command line as or me . .

  mm

  The classical mm document format; see %groff_mm(7) . It can be specified on the command line as or mm . .

  ms

  The classical ms document format; see %groff_ms(7) . It can be specified on the command line as or ms . .

  www

  HTML-like macros for inclusion in arbitrary groff documents; see %groff_www(7) . . Details on the naming of macro files and their placement can be found in %groff_tmac(5) . . .

  "Programming Language" . General concepts common to all roff programming languages are described in roff(7) . . 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) . . . Formatters . The central roff formatter within the groff system is troff(1) . It provides the features of both the classical troff and nroff, as well as the groff extensions. . The command line option switches troff into "compatibility mode" which tries to emulate classical roff as much as possible. . 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) . . . Devices . 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 The groff devices are as follows. .

  ascii

  Text output using the ascii(7) character set. .

  cp1047

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

  nippon

  Text output using the Japanese-EUC character set. .

  dvi

  TeX DVI format. .

  html

  HTML output. .

  ascii8

  For typewriter-like devices.  Unlike ascii , this device is 8 bit clean.  This device is intended to be used for codesets other than ASCII and ISO-8859-1.

  latin1

  Text output using the ISO Latin-1 (ISO 8859-1) character set; see 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 gv(1) . .

  utf8

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

  X75

  75dpi X Window System output suitable for the previewers xditview (1x) and %gxditview(1) . A variant for a 12pt document base font is X75-12 . .

  X100

  100dpi X Window System output suitable for the previewers xditview (1x) and %gxditview(1) . A variant for a 12pt document base font is X100-12 . . 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 . . .

  Postprocessors . groff provides 3~hardware postprocessors: .

  %grolbp(1)

  for some Canon printers,

  %grolj4(1)

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

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

  %grodvi(1)

  for the DVI format,

  %grohtml(1)

  for HTML format,

  grops(1)

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

  Utilities . The following utility programs around groff are available. .

  %addftinfo(1)

  Add information to troff font description files for use with groff. .

  %afmtodit(1)

  Create font description files for PostScript device. .

  %groffer(1)

  General viewer program for groff files and man pages. .

  %gxditview(1)

  The groff X viewer, the GNU version of xditview. .

  %hpftodit(1)

  Create font description files for lj4 device. .

  %indxbib(1)

  Make inverted index for bibliographic databases. .

  lkbib(1)

  Search bibliographic databases. .

  %lookbib(1)

  Interactively search bibliographic databases. .

  %pfbtops(1)

  Translate a PostScript font in .pfb format to ASCII. .

  %tfmtodit(1)

  Create font description files for TeX DVI device. .

  %xditview (1x)

  roff viewer distributed with X window. . .

• ENVIRONMENT
  
  . 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. .

  This search path, followed by

  will be used for commands that are executed by groff . . If it is not set then the directory where the groff binaries were installed is prepended to .

  When there is a need to run different roff implementations at the same

  time groff provides the facility to prepend a prefix to most of its programs that could provoke name clashings at run time (default is to have none). . Historically, this prefix was the character g , but it can be anything. . For example, gtroff stood for groff 's troff , gtbl for the groff version of tbl . . By setting to different values, the different roff installations can be addressed. . More exactly, if it is set to prefix xxx then groff as a wrapper program will internally call instead of troff . This also applies to the preprocessors %eqn , %grn , %pic , %refer , %tbl , %soelim , and to the utilities %indxbib and %lookbib . . This feature does not apply to any programs different from the ones above (most notably groff itself) since they are unique to the groff package. . .

  A list of directories in which to search for the

  dev name directory in addition to the default ones. . See troff(1) and %groff_font(5) for more details. . .

  A list of directories in which to search for macro files in addition to

  the default directories. . See troff(1) and %groff_tmac(5) for more details. . .

  The directory in which temporary files will be created.

  . If this is not set but the environment variable instead, temporary files will be created in the directory . Otherwise temporary files will be created in /tmp . The %refer(1) , %groffer(1) , %grohtml(1) , and grops(1) commands use temporary files. . .

  Preset the default device.

  . If this is not set the ps device is used as default. . This device name is overwritten by the option . .

• FILES
  
  . 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. . . "groff Macro Directory" . This contains all information related to macro packages. . Note that more than a single directory is searched for those files as documented in %groff_tmac(5) . . For the groff installation corresponding to this document, it is located at /usr/share/groff/1.18.1.4/tmac . . The following files contained in the groff macro directory have 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. . .

  tmac. name

  Macro file for macro package name . . .

  "groff Font Directory" . This contains all information related to output devices. . Note that more than a single directory is searched for those files; see troff(1) . . For the groff installation corresponding to this document, it is located at /usr/share/groff/1.18.1.4/font . . The following files contained in the groff font directory have a special meaning: . .

  dev name /DESC

  Device description file for device name , see %groff_font(5) . . .

  dev name / F

  Font file for font F of device name . . .

• EXAMPLES
  
  . 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 specifying shell left quotes) . The simplest way is to view the contents in an automated way by calling . . .
• BUGS
  
  . 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 bug-groff@gnu.org. . Include a complete, self-contained example that will allow the bug to be reproduced, and say which version of groff you are using. . .
• AVAILABILITY
  
  . Information on how to get groff and related information is available at the The most recent released version of groff is available for anonymous ftp at the      "groff development site" . . Three groff mailing lists are available:

  for reporting bugs,

  .

  for general discussion of groff,

  .

  a read-only list showing logs of commitments to the CVS repository.

  . Details on CVS 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 . The actual version can be found at the .      "grap website" . This is the only grap version supported by groff. . .

• AUTHORS
  
  . Copyright © 1989, 2002 Free Software Foundation, Inc. . This document is distributed under the terms of the FDL (GNU Free Documentation License) version 1.1 or later. . You should have received a copy of the FDL on your system, it is also available on-line at the . This document is based on the original groff man page written by . It was rewritten, enhanced, and put under the FDL license by . It is maintained by . groff is a GNU free software project. . All parts of the groff package are protected by GNU copyleft licenses. . The software files are distributed under the terms of the GNU General Public License (GPL), while the documentation files mostly use the GNU Free Documentation License (FDL). . .
• SEE ALSO
  
  . The "groff info file" contains all information on the groff system within a single document. . Beneath the detailed documentation of all aspects, it provides 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) . .

  Introduction, history and further readings:

  roff(7) . .

  Viewer for groff files:

  %groffer(1) , %gxditview(1) , %xditview (1x). .

  Wrapper programs for formatters:

  %groff(1) , %grog(1) . .

  Roff preprocessors:

  %eqn(1) , %grn(1) , %pic(1) , %refer(1) , %soelim(1) , %tbl(1) , grap(1) . .

  Roff language with the groff extensions:

  %groff(7) , %groff_char(7) , %groff_diff(7) , %groff_font(5) . .

  Roff formatter programs:

  %nroff(1) , %troff(1) , ditroff(7) . .

  The intermediate output language:

  %groff_out(7) . .

  Postprocessors for the output devices:

  %grodvi(1) , %grohtml(1) , %grolbp(1) , %grolj4(1) , %grops(1) , %grotty(1) . .

  Groff macro packages and macro-specific utilities:

  %groff_tmac(5) , %groff_man(7) , %groff_mdoc(7) , %groff_me(7) , %groff_mm(7) , %groff_mmse(7) , %groff_mom(7) , %groff_ms(7) , %groff_www(7) , %mmroff(7) . .

  The following utilities are available:

  %addftinfo(1) , %afmtodit(1) , %eqn2graph(1) , %groffer(1) , %gxditview(1) , %hpftodit(1) , %indxbib(1) , %lookbib(1) , %pfbtops(1) , %pic2graph(1) , %tfmtodit(1) . . .

  .

Current Users: 41 © 1999-2009 PenguinSoft. All trademarks and copyrights on this page are owned by their respective companies. Linux is a trademark of Linus Torvalds.