1TROFF(1)                    General Commands Manual                   TROFF(1)
2
3
4

NAME

6       troff - the troff processor of the groff text formatting system
7

SYNOPSIS

9       troff [-abcivzCERU] [-d cs] [-f fam] [-F dir] [-I dir] [-m name]
10             [-M dir] [-n num] [-o list] [-r cn] [-T name] [-w name] [-W name]
11             [file ...]
12

DESCRIPTION

14       This manual page describes the GNU version of troff.  It is part of the
15       groff document formatting system.  It is functionally  compatible  with
16       UNIX  troff,  but  has  many extensions, see groff_diff(7).  Usually it
17       should be invoked using the groff(1) command which will also  run  pre‐
18       processors  and  postprocessors  in  the appropriate order and with the
19       appropriate options.
20

OPTIONS

22       It is possible to have whitespace between a command line option and its
23       parameter.
24
25       -a        Generate an ASCII approximation of the typeset output.
26
27       -b        Print  a  backtrace with each warning or error message.  This
28                 backtrace should help track down the cause of the error.  The
29                 line  numbers  given  in the backtrace may not always be cor‐
30                 rect, for troff's idea of line numbers gets confused by as or
31                 am requests.
32
33       -c        Disable color output (always disabled in compatibility mode).
34
35       -C        Enable compatibility mode.
36
37       -dcs
38       -dname=s  Define  c  or  name  to be a string s; c must be a one letter
39                 name.
40
41       -E        Inhibit all error messages of troff.  Note that this  doesn't
42                 affect  messages  output  to standard error by macro packages
43                 using the tm or tm1 requests.
44
45       -ffam     Use fam as the default font family.
46
47       -Fdir     Search in directory (or directory path) dir  for  subdirecto‐
48                 ries  devname  (name is the name of the device) and there for
49                 the DESC file and font files.   dir  is  scanned  before  all
50                 other font directories.
51
52       -i        Read  the standard input after all the named input files have
53                 been processed.
54
55       -Idir     This option may be used to add a directory to the search path
56                 for  files (both those on the command line and those named in
57                 .psbb requests).  The search path  is  initialized  with  the
58                 current  directory.   This  option may be specified more than
59                 once; the directories are then searched in the  order  speci‐
60                 fied (but before the current directory).  If you want to make
61                 the current directory be read before other  directories,  add
62                 -I. at the appropriate place.
63
64                 No  directory  search is performed for files with an absolute
65                 file name.
66
67       -mname    Read in the file name.tmac.  If it isn't found, try tmac.name
68                 instead.   It will be first searched for in directories given
69                 with the -M command line option, then in directories given in
70                 the GROFF_TMAC_PATH environment variable, then in the current
71                 directory (only if  in  unsafe  mode),  the  home  directory,
72                 /etc/groff/site-tmac,        /etc/groff/site-tmac,        and
73                 /usr/share/groff/1.22.2/tmac.
74
75       -Mdir     Search directory (or directory path)  dir  for  macro  files.
76                 This is scanned before all other macro directories.
77
78       -nnum     Number the first page num.
79
80       -olist    Output only pages in list, which is a comma-separated list of
81                 page ranges; n means print page n, m-n means print every page
82                 between  m and n, -n means print every page up to n, n- means
83                 print every page from n.  troff will exit after printing  the
84                 last page in the list.
85
86       -rcn
87       -rname=n  Set number register c or name to n; c must be a one character
88                 name; n can be any troff numeric expression.
89
90       -R        Don't load troffrc and troffrc-end.
91
92       -Tname    Prepare output for device name, rather than the  default  ps;
93                 see groff(1) for a more detailed description.
94
95       -U        Unsafe  mode.  This will enable the following requests: open,
96                 opena, pso, sy, and pi.  For security reasons,  these  poten‐
97                 tially  dangerous  requests  are disabled otherwise.  It will
98                 also add the current directory to the macro search path.
99
100       -v        Print the version number.
101
102       -wname    Enable warning name.  Available warnings are described in the
103                 section WARNINGS below.  For example, to enable all warnings,
104                 use -w all.  Multiple -w options are allowed.
105
106       -Wname    Inhibit warning name.  Multiple -W options are allowed.
107
108       -z        Suppress formatted output.
109

WARNINGS

