man pages section 1: User Commands

Exit Print View

Updated: July 2014

gtroff (1)


gtroff - the troff processor of the groff text formatting system


gtroff [ -abcivzCERU ] [ -dcs ] [ -ffam ] [ -Fdir ]
[ -Idir ] [ -mname ] [ -Mdir ] [ -nnum ] [ -olist ]
[ -rcn ] [ -Tname ] [ -wname ] [ -Wname ]
[ files... ]

It  is  possible  to  have whitespace between a command line
option and its parameter.


User Commands                                           GTROFF(1)

     gtroff  -  the  troff processor of the groff text formatting

     gtroff [ -abcivzCERU ] [ -dcs ] [ -ffam ] [ -Fdir ]
            [ -Idir ] [ -mname ] [ -Mdir ] [ -nnum ] [ -olist ]
            [ -rcn ] [ -Tname ] [ -wname ] [ -Wname ]
            [ files... ]

     It  is  possible  to  have whitespace between a command line
     option and its parameter.

     This manual page describes the GNU version of troff.  It  is
     part  of  the groff document formatting system.  It is func-
     tionally compatible with UNIX troff,  but  has  many  exten-
     sions,  see  groff_diff(7).   Usually  it  should be invoked
     using the groff(1) command which will also run preprocessors
     and  postprocessors  in  the  appropriate order and with the
     appropriate options.

     -a        Generate an ASCII  approximation  of  the  typeset

     -b        Print  a backtrace with each warning or error mes-
               sage.  This backtrace should help track  down  the
               cause of the error.  The line numbers given in the
               backtrace may not always be correct, for  gtroff's
               idea  of  line  numbers  gets confused by as or am

     -c        Disable color output (always disabled in  compati-
               bility mode).

     -C        Enable compatibility mode.

     -dname=s  Define c or name to be a string s; c must be a one
               letter name.

     -E        Inhibit all error messages of gtroff.   Note  that
               this  doesn't  affect  messages output to standard
               error by  macro  packages  using  the  tm  or  tm1

     -ffam     Use fam as the default font family.

     -Fdir     Search  in  directory  (or directory path) dir for
               subdirectories devname (name is the  name  of  the
               device)  and  there  for  the  DESC  file and font

Groff Version 1.19.Last change: 13 October 2003                 1

User Commands                                           GTROFF(1)

               files.  dir  is  scanned  before  all  other  font

     -i        Read  the standard input after all the named input
               files have been processed.

     -Idir     This option may be used to specify a directory  to
               search  for  files (both those on the command line
               and those named in .psbb requests).   The  current
               directory  is  always searched first.  This option
               may be specified more than once;  the  directories
               will  be  searched  in  the  order  specified.  No
               directory search is performed for files  specified
               using an absolute path.

     -mname    Read  in  the  file name.tmac.  If it isn't found,
               try instead.  It will be first  searched
               for  in directories given with the -M command line
               option,  then  in   directories   given   in   the
               GROFF_TMAC_PATH  environment variable, then in the
               current directory (only if in  unsafe  mode),  the
               home  directory, /usr/lib/sparcv9/groff/site-tmac,
               /usr/share/groff/site-tmac,                    and

     -Mdir     Search directory (or directory path) dir for macro
               files.  This is scanned  before  all  other  macro

     -nnum     Number the first page num.

     -olist    Output  only pages in list, which is a comma-sepa-
               rated list of page ranges; n means print  page  n,
               m-n  means  print  every  page between m and n, -n
               means print every page up to  n,  n-  means  print
               every  page from n.  gtroff will exit after print-
               ing the last page in the list.

     -rname=n  Set number register c or name to n; c  must  be  a
               one  character  name;  n  can be any troff numeric

     -R        Don't load troffrc and troffrc-end.

     -Tname    Prepare output for device name,  rather  than  the
               default  ps;  see  groff(1)  for  a  more detailed

     -U        Unsafe  mode.   This  will  enable  the  following
               requests: open, opena, pso, sy, and pi.  For secu-
               rity reasons, these potentially dangerous requests

Groff Version 1.19.Last change: 13 October 2003                 2

User Commands                                           GTROFF(1)

               are disabled otherwise.  It will also add the cur-
               rent directory to the macro search path.

     -v        Print the version number.

     -wname    Enable  warning  name.   Available  warnings   are
               described  in  the  section  WARNINGS  below.  For
               example, to enable all warnings, use -w all.  Mul-
               tiple -w options are allowed.

     -Wname    Inhibit  warning  name.   Multiple  -W options are

     -z        Suppress formatted output.

     The warnings that can be given by gtroff  are  divided  into
     the  following  categories.   The  name associated with each
     warning is used by the -w and -W options; the number is used
     by the warn request, and by the .warn register; it is always
     a power of 2 to allow bitwise composition.

         |Bit   Code   Warning | Bit    Code      Warning   |
         |  0      1   char    |  10     1024   reg         |
         |  1      2   number  |  11     2048   tab         |
         |  2      4   break   |  12     4096   right-brace |
         |  3      8   delim   |  13     8192   missing     |
         |  4     16   el      |  14    16384   input       |
         |  5     32   scale   |  15    32768   escape      |
         |  6     64   range   |  16    65536   space       |
         |  7    128   syntax  |  17   131072   font        |
         |  8    256   di      |  18   262144   ig          |
         |  9    512   mac     |  19   524288   color       |
     break           4   In fill mode, lines which could  not  be
                         broken  so  that  their  length was less
                         than the line length.  This  is  enabled
                         by default.

     char            1   Non-existent    characters.    This   is
                         enabled by default.

     color      524288   Color related warnings.

     delim           8   Missing  or  mismatched  closing  delim-

     di            256   Use of di or da without an argument when
                         there is no current diversion.

