*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->NetBSD man pages -> roff (7)              
Title
Content
Arch
Section
 

ROFF(7)

Contents


NAME    [Toc]    [Back]

       roff - a survey of the roff typesetting system

DESCRIPTION    [Toc]    [Back]

       roff  is  the  general name for a set of type-setting programs,
 known under names like troff, nroff, groff, etc.

       The roff type-setting system consists of a formatting language,
  macro  packages, preprocessors, postprocessors for
       output devices, user front-end  programs,  and  conversion
       tools.

       The  most  common  roff  system today is the free software
       implementation groff  (from  `GNU roff').   The  pre-groff
       implementations  are  referred  to  as `classical' (dating
       back as long as 1973).

       groff is backward-compatible to its  classical  ancestors,
       but  has many extensions, and is still evolving.  As it is
       available for almost every computer system it is  the  defacto
 roff standard today.

       In  spite of its age, roff is in wide use today, e.g., the
       manual pages on UNIX systems (man-pages)  are  written  in
       roff.    The   roff  output  for  text  devices  is  still
       unmatched, and its graphical output has the  same  quality
       as the other free type-setting programs and is better than
       some of the commercial systems.

       This document gives only an overview and provides pointers
       to further documentation.

       This  document is not maintained and might be out of date.
       For the real documentation refer to the  groff  info  file
       that  contains  the detailed, actual and concise reference
       information.

