troff - the troff processor of the groff text formatting system
.
.
SYNOPSIS
.
troff [\ files\|.\|.\|. \ ] It is possible to have whitespace between a command line option and
its parameter.
.
.
DESCRIPTION
.
This manual page describes the GNU version of
troff . It is part of the groff document formatting system.
.
It is functionally compatible with UNIX troff, but has many extensions,
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.
.
.
OPTIONS
.
-a
Generate an
ASCII approximation of the typeset output.
.
-b
Print a backtrace with each warning or error message.
.
This backtrace should help track down the cause of the error.
.
The line numbers given in the backtrace may not always be correct, for
troff 's idea of line numbers gets confused by
as or
am requests.
.
-c
Disable color output (always disabled in compatibility mode).
.
-C
Enable compatibility mode.
.
-d cs
-d name = s Define
c or
name to be a string
s ; c must be a one letter name.
.
-E
Inhibit all error messages of
troff . Note that this doesn't affect messages output to standard error by macro
packages using the
tm or
tm1 requests.
.
-f fam
Use
fam as the default font family.
.
-F dir
Search in directory (or directory path)
dir for subdirectories
dev name ( name is the name of the device) and there for the
DESC file and font files.
dir is scanned before all other font directories.
.
-i
Read the standard input after all the named input files have been
processed.
.
-m name
Read in the file
If it isn't found, try
tmac. name 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/groff/site-tmac, /usr/share/groff/site-tmac, and
/usr/share/groff/1.18.1.1/tmac.
.
-M dir
Search directory (or directory path)
dir for macro files.
.
This is scanned before all other macro directories.
.
-n num
Number the first page
num . .
-o list
Output only pages in
list , which is a comma-separated list of page ranges;
n means print page
n , means print every page between
m and
n , - n means print every page up to
n , means print every page from
n . troff will exit after printing the last page in the list.
.
-r cn
-r name = n Set number register
c or
name to
n ; c must be a one character name;
n can be any troff numeric expression.
.
-R
Don't load
troffrc and
troffrc-end . .
-T name
Prepare output for device
name , rather than the default
ps . .
-U
Unsafe mode.
.
This will enable the following requests:
open , opena , pso , sy , and
pi . For security reasons, these potentially dangerous requests are disabled
otherwise.
.
It will also add the current directory to the macro search path.
.
-v
Print the version number.
.
-w name
Enable warning
name . Available warnings are described in the section
WARNINGS below.
.
For example, to enable all warnings, use
-w all . Multiple
-w options are allowed.
.
-W name
Inhibit warning
name . Multiple
-W options are allowed.
.
-z
Suppress formatted output.
.
.
WARNINGS
.
The warnings that can be given by
troff 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.
.
c c c | c c c
r rI lB | r rI lB.
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 "t4"
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 "t1"
Non-existent characters.
.
This is enabled by default.
.
color "t524288"
Color related warnings.
.
delim "t8"
Missing or mismatched closing delimiters.
.
di "t256"
Use of
di or
da without an argument when there is no current diversion.
.
el "t16"
Use of the
el request with no matching
ie request.
.
escape "t32768"
Unrecognized escape sequences.
.
When an unrecognized escape sequence is encountered, the escape
character is ignored.
.
font "t131072"
Non-existent fonts.
.
This is enabled by default.
.
ig "t262144"
Invalid escapes in text ignored with the
ig request.
.
These are conditions that are errors when they do not occur in ignored
text.
.
input "t16384"
Invalid input characters.
.
mac "t512"
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 "t8192"
Requests that are missing non-optional arguments.
.
number "t2"
Invalid numeric expressions.
.
This is enabled by default.
.
range "t64"
Out of range arguments.
.
reg "t1024"
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 "t4096"
Use of
[rs]} where a number was expected.
.
scale "t32"
Meaningless scaling indicators.
.
space "t65536"
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.
.
This warning will never occur in compatibility mode.
.
syntax "t128"
Dubious syntax in numeric expressions.
.
tab "t2048"
Inappropriate use of a tab character.
Either use of a tab character where a number was expected, or use of tab
character in an unquoted macro argument.
.
There are also names that can be used to refer to groups of warnings:
.
all
All warnings except
di , mac , and
reg . It is intended that this covers all warnings that are useful with
traditional macro packages.
.
w
All warnings.
.
.
ENVIRONMENT
.
GROFF_TMAC_PATH A colon separated list of directories in which to search for
macro files.
troff will scan directories given in the
-M option before these, and in standard directories (current directory if
in unsafe mode, home directory,
/usr/lib/groff/site-tmac , /usr/share/groff/site-tmac , /usr/share/groff/1.18.1.1/tmac ) after these.
.
GROFF_TYPESETTER Default device.
.
GROFF_FONT_PATH A colon separated list of directories in which to search for the
dev name directory.
troff will scan directories given in the
-F option before these, and in standard directories
/usr/share/groff/1.18.1.1/font , /usr/lib/font ) after these.
.
.
FILES
.
/usr/share/groff/1.18.1.1/tmac/troffrc Initialization file (called before any other macro package).
.
/usr/share/groff/1.18.1.1/tmac/troffrc-end
Initialization file (called after any other macro package).
.
/usr/share/groff/1.18.1.1/tmac/ name .tmac
/usr/share/groff/1.18.1.1/tmac/tmac. name Macro files
.
/usr/share/groff/1.18.1.1/font/dev name /DESC
Device description file for device
name . .
/usr/share/groff/1.18.1.1/font/dev name / F
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 security reasons (even if the
-U option is given).
.
Use the
-M command line option or the
GROFF_TMAC_PATH environment variable to add these directories to the search path if
necessary.
.
.
AUTHOR
.
Copyright (C) 1989, 2001, 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 was written by James Clark, with modifications from
and
.
This document is part of
groff , the GNU roff distribution.
.
.
A description of the
groff language, including a short but complete reference of all predefined
requests, registers, and escapes of plain
groff . From the command line, this is called by
An overview over
groff and other
roff systems, including pointers to further related documentation.
.
The
groff info file , cf.
info(1) , presents all groff documentation within a single document.
.
.