Groff Version 1.19.Last change: 13 October 2003                 3

User Commands                                           GTROFF(1)

     el             16   Use of the el request with  no  matching
                         ie request.

     escape      32768   Unrecognized  escape sequences.  When an
                         unrecognized escape sequence is  encoun-
                         tered,  the escape character is ignored.

     font       131072   Non-existent fonts.  This is enabled  by

     ig         262144   Invalid escapes in text ignored with the
                         ig request.  These are  conditions  that
                         are  errors  when  they  do not occur in
                         ignored text.

     input       16384   Invalid input characters.

     mac           512   Use of  undefined  strings,  macros  and
                         diversions.   When  an undefined string,
                         macro or diversion is used, that  string
                         is  automatically defined as empty.  So,
                         in most cases, at most one warning  will
                         be given for each name.

     missing      8192   Requests  that  are missing non-optional

     number          2   Invalid numeric  expressions.   This  is
                         enabled by default.

     range          64   Out of range arguments.

     reg          1024   Use of undefined number registers.  When
                         an undefined number  register  is  used,
                         that  register  is automatically defined
                         to have a  value  of  0.   So,  in  most
                         cases, at most one warning will be given
                         for use of a particular name.

     right-brace  4096   Use of \} where a number was expected.

     scale          32   Meaningless scaling indicators.

     space       65536   Missing space between a request or macro
                         and  its argument.  This warning will be
                         given when an undefined name longer than
                         two  characters  is encountered, and the
                         first two characters of the name make  a
                         defined name.  The request or macro will
                         not be invoked.  When  this  warning  is
                         given,   no   macro   is   automatically
                         defined.  This is  enabled  by  default.

Groff Version 1.19.Last change: 13 October 2003                 4

User Commands                                           GTROFF(1)

                         This warning will never occur in compat-
                         ibility mode.

     syntax        128   Dubious syntax in numeric expressions.

     tab          2048   Inappropriate use of  a  tab  character.
                         Either  use  of  a tab character where a
                         number was expected, or use of tab char-
                         acter in an unquoted macro argument.

     There  are also names that can be used to refer to groups of

     all  All warnings except di, mac, and reg.  It  is  intended
          that this covers all warnings that are useful with tra-
          ditional macro packages.

     w    All warnings.

          A colon separated  list  of  directories  in  which  to
          search  for  macro files.  gtroff will scan directories
          given in the -M option before these,  and  in  standard
          directories  (current directory if in unsafe mode, home
          directory,            /usr/lib/sparcv9/groff/site-tmac,
          /usr/share/groff/1.19.2/tmac) after these.

          Default device.

          A colon separated  list  of  directories  in  which  to
          search  for  the  devname  directory.  gtroff will scan
          directories given in the -F option before these, and in
          standard    directories    (/usr/share/groff/site-font,
          /usr/share/groff/1.19.2/font,   /usr/lib/font)    after

          Initialization  file  (called  before  any  other macro

          Initialization file (called after any other macro pack-

          Macro files

Groff Version 1.19.Last change: 13 October 2003                 5

User Commands                                           GTROFF(1)

          Device description file for device name.

          Font file for font F of device name.

     Note  that  troffrc  and troffrc-end are neither searched in
     the current nor in the home directory by default  for  secu-
     rity  reasons  (even if the -U option is given).  Use the -M
     command line option or the GROFF_TMAC_PATH environment vari-
     able  to  add these directories to the search path if neces-

     Copyright (C) 1989, 2001, 2002, 2003 Free  Software  Founda-
     tion, 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 GNU copyleft site <http://>.   This  document was written
     by James  Clark,  with  modifications  from  Werner  Lemberg
     <> and Bernd Warken <>

     This document is part of groff, the GNU roff distribution.

     See   attributes(5)   for   descriptions  of  the  following

     |Availability   | text/groff/groff-core |
     |Stability      | Uncommitted           |
          The main program of the groff system, a wrapper  around

          A  description of the groff language, including a short
          but complete reference of all predefined requests, reg-
          isters,  and  escapes of plain groff.  From the command
          line, this is called by

               man 7 groff

Groff Version 1.19.Last change: 13 October 2003                 6

User Commands                                           GTROFF(1)

          The differences of the groff language and the classical
          troff  language.   Currently,  this  is the most actual
          document of the groff system.

          An overview over groff and other roff systems,  includ-
          ing pointers to further related documentation.

     The  groff  info file, cf. info(1), presents all groff docu-
     mentation within a single document.

     This  software  was   built   from   source   available   at    The  original
     community       source       was       downloaded       from

     Further  information about this software can be found on the
     open source community  website  at

Groff Version 1.19.Last change: 13 October 2003                 7