FORMATTING LANGUAGE    [Toc]    [Back]

       There are three terms that refer to the  language  of  the
       roff  system.   The  term  troff language is used when the
       classical aspects of roff are  stressed,  the  term  groff
       language  includes  the  GNU extensions, whereas roff lan-
       guage is the general term.

       The main source of documentation for all  aspects  of  the
       groff  language  is  the groff info file.  The manual page
       groff(7) gives a short description of all predefined  language
 elements.

       Documents  using  roff  are normal text files decorated by
       formatting elements.  It is very easy to write  high-quality
  documents  by using one of the macro packages.  These
       are like high-level programming languages, while the  bare
       roff  language  compares to a low-level language like C or
       assembler.

       The roff language is a full programming language providing
       low-level   requests,   definition   of   macros,   escape
       sequences, string variables, number or size registers, and
       C-like flow controls.

       Some  clarification  on  the language elements seems to be
       wanted.  Requests are basic formatting commands defined by
       programming  languages  like  C, C++, etc., whereas macros
       are formatting commands that are written in the roff  language.
   A document writer will not note any difference in
       usage for requests or macros, both are written on  a  line
       on  their  own  starting  with a dot `.'. But the user may
       define her own macros if desired.

       Escape sequences are  in-line  elements  starting  with  a
       backslash  `\'.  They  are  used to implement various features,
 including the  insertion  of  non-ASCII  characters
       with \(, the content of strings with \* and register variables
 with \n, font changes with \f, in-line comments with
       \",  the  escaping  of special control characters like \\,
       and many other features.

FORMATTERS    [Toc]    [Back]

       Formatters are the front-end programs that analyze a groff
       document and translate it into a form that is suitable for
       a special device.  The traditional roff  had  two  formatters,
  nroff  for  text  devices  and  troff for graphical
       devices.

       These programs still exist in  the  groff  implementation,
       but  usually  they  are  accessed through a program called
       groff.  This combined and extended the  old  functionality
       into  a single program.  It has many command-line options,
       most of them herited from troff.  To ease the option  jungle,
  the  user-friendly utility grog (from `groff guess')
       was created.  It tries to guess from  the  document  which
       arguments  should  be used and displays a suitable command
       line.  Though not being perfect, it  is  a  good  starting
       point.

PREPROCESSORS    [Toc]    [Back]

       The  classical  preprocessors  that are still available in
       groff.

              eqn    for including mathematical equations.
              grap   for constructing  graphical  elements  (this
                     preprocessor  doesn't come with groff; it is
                     an extra package).
              grn    for including gremlin pictures.
              pic    for creating diagrams.
              refer  for bibliographic references.
              soelim for including other roff files.
              tbl    for rectangular tables.

       Each of these preprocessors defines its own language  that
       is  translated into roff code when run through the preprocessor
 program.  So parts written in these  languages  may
       be included within a roff document.  Such an enhanced document
 is run through one or more corresponding  preprocessors
 before it is fed into the actual formatter.

       The  preprocessor programs extract and transform the document
 parts determined for them.  They can be called either
       in  a  UNIX  pipeline with their program name or automatically
 with a groff option.







                     +-------------+--------------+
                     |preprocessor | groff option |
                     +-------------+--------------+
                     |    eqn      |      -e      |
                     |    grap     |      -G      |
                     |    grn      |      -g      |
                     |    pic      |      -p      |
                     |   refer     |      -R      |
                     |    tbl      |      -r      |
                     |   soelim    |      -s      |
                     +-------------+--------------+

MACRO PACKAGES    [Toc]    [Back]

       Macro packages are collections of macros that are suitable
       to format a special kind of documents in a convenient way.
       This greatly eases the usage of roff.  The  macro  definitions
  of  a  package  are kept in a file called tmac.name
       where name is the internal roff  name  for  this  package.
       All  tmac  files are stored in a single or few directories
       at standard positions.

       A macro package that is used in a document is specified by
       the command line option -m for the formatter like troff -m
       name or groff -m name. General details on  the  naming  of
       macro packages and their placement is found in tmac(5).

       Famous  classical macro packages are man, mandoc, and mdoc
       for manual pages and me, ms, and mm for  books,  articles,
       and letters.  Besides these collections, groff provides an
       increasing number of new macro packages for various applications,
  for  example  integration  of or conversion into
       other file formats.

FILE NAME EXTENSIONS    [Toc]    [Back]

       Manual pages (man-pages) take the section number as a file
       name  extension,  e.g.,  the filename for this document is
       roff.7, i.e., it is kept in section 7 of the man-pages.

       The classical macro packages take the package name  as  an
       extension, e.g.  file.me for a document using the me macro
       package, file.mm for mm, file.ms for ms, file.pic for  pic
       files, etc.

EDITING    [Toc]    [Back]

       Most  text  editors  provide support for editing documents
       using roff.  Especially useful is the  nroff-mode  in  all
       flavors of the Emacs editor.

ENVIRONMENT    [Toc]    [Back]

       GROFF_TMAC_PATH
              A  colon  separated list of directories in which to
              search for macro files, see tmac(5).

       GROFF_TYPESETTER    [Toc]    [Back]
              Default device.

       GROFF_FONT_PATH    [Toc]    [Back]
              A colon separated list of directories in  which  to
              search  for  the  devname  directory.   troff  will
              search in directories given in the -F option before
              these,      and     in     standard     directories
              (.:/usr/local/share/groff/font:/usr/lib/font) after
              these.

FILES    [Toc]    [Back]

       By  default,  groff installs all of its library files in a
       directory tree under /usr/local/share/groff.   This  location
  might vary for different systems.  In the following,
       this directory is referred to as <groff_dir>.


       <groff_dir>/tmac/troffrc
              Initialization file for troff.

       <groff_dir>/tmac/tmac.name
              Macro files.

       <groff_dir>/font/devname/DESC
              Device description file for device name.

       <groff_dir>/font/devname/F
              Font file for font F of device name.

BUGS    [Toc]    [Back]

       The groff documentation is in evolution at the moment.  It
       is  possible  that small inconsistencies between different
       documents exist temporarily.

AUTHOR    [Toc]    [Back]

       This document is part of groff, the GNU roff distribution.
       It was written by Bernd Warken <bwarken@mayn.de>.

       It  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 under

              <http://www.gnu.org/copyleft/fdl.html>.

SEE ALSO    [Toc]    [Back]

      
      
       The main source of information is the groff info(1)  file.

       The  predefined  elements  of  the groff language are also
       documented in the manual page groff(7).

       Formatters  and   their   wrappers:   groff(1),   grog(1),
       nroff(1), and troff(1).

       Postprocessors  for  the  output  devices: grodvi(1), gro-
       html(1), grolbp(1), grolj4(1), grops(1), and grotty(1).

       Standard preprocessors: eqn(1), grn(1),  grap(1),  pic(1),
       refer(1), soelim(1), and tbl(1).

       The  man  pages  for macro packages include groff_tmac(5),
       groff_man(7),       groff_markup(7),        groff_mdoc(7),
       groff_mdoc.samples(7),      groff_me(7),      groff_mm(7),
       groff_mmroff(7), groff_ms(7), and groff_msafer(7).

       The following utilities are available: addftinfo(1),  afm-
       todif(1), hpftodit(1), indxbib(1), lookbib(1), pfbtops(1),
       tfmtodit(1), and gxditview(1).

       For details on the GNU implementation of the  roff  system
       see  groff_char(7),  groff_font(7),  groff_out(7), and the
       file README in the main directory of the groff source distribution.
   These  also give details on how to contact or
       join the groff developer group.

       Many classical  documents  are  still  available  on-line.
       Especially informative are the original Bell Labs proceedings
 for the old, free UNIX  7  found  at  http://cm.bell-
       labs.com/cm/cs/cstr.html  and  the  collection of the late
       Richard S. Stevens at  http://www.kohala.com/start/troff/.



Groff Version 1.16.1      April 8, 2001                   ROFF(7)
[ Back ]
 Similar pages
Name OS Title
groff_tmac FreeBSD macro files in the roff typesetting system
tmac FreeBSD macro files in the roff typesetting system
groff_tmac NetBSD macro files in the roff typesetting system
roff FreeBSD concepts and history of roff typesetting
kvm_getfiles OpenBSD survey open files
kvm_getfiles FreeBSD survey open files
kvm_getfiles NetBSD survey open files
zsoelim Linux satisfy .so requests in roff input
groff NetBSD a short reference for the GNU roff language
ditroff FreeBSD classical device independent roff
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service