686 lines
13 KiB
Groff
686 lines
13 KiB
Groff
'\" t
|
|
.TH TROFF 1 "21 March 2020" "groff 1.22.4"
|
|
.SH NAME
|
|
troff \- the troff processor of the groff text formatting system
|
|
.
|
|
.\" troff.man -> troff.1
|
|
.
|
|
.
|
|
.\" ====================================================================
|
|
.\" Legal Terms
|
|
.\" ====================================================================
|
|
.\"
|
|
.\" Copyright (C) 1989-2018 Free Software Foundation, Inc.
|
|
.\"
|
|
.\" This file is part of groff, the GNU roff type-setting system.
|
|
.\"
|
|
.\" Permission is granted to copy, distribute and/or modify this
|
|
.\" document under the terms of the GNU Free Documentation License,
|
|
.\" Version 1.3 or any later version published by the Free Software
|
|
.\" Foundation; with no Invariant Sections, with no Front-Cover Texts,
|
|
.\" and with no Back-Cover Texts.
|
|
.\"
|
|
.\" A copy of the Free Documentation License is included as a file
|
|
.\" called FDL in the main directory of the groff source package.
|
|
.\"
|
|
.\" A copy of the GNU Free Documentation License is also available in this
|
|
.\" Debian package as /usr/share/doc/groff-base/copyright.
|
|
.
|
|
.
|
|
.\" ====================================================================
|
|
.SH SYNOPSIS
|
|
.\" ====================================================================
|
|
.
|
|
.SY troff
|
|
.OP \-abcivzCERU
|
|
.OP \-d cs
|
|
.OP \-f fam
|
|
.OP \-F dir
|
|
.OP \-I dir
|
|
.OP \-m name
|
|
.OP \-M dir
|
|
.OP \-n num
|
|
.OP \-o list
|
|
.OP \-r cn
|
|
.OP \-T name
|
|
.OP \-w name
|
|
.OP \-W name
|
|
.RI [ file
|
|
\&.\|.\|.\&]
|
|
.YS
|
|
.
|
|
.
|
|
.\" ====================================================================
|
|
.SH DESCRIPTION
|
|
.\" ====================================================================
|
|
.
|
|
This manual page describes the GNU version of
|
|
.BR troff .
|
|
.
|
|
It is part of the groff document formatting system.
|
|
.
|
|
It is functionally compatible with Unix troff, but has many
|
|
extensions, see
|
|
.BR \%groff_diff (7).
|
|
.
|
|
Usually it should be invoked using the
|
|
.BR groff (1)
|
|
command which will also run preprocessors and postprocessors in the
|
|
appropriate order and with the appropriate options.
|
|
.
|
|
.
|
|
.\" ====================================================================
|
|
.SH OPTIONS
|
|
.\" ====================================================================
|
|
.
|
|
Whitespace is permitted between a command-line option and its argument.
|
|
.
|
|
.
|
|
.TP
|
|
.B \-a
|
|
Generate an ASCII approximation of the typeset output.
|
|
.
|
|
.TP
|
|
.B \-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
|
|
.BR troff 's
|
|
idea of line numbers gets confused by
|
|
.B as
|
|
or
|
|
.B am
|
|
requests.
|
|
.
|
|
.TP
|
|
.B \-c
|
|
Disable color output (always disabled in compatibility mode).
|
|
.
|
|
.TP
|
|
.B \-C
|
|
Enable compatibility mode.
|
|
.
|
|
.TP
|
|
.BI \-d cs
|
|
.TQ
|
|
.BI \-d name = s
|
|
Define
|
|
.I c
|
|
or
|
|
.I name
|
|
to be a string
|
|
.IR s ;
|
|
.I c
|
|
must be a one letter name.
|
|
.
|
|
.TP
|
|
.B \-E
|
|
Inhibit all error messages of
|
|
.BR troff .
|
|
.
|
|
Note that this doesn't affect messages output to standard error by
|
|
macro packages using the
|
|
.B tm
|
|
or
|
|
.B tm1
|
|
requests.
|
|
.
|
|
.TP
|
|
.BI \-f fam
|
|
Use
|
|
.I fam
|
|
as the default font family.
|
|
.
|
|
.TP
|
|
.BI \-F dir
|
|
Search in directory (or directory path)
|
|
.I dir
|
|
for subdirectories
|
|
.IR dev name
|
|
.RI ( name
|
|
is the name of the device) and there for the
|
|
.I DESC
|
|
file and font files.
|
|
.
|
|
.I dir
|
|
is scanned before all other font directories.
|
|
.
|
|
.TP
|
|
.B \-i
|
|
Read the standard input after all the named input files have been
|
|
processed.
|
|
.
|
|
.TP
|
|
.BI \-I dir
|
|
This option may be used to add a directory to the search path for
|
|
files (both those on the command line and those named in
|
|
.B \&.psbb
|
|
requests).
|
|
.
|
|
The search path is initialized with the current directory.
|
|
.
|
|
This option may be specified more than once; the directories are then
|
|
searched in the order specified (but before the current directory).
|
|
.
|
|
If you want to make the current directory be read before other
|
|
directories, add
|
|
.B \-I.\&
|
|
at the appropriate place.
|
|
.
|
|
.IP
|
|
No directory search is performed for files with an absolute file name.
|
|
.
|
|
.TP
|
|
.BI \-m name
|
|
Read in the file
|
|
.RI name .tmac .
|
|
.
|
|
If it isn't found, try
|
|
.IR tmac. name
|
|
instead.
|
|
.
|
|
It will be first searched for in directories given with the
|
|
.B \-M
|
|
command-line option, then in directories given in the
|
|
.I GROFF_TMAC_PATH
|
|
environment variable, then in the current directory (only if in unsafe
|
|
mode), the home directory,
|
|
.IR /usr/\:lib/\:groff/\:site\-tmac ,
|
|
.IR /usr/\:share/\:groff/\:site\-tmac ,
|
|
and
|
|
.IR /usr/\:share/\:groff/\:1.22.4/\:tmac .
|
|
.
|
|
.TP
|
|
.BI \-M dir
|
|
Search directory (or directory path)
|
|
.I dir
|
|
for macro files.
|
|
.
|
|
This is scanned before all other macro directories.
|
|
.
|
|
.TP
|
|
.BI \-n num
|
|
Number the first page
|
|
.IR num .
|
|
.
|
|
.TP
|
|
.BI \-o list
|
|
Output only pages in
|
|
.IR list ,
|
|
which is a comma-separated list of page ranges;
|
|
.I n
|
|
means print page
|
|
.IR n ,
|
|
.IB m \- n
|
|
means print every page between
|
|
.I m
|
|
and
|
|
.IR n ,
|
|
.BI \- n
|
|
means print every page up to
|
|
.IR n ,
|
|
.IB n \-
|
|
means print every page from
|
|
.IR n .
|
|
.
|
|
.B troff
|
|
will exit after printing the last page in the list.
|
|
.
|
|
.TP
|
|
.BI \-r cn
|
|
.TQ
|
|
.BI \-r name = n
|
|
Set number register
|
|
.I c
|
|
or
|
|
.I name
|
|
to
|
|
.IR n ;
|
|
.I c
|
|
must be a one character name;
|
|
.I n
|
|
can be any troff numeric expression.
|
|
.
|
|
.TP
|
|
.B \-R
|
|
Don't load
|
|
.I troffrc
|
|
and
|
|
.IR troffrc\-end .
|
|
.
|
|
.TP
|
|
.BI \-T name
|
|
Prepare output for device
|
|
.IR name ,
|
|
rather than the default
|
|
.BR ps ;
|
|
see
|
|
.BR groff (1)
|
|
for a more detailed description.
|
|
.
|
|
.TP
|
|
.B \-U
|
|
Unsafe mode.
|
|
.
|
|
This will enable the following requests:
|
|
.BR open ,
|
|
.BR opena ,
|
|
.BR pso ,
|
|
.BR sy ,
|
|
and
|
|
.BR pi .
|
|
For security reasons, these potentially dangerous requests are
|
|
disabled otherwise.
|
|
.
|
|
It will also add the current directory to the macro search path.
|
|
.
|
|
.TP
|
|
.B \-v
|
|
Print the version number.
|
|
.
|
|
.TP
|
|
.BI \-w name
|
|
Enable warning
|
|
.IR name .
|
|
.
|
|
Available warnings are described in section \(lqWarnings\(rq below.
|
|
.
|
|
To enable most useful warnings use
|
|
.B \-w
|
|
.BR all .
|
|
To enable absolutely all warnings use
|
|
.B \-w w
|
|
instead.
|
|
Multiple
|
|
.B \-w
|
|
options are allowed.
|
|
.
|
|
.TP
|
|
.BI \-W name
|
|
Inhibit warning
|
|
.IR name .
|
|
.
|
|
Multiple
|
|
.B \-W
|
|
options are allowed.
|
|
.
|
|
.TP
|
|
.B \-z
|
|
Suppress formatted output.
|
|
.
|
|
.
|
|
.\" ====================================================================
|
|
.SH WARNINGS
|
|
.\" ====================================================================
|
|
.
|
|
The warnings that can be given by
|
|
.B troff
|
|
are divided into the following categories.
|
|
.
|
|
The name associated with each warning is used by the
|
|
.B \-w
|
|
and
|
|
.B \-W
|
|
options; the number is used by the
|
|
.B warn
|
|
request, and by the
|
|
.B .warn
|
|
register; it is always a power of 2 to allow bitwise composition.
|
|
.
|
|
.P
|
|
.TS
|
|
tab(@), center, box;
|
|
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
|
|
@@@20@1048576@file
|
|
.TE
|
|
.
|
|
.P
|
|
.nr x \w'\fBright-brace'+1n+\w'00000'u
|
|
.ta \nxuR
|
|
.
|
|
.TP \nxu+3n
|
|
.BR 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.
|
|
.
|
|
.TP
|
|
.BR char "\t1"
|
|
Non-existent characters.
|
|
.
|
|
This is enabled by default.
|
|
.
|
|
.TP
|
|
.BR color "\t524288"
|
|
Color-related warnings.
|
|
.
|
|
.TP
|
|
.BR delim "\t8"
|
|
Missing or mismatched closing delimiters.
|
|
.
|
|
.TP
|
|
.BR di "\t256"
|
|
Use of
|
|
.B di
|
|
or
|
|
.B da
|
|
without an argument when there is no current diversion.
|
|
.
|
|
.TP
|
|
.BR el "\t16"
|
|
Use of the
|
|
.B el
|
|
request with no matching
|
|
.B ie
|
|
request.
|
|
.
|
|
.TP
|
|
.BR escape "\t32768"
|
|
Unrecognized escape sequences.
|
|
.
|
|
When an unrecognized escape sequence is encountered, the escape
|
|
character is ignored.
|
|
.
|
|
.TP
|
|
.BR file "\t1048576"
|
|
Indicates a missing file for the
|
|
.B mso
|
|
request.
|
|
.
|
|
Enabled by default.
|
|
.
|
|
.TP
|
|
.BR font "\t131072"
|
|
Non-existent fonts.
|
|
.
|
|
This is enabled by default.
|
|
.
|
|
.TP
|
|
.BR ig "\t262144"
|
|
Invalid escapes in text ignored with the
|
|
.B ig
|
|
request.
|
|
.
|
|
These are conditions that are errors when they do not occur in ignored
|
|
text.
|
|
.
|
|
.TP
|
|
.BR input "\t16384"
|
|
Invalid input characters.
|
|
.
|
|
.TP
|
|
.BR 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.
|
|
.
|
|
.TP
|
|
.BR missing "\t8192"
|
|
Requests that are missing non-optional arguments.
|
|
.
|
|
.TP
|
|
.BR number "\t2"
|
|
Invalid numeric expressions.
|
|
.
|
|
This is enabled by default.
|
|
.
|
|
.TP
|
|
.BR range "\t64"
|
|
Out of range arguments.
|
|
.
|
|
.TP
|
|
.BR 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.
|
|
.
|
|
.TP
|
|
.BR right-brace "\t4096"
|
|
Use of
|
|
.B \(rs}
|
|
where a number was expected.
|
|
.
|
|
.TP
|
|
.BR scale "\t32"
|
|
Meaningless scaling indicators.
|
|
.
|
|
.TP
|
|
.BR 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.
|
|
.
|
|
.TP
|
|
.BR syntax "\t128"
|
|
Dubious syntax in numeric expressions.
|
|
.
|
|
.TP
|
|
.BR 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.
|
|
.
|
|
.P
|
|
There are also names that can be used to refer to groups of warnings:
|
|
.
|
|
.TP
|
|
.B all
|
|
All warnings except
|
|
.BR di ,
|
|
.BR mac ,
|
|
and
|
|
.BR reg .
|
|
.
|
|
It is intended that this covers all warnings that are useful with
|
|
traditional macro packages.
|
|
.
|
|
.TP
|
|
.B w
|
|
All warnings.
|
|
.
|
|
.
|
|
.\" ====================================================================
|
|
.SH ENVIRONMENT
|
|
.\" ====================================================================
|
|
.
|
|
.TP
|
|
.I GROFF_TMAC_PATH
|
|
A colon separated list of directories in which to search for
|
|
macro files.
|
|
.
|
|
.B troff
|
|
will scan directories given in the
|
|
.B \-M
|
|
option before these, and in standard directories (current directory if
|
|
in unsafe mode, home directory,
|
|
.IR /usr/\:lib/\:groff/\:site\-tmac ,
|
|
.IR /usr/\:share/\:groff/\:site\-tmac ,
|
|
.IR /usr/\:share/\:groff/\:1.22.4/\:tmac )
|
|
after these.
|
|
.
|
|
.TP
|
|
.I GROFF_TYPESETTER
|
|
Default device.
|
|
.
|
|
.TP
|
|
.I GROFF_FONT_PATH
|
|
A colon separated list of directories in which to search for the
|
|
.IR dev name
|
|
directory.
|
|
.
|
|
.B troff
|
|
will scan directories given in the
|
|
.B \-F
|
|
option before these, and in standard directories
|
|
.RI ( /usr/\:share/\:groff/\:site\-font ,
|
|
.IR /usr/\:share/\:groff/\:1.22.4/\:font ,
|
|
.IR /usr/\:lib/\:font )
|
|
after these.
|
|
.
|
|
.
|
|
.\" ====================================================================
|
|
.SH FILES
|
|
.\" ====================================================================
|
|
.
|
|
.TP
|
|
.I /usr/\:share/\:groff/\:1.22.4/\:tmac/troffrc
|
|
Initialization file (called before any other macro package).
|
|
.
|
|
.TP
|
|
.I /usr/\:share/\:groff/\:1.22.4/\:tmac/troffrc\-end
|
|
Initialization file (called after any other macro package).
|
|
.
|
|
.TP
|
|
.IR /usr/\:share/\:groff/\:1.22.4/\:tmac/ name .tmac
|
|
.TQ
|
|
.IR /usr/\:share/\:groff/\:1.22.4/\:tmac/tmac. name
|
|
Macro files
|
|
.
|
|
.TP
|
|
.IR /usr/\:share/\:groff/\:1.22.4/\:font/dev name /DESC
|
|
Device description file for device
|
|
.IR name .
|
|
.
|
|
.TP
|
|
.IR /usr/\:share/\:groff/\:1.22.4/\:font/dev name / F
|
|
Font file for font
|
|
.I F
|
|
of device
|
|
.IR name .
|
|
.
|
|
.
|
|
.P
|
|
Note that
|
|
.I troffrc
|
|
and
|
|
.I troffrc\-end
|
|
are searched for neither in the current nor the home directory by
|
|
default for security reasons (even if the
|
|
.B \-U
|
|
option is given).
|
|
.
|
|
Use the
|
|
.B \-M
|
|
command-line option or the
|
|
.I GROFF_TMAC_PATH
|
|
environment variable to add these directories to the search path if
|
|
necessary.
|
|
.
|
|
.
|
|
.\" ====================================================================
|
|
.SH AUTHORS
|
|
.\" ====================================================================
|
|
.
|
|
The GNU version of
|
|
.I troff
|
|
was originally written by James Clark;
|
|
he also wrote the original version of this document,
|
|
which was modified by
|
|
.MT wl@\:gnu.org
|
|
Werner Lemberg
|
|
.ME
|
|
and
|
|
.MT groff\-bernd.warken\-72@\:web.de
|
|
Bernd Warken
|
|
.ME .
|
|
.
|
|
.
|
|
.\" ====================================================================
|
|
.SH "SEE ALSO"
|
|
.\" ====================================================================
|
|
.
|
|
.TP
|
|
.BR groff (1)
|
|
The main program of the
|
|
.I groff
|
|
system, a wrapper around
|
|
.IR troff .
|
|
.
|
|
.TP
|
|
.BR groff (7)
|
|
A description of the
|
|
.I groff
|
|
language, including a short but complete reference of all predefined
|
|
requests, registers, and escapes of plain
|
|
.IR groff .
|
|
.
|
|
From the command line, this is called by
|
|
.RS
|
|
.IP
|
|
.B man 7 groff
|
|
.RE
|
|
.
|
|
.TP
|
|
.BR \%groff_diff (7)
|
|
The differences of the
|
|
.I groff
|
|
language and the
|
|
.I classical troff
|
|
language.
|
|
.
|
|
Currently, this is the most actual document of the
|
|
.I groff
|
|
system.
|
|
.
|
|
.TP
|
|
.BR roff (7)
|
|
An overview over
|
|
.I groff
|
|
and other
|
|
.I roff
|
|
systems, including pointers to further related documentation.
|
|
.
|
|
.
|
|
.P
|
|
.IR "Groff: The GNU Implementation of troff" ,
|
|
by Trent A.\& Fisher and Werner Lemberg,
|
|
is the primary
|
|
.I groff
|
|
manual.
|
|
.
|
|
You can browse it interactively with \(lqinfo groff\(rq.
|
|
.
|
|
.
|
|
.\" ====================================================================
|
|
.\" Emacs variables
|
|
.\" ====================================================================
|
|
.
|
|
.\" Local Variables:
|
|
.\" mode: nroff
|
|
.\" End:
|
|
.\" vim: set filetype=groff:
|