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 ap‐
19       propriate options.
20

OPTIONS

22       Whitespace is permitted between a command-line option and its argument.
23
24       -a     Generate an ASCII approximation of the typeset output.
25
26       -b     Print a backtrace with each  warning  or  error  message.   This
27              backtrace  should  help  track down the cause of the error.  The
28              line numbers given in the backtrace may not always  be  correct,
29              for  troff's  idea of line numbers gets confused by as or am re‐
30              quests.
31
32       -c     Disable color output (always disabled in compatibility mode).
33
34       -C     Enable compatibility mode.
35
36       -dcs
37       -dname=s
38              Define c or name to be a string s; c must be a one letter name.
39
40       -E     Inhibit all error messages of troff.  Note that this doesn't af‐
41              fect  messages  output to standard error by macro packages using
42              the tm or tm1 requests.
43
44       -ffam  Use fam as the default font family.
45
46       -Fdir  Search in directory (or directory path) dir  for  subdirectories
47              devname  (name is the name of the device) and there for the DESC
48              file and font files.  dir is scanned before all other  font  di‐
49              rectories.
50
51       -i     Read  the  standard  input  after all the named input files have
52              been processed.
53
54       -Idir  This option may be used to add a directory to  the  search  path
55              for  files  (both  those  on the command line and those named in
56              .psbb requests).  The search path is initialized with  the  cur‐
57              rent  directory.   This  option may be specified more than once;
58              the directories are then searched in the  order  specified  (but
59              before  the current directory).  If you want to make the current
60              directory be read before other directories, add -I. at  the  ap‐
61              propriate place.
62
63              No directory search is performed for files with an absolute file
64              name.
65
66       -mname Read in the file name.tmac.  If it isn't  found,  try  tmac.name
67              instead.   It  will  be  first searched for in directories given
68              with the -M command-line option, then in  directories  given  in
69              the  GROFF_TMAC_PATH  environment  variable, then in the current
70              directory (only if in unsafe mode), the  home  directory,  /etc/
71              groff/site-tmac,   /etc/groff/site-tmac,  and  /usr/share/groff/
72              1.22.4/tmac.
73
74       -Mdir  Search directory (or directory path) dir for macro files.   This
75              is scanned before all other macro directories.
76
77       -nnum  Number the first page num.
78
79       -olist Output  only  pages  in list, which is a comma-separated list of
80              page ranges; n means print page n, m-n means  print  every  page
81              between  m  and  n,  -n means print every page up to n, n- means
82              print every page from n.  troff will  exit  after  printing  the
83              last page in the list.
84
85       -rcn
86       -rname=n
87              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;  see
93              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 potentially
97              dangerous requests are disabled otherwise.  It will also add the
98              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  sec‐
103              tion  “Warnings”  below.   To enable most useful warnings use -w
104              all.  To enable absolutely all warnings use -w w instead.   Mul‐
105              tiple -w options are allowed.
106
107       -Wname Inhibit warning name.  Multiple -W options are allowed.
108
109       -z     Suppress formatted output.
110

WARNINGS

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

ENVIRONMENT

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

FILES

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

AUTHORS

252       The GNU version of troff was originally written by James Clark; he also
253       wrote  the  original  version  of  this document, which was modified by
254       Werner Lemberg ⟨wl@gnu.org⟩ and  Bernd  Warken  ⟨groff-bernd.warken-72@
255       web.de⟩.
256

SEE ALSO

258       groff(1)
259              The main program of the groff system, a wrapper around troff.
260
261       groff(7)
262              A  description of the groff language, including a short but com‐
263              plete reference of all predefined requests, registers,  and  es‐
264              capes of plain groff.  From the command line, this is called by
265
266                     man 7 groff
267
268       groff_diff(7)
269              The  differences  of  the groff language and the classical troff
270              language.  Currently, this is the most actual  document  of  the
271              groff system.
272
273       roff(7)
274              An  overview over groff and other roff systems, including point‐
275              ers to further related documentation.
276
277       Groff: The GNU Implementation of troff, by Trent A. Fisher  and  Werner
278       Lemberg,  is the primary groff manual.  You can browse it interactively
279       with “info groff”.
280
281
282
283groff 1.22.4                    19 January 2023                       TROFF(1)
Impressum