troff.man

早期freebsd实现

when reread, will cause the contents of
.I filename
to be transparently copied through to the output.
In Unix troff, the
contents of
.I filename
is immediately copied through to the output regardless of whether
there is a current diversion; this behavior is so anomalous that it
must be considered a bug.
.TP
.BI .ev\  xx
If
.I xx
is not a number, this will switch to a named environment called
.IR xx .
The environment should be popped with a matching
.B ev
request without any arguments, just as for numbered environments.
There is no limit on the number of named environments; they will be
created the first time that they are referenced.
.TP
.BI .fp\  n\ f1\ f2
The
.B fp
request has an optional third argument.
This argument gives the external name of the font,
which is used for finding the font description file.
The second argument gives the internal name of the font
which is used to refer to the font in troff after it has been mounted.
If there is no third argument then the internal name will be used
as the external name.
This feature allows you to use fonts with long names in compatibility mode.
.TP
.BI .ss\  m\ n
When two arguments are given to the
.B ss
request, the second argument gives the
.IR "sentence space size" .
If the second argument is not given, the sentence space size
will be the same as the word space size.
Like the word space size, the sentence space is in units of
one twelfth of the spacewidth parameter for the current font.
Initially both the word space size and the sentence
space size are 12.
The sentence space size is used in two circumstances:
if the end of a sentence occurs at the end of a line in fill mode, then
both an inter-word space and a sentence space will be added;
if two spaces follow the end of a sentence in the middle of a line,
then the second space will be a sentence space.
Note that the behaviour of Unix troff will be exactly
that exhibited by GNU troff if a second argument is never given to the
.B ss
request.
In GNU troff, as in Unix troff, you should always
follow a sentence with either a newline or two spaces.
.TP
.BI .ta\  n1\ n2\|.\|.\|.nn \ T\  r1\ r2\|.\|.\|.\|rn
Set tabs at positions
.IR n1 ,
.IR n2 ,\|.\|.\|.\|,
.I nn
and then set tabs at
.IR nn + r1 ,
.IR nn + r2 ,\|.\|.\|.\|.\|,
.IR nn + rn
and then at
.IR nn + rn + r1 ,
.IR nn + rn + r2 ,\|.\|.\|.\|,
.IR nn + rn + rn ,
and so on.
For example,
.RS
.IP
.B
\&.ta T .5i
.LP
will set tabs every half an inch.
.RE
.SS New number registers
The following read-only registers are available:
.TP
.B \en[.C]
1 if compatibility mode is in effect, 0 otherwise.
.TP
.B \en[.cdp]
The depth of the last character added to the current environment.
It is positive if the character extends below the baseline.
.TP
.B \en[.ce]
The number of lines remaining to be centered, as set by the
.B ce
request.
.TP
.B \en[.cht]
The height of the last character added to the current environment.
It is positive if the character extends above the baseline.
.TP
.B \en[.csk]
The skew of the last character added to the current environment.
The
.I skew
of a character is how far to the right of the center of a character
the center of an accent over that character should be placed.
.TP
.B \en[.ev]
The name or number of the current environment.
This is a string-valued register.
.TP
.B \en[.fam]
The current font family.
This is a string-valued register.
.TP
.B \en[.fp]
The number of the next free font position.
.TP
.B \en[.g]
Always 1.
Macros should use this to determine whether they are running
under GNU troff.
.TP
.B \en[.hla]
The current hyphenation language as set by the
.B hla
request.
.TP
.B \en[.hlc]
The number of immediately preceding consecutive hyphenated lines.
.TP
.B \en[.hlm]
The maximum allowed number of consecutive hyphenated lines, as set by the
.B hlm
request.
.TP
.B \en[.hy]
The current hyphenation flags (as set by the
.B hy
request.)
.TP
.B \en[.hym]
The current hyphenation margin (as set by the
.B hym
request.)
.TP
.B \en[.hys]
The current hyphenation space (as set by the
.B hys
request.)
.TP
.B \en[.in]
The indent that applies to the current output line.
.TP
.B \en[.kern]
.B 1
if pairwise kerning is enabled,
.B 0
otherwise.
.TP
.B \en[.lg]
The current ligature mode (as set by the
.B lg
request.)
.TP
.B \en[.ll]
The line length that applies to the current output line.
.TP
.B \en[.lt]
The title length as set by the
.B lt
request.
.TP
.B \en[.ne]
The amount of space that was needed in the last
.B ne
request that caused a trap to be sprung.
Useful in conjunction with the
.B \en[.trunc]
register.
.TP
.B \en[.pn]
The number of the next page:
either the value set by a
.B pn
request, or the number of the current page plus 1.
.TP
.B \en[.ps]
The current pointsize in scaled points.
.TP
.B \en[.psr]
The last-requested pointsize in scaled points.
.TP
.B \en[.rj]
The number of lines to be right-justified as set by the
.B rj
request.
.TP
.B \en[.sr]
The last requested pointsize in points as a decimal fraction.
This is a string-valued register.
.TP
.B \en[.tabs]
A string representation of the current tab settings suitable for use as
an argument to the
.B ta
request.
.TP
.B \en[.trunc]
The amount of vertical space truncated by the most recently sprung
vertical position trap, or,
if the trap was sprung by a
.B ne
request,
minus the amount of vertical motion produced by the
.B ne
request.
In other words, at the point a trap is sprung, it represents the difference
of what the vertical position would have been but for the trap,
and what the vertical position actually is.
Useful in conjunction with the
.B \en[.ne]
register.
.TP
.B \en[.ss]
.TQ
.B \en[.sss]
These give the values of the parameters set by the
first and second arguments of the
.B ss
request.
.TP
.B \en[.vpt]
1 if vertical position traps are enabled, 0 otherwise.
.TP
.B \en[.warn]
The sum of the numbers associated with each of the currently enabled
warnings.
The number associated with each warning is listed in the `Warnings'
subsection.
.TP
.B \en(.x
The major version number.
For example, if the version number is
.B 1.03
then
.B \en(.x
will contain
.BR 1 .
.TP
.B \en(.y
The minor version number.
For example, if the version number is
.B 1.03
then
.B \en(.y
will contain
.BR 03 .
.LP
The following registers are set by the
.B \ew
escape sequence:
.TP
.B \en[rst]
.TQ
.B \en[rsb]
Like the
.B st
and
.B sb
registers, but takes account of the heights and depths of characters.
.TP
.B \en[ssc]
The amount of horizontal space (possibly negative) that should
be added to the last character before a subscript.
.TP
.B \en[skw]
How far to right of the center of the last character
in the
.B \ew
argument,
the center of an accent from a roman font should be placed over that character.
.LP
The following read/write number registers are available:
.TP
.B \en[systat]
The return value of the system() function executed by the last
.B sy
request.
.TP
.B \en[slimit]
If greater than 0, the maximum number of objects on the input stack.
If less than or equal to 0, there is no limit on the number of objects
on the input stack.  With no limit, recursion can continue until
virtual memory is exhausted.
.SS Miscellaneous
.LP
Fonts not listed in the
.SM DESC
file are automatically mounted on the next available font position
when they are referenced.
If a font is to be mounted explicitly with the
.B fp
request on an unused font position,
it should be mounted on the first unused font position,
which can be found in the
.B \en[.fp]
register;
although
.B troff
does not enforce this strictly,
it will not allow a font to be mounted at a position whose number is much
greater than that of any currently used position.
.LP
Interpolating a string does not hide existing macro arguments.
Thus in a macro, a more efficient way of doing
.IP
.BI . xx\  \e\e$@
.LP
is
.IP
.BI \e\e*[ xx ]\e\e  
.LP
If the font description file contains pairwise kerning information,
characters from that font will be kerned.
Kerning between two characters can be inhibited by placing a
.B \e&
between them.
.LP
In a string comparison in a condition, 
characters that appear at different input levels
to the first delimiter character will not be recognized
as the second or third delimiters.
This applies also to the
.B tl
request.
In a
.B \ew
escape sequence,
a character that appears at a different input level to
the starting delimiter character will not be recognised
as the closing delimiter character.
When decoding a macro argument that is delimited
by double quotes, a character that appears at a different
input level to the starting delimiter character will not
be recognised as the closing delimiter character.
The implementation of
.B \e$@
ensures that the double quotes surrounding an argument
will appear at the same input level, which will be different
to the input level of the argument itself.
In a long escape name
.B ]
will not be recognized as a closing delimiter except
when it occurs at the same input level as the opening
.BR ] .
In compatibility mode, no attention is paid to the input-level.
.LP
There are some new types of condition:
.TP
.BI .if\ r xxx
True if there is a number register named
.IR xxx .
.TP
.BI .if\ d xxx
True if there is a string, macro, diversion, or request named
.IR xxx .
.TP
.BI .if\ c ch
True if there is a character
.IR ch
available;
.I ch
is either an
.SM ASCII
character
or a special character
.BI \e( xx
or
.BI \e[ xxx ]\fR;
the condition will also be true if
.I ch
has been defined by the
.B char
request.
.SS 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.
.nr x \w'\fBright-brace'+1n+\w'0000'u
.ta \nxuR
.TP \nxu+3n
.BR char \t1
Non-existent characters.
This is enabled by default.
.TP
.BR number \t2
Invalid numeric expressions.
This is enabled by default.
.TP
.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 delim \t8
Missing or mismatched closing delimiters.
.TP
.BR el \t16
Use of the
.B el
request with no matching
.B ie
request.
.TP
.BR scale \t32
Meaningless scaling indicators.
.TP
.BR range \t64
Out of range arguments.
.TP
.BR syntax \t128
Dubious syntax in numeric expressions.
.TP
.BR di \t256
Use of
.B di
or
.B da
without an argument when there is no current diversion.
.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 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.
a definition is automatically made with a value of 0.
So, in most cases, at most one warning will be given for
use of a particular name.
.TP
.BR tab \t2048
Use of a tab character where a number was expected.
.TP
.BR right-brace \t4096
Use of
.B \e}
where a number was expected.
.TP
.BR missing \t8192
Requests that are missing non-optional arguments.
.TP
.BR input \t16384
Illegal input characters.
.TP
.BR escape \t32768
Unrecognized escape sequences.
When an unrecognized escape sequence is encountered,
the escape character is ignored.
.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 font \t131072
Non-existent fonts.
This is enabled by default.
.LP
There are also names that can be used to refer to groups of warnings:
.TP
.B all
All warnings except
.BR di ,
.B mac
and
.BR reg .
It is intended that this covers all warnings
that are useful with traditional macro packages.
.TP
.B w
All warnings.
.SS Incompatibilities
.LP
Long names cause some incompatibilities.
Unix troff will interpret
.IP
.B
\&.dsabcd
.LP
as defining a string
.B ab
with contents
.BR cd .
Normally, GNU troff will interpret this as a call of a macro named
.BR dsabcd .
Also Unix troff will interpret
.B \e*[
or
.B \en[
as references to a string or number register called
.BR [ .
In GNU troff, however, this will normally be interpreted as the start
of a long name.
In
.I compatibility mode
GNU troff will interpret these things in the traditional way.
In compatibility mode, however, long names are not recognised.
Compatibility mode can be turned on with the
.B \-C
command line option, and turned on or off with the
.B cp
request.
The number register
.B \en(.C
is 1 if compatibility mode is on, 0 otherwise.
.LP
GNU troff
does not allow the use of the escape sequences
.BR \\e\e|\e^\e&\e}\e{\e (space) \e'\e`\e-\e_\e!\e%\ec
in names of strings, macros, diversions, number registers,
fonts or environments; Unix troff does.
The
.B \eA
escape sequence may be helpful in avoiding use of these
escape sequences in names.
.LP
Fractional pointsizes cause one noteworthy incompatibility.
In Unix troff the
.B ps 
request ignores scale indicators and so
.IP
.B .ps\ 10u
.LP
will set the pointsize to 10 points, whereas in
GNU troff it will set the pointsize to 10 scaled points.
.LP
In GNU troff there is a fundamental difference between unformatted,
input characters, and formatted, output characters.
Everything that affects how an output character
will be output is stored with the character; once an output
character has been constructed it is unaffected by any subsequent
requests that are executed, including
.BR bd ,
.BR cs ,
.BR tkf ,
.BR tr ,
or
.B fp
requests.
Normally output characters are constructed from input
characters at the moment immediately before the character
is added to the current output line.
Macros, diversions and strings are all, in fact, the same type
of object; they contain lists of input characters and output
characters in any combination.
An output character does not behave like an input character
for the purposes of macro processing; it does not inherit any
of the special properties that the input character from which it
was constructed might have had.
For example,
.IP
.nf
.ft B
\&.di x
\e\e\e\e
\&.br
\&.di
\&.x
.ft
.fi
.LP
will print
.B \e\e
in GNU troff;
each pair of input
.BR \e s
is turned into one output
.B \e
and the resulting output
.BR \e s
are not interpreted as escape characters when they are reread.
Unix troff would interpret them as escape characters
when they were reread and would end up printing one
.BR \e .
The correct way to obtain a printable
.B \e
is to use the
.B \ee
escape sequence: this will always print a single instance of the
current escape character, regardless of whether or not it is used in a
diversion; it will also work in both GNU troff and Unix troff.
If you wish for some reason to store in a diversion an escape
sequence that will be interpreted when the diversion is reread,
you can either use the traditional
.B \e!
transparent output facility, or, if this is unsuitable, the new
.B \e?
escape sequence.
.SH ENVIRONMENT
.TP
.SM
.B GROFF_TMAC_PATH
A colon separated list of directories in which to search for
macro files.
.TP
.SM
.B GROFF_TYPESETTER
Default device.
.TP
.SM
.B GROFF_FONT_PATH
A colon separated list of directories in which to search for the
.BI dev name
directory.
.B troff
will search in directories given in the
.B \-F
option before these, and in standard directories
.RB ( @FONTPATH@ )
after these.
.SH FILES
.Tp \w'@FONTDIR@/devname/DESC'u+3n
.B @MACRODIR@/troffrc
Initialization file
.TP
.BI @MACRODIR@/tmac. name
Macro files
.TP
.BI @FONTDIR@/dev name /DESC
Device description file for device
.IR name .
.TP
.BI @FONTDIR@/dev name / F
Font file for font
.I F
of device
.IR name .
.SH "SEE ALSO"
.BR groff (@MAN1EXT@)
.BR @g@tbl (@MAN1EXT@),
.BR @g@pic (@MAN1EXT@),
.BR @g@eqn (@MAN1EXT@),
.BR grops (@MAN1EXT@),
.BR grodvi (@MAN1EXT@),
.BR grotty (@MAN1EXT@),
.BR groff_font (@MAN5EXT@),
.BR groff_out (@MAN5EXT@),
.BR groff_char (@MAN7EXT@)