111       The warnings that can be given by troff are divided into the  following
112       categories.   The  name  associated with each warning is used by the -w
113       and -W options; the number is used by the  warn  request,  and  by  the
114       .warn register; it is always a power of 2 to allow bitwise composition.
115
116                ┌─────────────────────┬─────────────────────────────┐
117                │Bit   Code   Warning │ Bit    Code       Warning   │
118                ├─────────────────────┼─────────────────────────────┤
119                │  0      1   char    │  10      1024   reg         
120                │  1      2   number  │  11      2048   tab         
121                │  2      4   break   │  12      4096   right-brace 
122                │  3      8   delim   │  13      8192   missing     
123                │  4     16   el      │  14     16384   input       
124                │  5     32   scale   │  15     32768   escape      
125                │  6     64   range   │  16     65536   space       
126                │  7    128   syntax  │  17    131072   font        
127                │  8    256   di      │  18    262144   ig          
128                │  9    512   mac     │  19    524288   color       
129                │                     │  20   1048576   file        
130                └─────────────────────┴─────────────────────────────┘
131       break           4   In  fill  mode,  lines which could not be broken so
132                           that their length was less than  the  line  length.
133                           This is enabled by default.
134
135       char            1   Non-existent   characters.    This  is  enabled  by
136                           default.
137
138       color      524288   Color related warnings.
139
140       delim           8   Missing or mismatched closing delimiters.
141
142       di            256   Use of di or da without an argument when  there  is
143                           no current diversion.
144
145       el             16   Use of the el request with no matching ie request.
146
147       escape      32768   Unrecognized  escape  sequences.   When an unrecog‐
148                           nized escape sequence is  encountered,  the  escape
149                           character is ignored.
150
151       file      1048576   Indicates  a  missing  file  for  the  mso request.
152                           Enabled by default.
153
154       font       131072   Non-existent fonts.  This is enabled by default.
155
156       ig         262144   Invalid  escapes  in  text  ignored  with  the   ig
157                           request.  These are conditions that are errors when
158                           they do not occur in ignored text.
159
160       input       16384   Invalid input characters.
161
162       mac           512   Use of undefined strings,  macros  and  diversions.
163                           When  an  undefined  string,  macro or diversion is
164                           used,  that  string  is  automatically  defined  as
165                           empty.  So, in most cases, at most one warning will
166                           be given for each name.
167
168       missing      8192   Requests that are missing non-optional arguments.
169
170       number          2   Invalid numeric expressions.  This  is  enabled  by
171                           default.
172
173       range          64   Out of range arguments.
174
175       reg          1024   Use  of  undefined number registers.  When an unde‐
176                           fined number register is  used,  that  register  is
177                           automatically defined to have a value of 0.  So, in
178                           most cases, at most one warning will be  given  for
179                           use of a particular name.
180
181       right-brace  4096   Use of \} where a number was expected.
182
183       scale          32   Meaningless scaling indicators.
184
185       space       65536   Missing  space  between  a request or macro and its
186                           argument.  This warning will be given when an unde‐
187                           fined  name  longer  than two characters is encoun‐
188                           tered, and the first two  characters  of  the  name
189                           make a defined name.  The request or macro will not
190                           be invoked.  When this warning is given,  no  macro
191                           is  automatically  defined.   This  is  enabled  by
192                           default.  This warning will never occur in compati‐
193                           bility mode.
194
195       syntax        128   Dubious syntax in numeric expressions.
196
197       tab          2048   Inappropriate  use  of a tab character.  Either use
198                           of a tab character where a number was expected,  or
199                           use of tab character in an unquoted macro argument.
200
201       There are also names that can be used to refer to groups of warnings:
202
203       all    All  warnings except di, mac, and reg.  It is intended that this
204              covers all warnings that are useful with traditional macro pack‐
205              ages.
206
207       w      All warnings.
208

ENVIRONMENT

210       GROFF_TMAC_PATH
211              A  colon  separated  list  of directories in which to search for
212              macro files.  troff will scan directories given in the -M option
213              before  these, and in standard directories (current directory if
214              in   unsafe   mode,   home   directory,    /etc/groff/site-tmac,
215              /etc/groff/site-tmac, /usr/share/groff/1.22.2/tmac) after these.
216
217       GROFF_TYPESETTER
218              Default device.
219
220       GROFF_FONT_PATH
221              A colon separated list of directories in which to search for the
222              devname directory.  troff will scan directories given in the  -F
223              option    before    these,    and    in   standard   directories
224              (/etc/groff/site-font,             /usr/share/groff/1.22.2/font,
225              /usr/lib/font) after these.
226

FILES

228       /usr/share/groff/1.22.2/tmac/troffrc
229              Initialization file (called before any other macro package).
230
231       /usr/share/groff/1.22.2/tmac/troffrc-end
232              Initialization file (called after any other macro package).
233
234       /usr/share/groff/1.22.2/tmac/name.tmac
235       /usr/share/groff/1.22.2/tmac/tmac.name
236              Macro files
237
238       /usr/share/groff/1.22.2/font/devname/DESC
239              Device description file for device name.
240
241       /usr/share/groff/1.22.2/font/devname/F
242              Font file for font F of device name.
243
244       Note  that  troffrc and troffrc-end are neither searched in the current
245       nor in the home directory by default for security reasons (even if  the
246       -U   option  is  given).   Use  the  -M  command  line  option  or  the
247       GROFF_TMAC_PATH environment variable to add these  directories  to  the
248       search path if necessary.
249

AUTHOR

251       Copyright  (C)  1989,  2001, 2002, 2003, 2007, 2008, 2009 Free Software
252       Foundation, Inc.
253
254       This document is distributed under the terms of the FDL (GNU Free Docu‐
255       mentation  License)  version  1.3 or later.  You should have received a
256       copy of the FDL on your system, it is also available on-line at the GNU
257       copyleft  site  ⟨http://www.gnu.org/copyleft/fdl.html⟩.   This document
258       was written by James Clark,  with  modifications  from  Werner  Lemberg
259       ⟨wl@gnu.org⟩ and Bernd Warken ⟨groff-bernd.warken-72@web.de⟩.
260
261       This document is part of groff, the GNU roff distribution.
262

SEE ALSO

264       groff(1)
265              The main program of the groff system, a wrapper around troff.
266
267       groff(7)
268              A  description of the groff language, including a short but com‐
269              plete reference  of  all  predefined  requests,  registers,  and
270              escapes  of  plain groff.  From the command line, this is called
271              by
272
273                     man 7 groff
274
275       groff_diff(7)
276              The differences of the groff language and  the  classical  troff
277              language.   Currently,  this  is the most actual document of the
278              groff system.
279
280       roff(7)
281              An overview over groff and other roff systems, including  point‐
282              ers to further related documentation.
283
284       The  groff  info  file,  cf.  info(1), presents all groff documentation
285       within a single document.
286
287
288
289Groff Version 1.22.2            7 February 2013                       TROFF(1)
Impressum