| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This chapter covers all of the facilities of gtroff.
Users of macro packages may skip it if not interested in details.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gtroff input files contain text with control commands
interspersed throughout. But, even without control codes, gtroff
will still do several things with the input text: filling and adjusting,
adding additional space after sentences, hyphenating and inserting
implicit line breaks.
5.1.1 Filling and Adjusting 5.1.2 Hyphenation 5.1.3 Sentences 5.1.4 Tab Stops 5.1.5 Implicit Line Breaks
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When gtroff reads in text it collects words from input and fits
as many of them together on one output line as it can. This is known as
filling.
Once gtroff has a filled line it will try to adjust
it. This means it will widen the spacing between words until the text
reaches the right margin (in the default adjustment mode). Extra spaces
between words are preserved, but spaces at the end of lines are ignored.
Spaces at the front of a line will cause a break (breaks will be
explained in 5.1.5 Implicit Line Breaks)
See section 5.8 Manipulating Filling and Adjusting.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Since the odds are not great for finding a set of words, for every
output line, which will fit nicely on a line without inserting excessive
amounts of space between words, gtroff will hyphenate words so
that lines can be justified without there being too much space between
words. It uses an internal hyphenation algorithm (a simplified version
of the algorithm used within TeX) to indicate which words can be
hyphenated and how to do so. When a word is hyphenated the first part
of the word will be added to the current filled line being output (with
an attached hyphen), and the other portion will be added to the next
line to be filled.
See section 5.9 Manipulating Hyphenation.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Although it is often debated, some typesetting rules say there should be different amounts of space after various punctuation marks. For example, the Chicago typsetting manual says that a period at the end of a sentence should have twice as much space following it as would a comma or a period as part of an abbreviation.
gtroff does this by flagging certain characters (normally
`!', `?' and `.') as end of sentence characters.
When gtroff encounters one of these characters at the end of a
line it will append two sentence spaces in the formatted output.
(This justifies one of the conventions mentioned in 5.2 Input Conventions.)
In addition, the following characters resp. glyphs are treated
transparently while handling end of sentence characters: `"',
`'', `)', `]', `*', dg, and rq.
See the cflags request in 5.17.4 Using Symbols, for more details.
To prevent the insertion of extra space after an end of sentence
character (at the end of a line), append \&.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gtroff translates tabulator characters, also called
tabs (normally code point ASCII 0x09 resp.
EBCDIC 0x05), in the input into movements to the next
tabulator stop. These tab stops are initially located every half inch
across the page. Using this, simple tables can easily be made.
However, it can often be deceptive as the appearance (and width) of the
text on a terminal and the results from gtroff can vary greatly.
Also, a possible sticking point is that lines beginning with tab characters will still be filled, again producing unexpected results. For example, the following input
| 1 | 2 | 3 | |
| 4 | 5 |
will produce
| 1 | 2 | 3 | 4 | 5 |
See section 5.11 Tabs and Fields.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
An important concept in gtroff is the break. When a break
occurs, gtroff will output the partially filled line
(unjustified), and resume collecting and filling text on the next output
line.
There are several ways to cause a break in gtroff. A blank line
will not only cause a break, but it will also cause a one line vertical
space (effectively a blank line) to be output.
A line which begins with a space will cause a break and the space will be output at the beginning of the next line. Note that this space isn't adjusted, even in fill mode.
The end of file will also cause a break -- otherwise the last line of the document may vanish!
Certain requests also cause breaks, implicitly or explicitly. This will be discussed in 5.8 Manipulating Filling and Adjusting.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Since gtroff does filling automatically, it is traditional in
groff not to try and type things in as nicely formatted
paragraphs. These are some conventions commonly used when typing
gtroff text:
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gtroff (like any other programs) requires numeric parameters to
specify various measurements. Most numeric parameters(4) may have a
measurement unit attached. These units are specified as a single
character which immediately follows the number or expression. Each of
these units are understood, by gtroff, to be a multiple of its
basic unit. So, whenever a different measurement unit is
specified gtroff converts this into its basic units. This
basic unit, represented by a `u', is a device dependent measurement
which is quite small, ranging from 1/75th to 1/72000th of an inch. The
values may be given as fractional numbers; however, fractional basic
units are always rounded to integers.
Some of the measurement units are completely independent of any of the
current settings (e.g. type size) of gtroff.
i
c
p
P
s
z
The other measurements understood by gtroff are dependent on
settings currently in effect in gtroff. These are very useful
for specifying measurements which should look proper with any size of
text.
m
n
v
M
5.3.1 Default Units
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Many requests take a default unit. While this can be helpful at times, it can cause strange errors in some expressions. For example, the line length request expects em units. Here are several attempts to get a line length of 3.5 inches and their results:
3.5i => 3.5i 7/2 => 0i 7/2i => 0i 7i/2 => 0.1i 7i/2u => 3.5i |
Everything will be converted to basic units first. In the above example it is assumed that 1i equals 240u, and 1m equals 10p (thus 1m equals 33u). The value 7i/2 will be first handled as 7i/2m, then converted to 1680u/66u which is 25u, and this is approximately 0.1i.
As a conclusion, the safest way to specify measurements is to always attach a scaling indicator. If you want to multiply or divide by a certain scalar value, use `u' as the unit for that value.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gtroff has most of operators common to other languages:
gtroff only provides integer arithmetic. The internal type used
for computing results is `int', which is usually a 32bit
signed integer.
if and while requests). See
below for the use of unary operators in motion requests.
(c;e). Evaluate e using c as
the default scaling indicator. If c is missing, ignore scaling
indicators in the evaluation of e.
Parentheses may be used as in any other language. However, in
gtroff they are necessary to ensure order of evaluation.
gtroff has no operator precedence; expressions are evaluated left
to right. This means that `3+5*4' is evaluated as if it were
parenthesized like `(3+5)*4', not as `3+(5*4)', as might be
expected.
For many requests which cause a motion on the page, the unary operators
work differently. The `+' and `-' operators then indicate a
motion relative to the current position (down or up, respectively), and
the `|' operator indicates an absolute position on the page or
input line.
`+' and `-' are also treated differently by the following
requests and escapes: bp, in, ll, lt,
nm, nr, pl, pn, po, ps,
rt, ti, \R, and \s. Here the plus and minus
signs indicate increments resp. decrements.
See section 5.7.1 Setting Registers.
Due to the way arguments are parsed, spaces are not allowed in expressions, unless the entire expression is surrounded by parentheses.
See section 5.6.1.1 Request Arguments, and 5.20 Conditionals and Loops.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Like any other language, gtroff has rules for properly formed
identifiers. In gtroff, an identifier can be made up of
almost any printable character, with the exception of the following
characters:
0x08 resp. EBCDIC
0x16) and character code 0x01.
groff runs on a machine based on ASCII, causing a
warning message of type `input' (see 5.30 Debugging, for more
details): 0x00, 0x0B, 0x0D-0x1F,
0x80-0x9F.
And here are the invalid input characters if groff runs on an
EBCDIC host: 0x00, 0x08, 0x09,
0x0B, 0x0D-0x14, 0x17-0x1F,
0x30-0x3F.
Currently, some of these reserved codepoints are used internally, thus
making it non-trivial to extend gtroff to cover Unicode or other
character sets resp. encodings which use characters of these ranges.
Note that invalid characters will be removed before parsing; an
identifier foo, followed by an invalid character, followed by
bar will be treated as foobar.
For example, any of the following is valid.
br PP (l end-list @_ |
Note that identifiers longer than two characters with a closing bracket (`]') in its name can't be accessed with escape sequences which expect an identifier as a parameter. For example, `\[foo]]' will access the glyph `foo', followed by `]', whereas `\C'foo]'' really asks for glyph `foo]'.
gtroff can be
tested with the \A escape. It expands to the character 1
or 0 according to whether its argument (usually delimited by quotes)
is or is not acceptable as the name of a string, macro, diversion,
number register, environment, or font. It will return 0 if no
argument is given. This is useful for looking up user input in some
sort of associative table.
\A'end-list'
=> 1
|
See section 5.6.3 Escapes, for details on parameter delimiting characters.
Identifiers in gtroff can be any length, but, in some contexts,
gtroff needs to be told where identifiers end and text begins
(and in different ways depending on their length):
gtroff only). Must be bracketed with `['
and `]' in some situations. Any length identifier can be put
in brackets.
Unlike many other programming languages, undefined identifiers are silently ignored or expanded to nothing.
See section 5.7.2 Interpolating Registers, and 5.19 Strings.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Most documents need more functionality beyond filling, adjusting and
implicit line breaking. In order to gain further functionality,
gtroff allows commands to be embedded into the text, in two ways.
The first is a request which takes up an entire line, and does some large scale operation (e.g. break lines, start new pages).
The other is an escape which can be embedded anywhere in the text, or even as an argument to a request. Escapes generally do more minor operations like sub- and superscripts, print a symbol, etc.
5.6.1 Requests 5.6.2 Macros 5.6.3 Escapes
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A request line begins with a control character, which is either a single quote (`'', the no-break control character) or a period (`.', the normal control character). These can be changed; see 5.12 Character Translations, for details. After this there may be optional tabs or spaces followed by an identifier which is the name of the request. This may be followed by any number of space-separated arguments.
To begin a line with a control character without it being interpreted,
precede it with \&. This represents a zero width space, which
means it will not affect the output.
In most cases the period is used as a control character. Several requests will cause a break implicitly; using the single quote control character will prevent this.
5.6.1.1 Request Arguments
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Arguments to requests (and macros) are processed much like the shell: The line is split into arguments according to spaces. An argument which is intended to contain spaces can either be enclosed in quotes (single or double), or have the spaces escaped with backslashes.
Here are a few examples:
.uh The Mouse Problem .uh "The Mouse Problem" .uh The\ Mouse\ Problem |
The first line is the uh macro being called with 3 arguments,
`The', `Mouse', and `Problem'. The latter two have the
same effect or calling the uh macro with one argument, `The
Mouse Problem'.(5)
Note, however, that the ds request works differently.
See section 5.19 Strings, for more details.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gtroff has a macro facility for defining a series of lines
which can be invoked by name. They are called in the same manner as
requests -- arguments also may be passed in the same manner.
See section 5.21 Writing Macros, and 5.6.1.1 Request Arguments.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Escapes may occur anywhere in the input to gtroff. They usually
begin with a backslash and are followed by a single character which
indicates the function to be performed. The escape character can be
changed; see 5.12 Character Translations.
Escape sequences which require an identifier as a parameter accept three possible syntax forms.
Examples:
\fB \n(XX \*[TeX] |
Other escapes may require several arguments and/or some special format. In such cases the argument is traditionally enclosed in single quotes (and quotes are always used in this manual for the definitions of escape sequences). The enclosed text is then processed according to what that escape expects. Example:
\l'1.5i\(bu' |
Note that the quote character can be replaced with any other character
which does not occur in the argument (even a newline or a space
character) in the following escapes: \o, \b, and
\X. This makes e.g.
A caf \o e\' in Paris => A café in Paris |
possible, but it is better not to use this feature to avoid confusion.
The following escapes sequences (which are handled similarly to
characters since they don't take a parameter) are also allowed as
delimiters: \%, `\ ', \|, \^, \{,
\}, \', \`, \-, \_, \!,
\?, \@, \), \/, \,, \&,
\~, \0, \a, \c, \d, \e,
\E, \p, \r, \t, and \u. Again, don't
use these if possible.
No newline characters as delimiters are allowed in the following
escapes: \A, \Z, \C, and \w.
Finally, the escapes \D, \h, \H, \l,
\L, \N, \R, \s, \S, \v, and
\x can't use the following characters as delimiters:
0-9.
\%, \{, \},
\', \`, \-, \_, \!, \@,
\/, \c, \e, and \p.
To have a backslash (resp. the current escape character) appear in the
output several escapes are defined: \\, \e or \E.
These are very similar, and only differ with respect to being used in
macros or diversions. See section 5.21.1 Copy-in Mode, and 5.25 Diversions, for
more information.
See section 5.5 Identifiers, and 5.12 Character Translations.
5.6.3.1 Comments
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Probably one of the most(6) common forms of escapes is the comment.
This may sound simple, but it can be tricky to keep the comments from interfering with the appearance of the final output.
If the escape is to the right of some text or a request, that portion of
the line will be ignored, but the space leading up to it will be noticed
by gtroff. This only affects the .ds request.
One possibly irritating idiosyncracy is that tabs must not be used to line up comments. Tabs are not treated as white space between the request and macro arguments.
A comment on a line by itself will be treated as a blank line, because after eliminating the comment, that is all that remains:
Test \" comment Test |
will produce
Test Test |
As a consequence, it is common to start the line with .\" which
will cause the line to be treated as an undefined request and thus
ignored completely.
Another commenting scheme seen sometimes is three consecutive single
quotes ("') at the beginning of a line. This works, but
gtroff will give a warning about an undefined macro (namely
"), which is harmless, but irritating.
gtroff has a new comment mechanism using
the \# escape. This escape works the same as \" except
that the newline is also ignored:
Test \# comment Test |
will produce
Test Test |
as expected.
For commenting away large blocks of text, the ig request may be
useful.
See section 5.19 Strings.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Numeric variables in gtroff are called registers. There
are a number of built-in registers, supplying anything from the date to
details of formatting parameters.
See section 5.5 Identifiers, for details on register identifiers.
5.7.1 Setting Registers 5.7.2 Interpolating Registers 5.7.3 Auto-increment 5.7.4 Assigning Formats 5.7.5 Built-in Registers
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Registers are defined resp. set via the nr request or the
\R escape.
The argument to \R has to be enclosed in quotes usually.
See section 5.6.3 Escapes, for details on parameter delimiting characters.
For example, the following two lines are equivalent:
.nr a 1 \R'a 1' |
Both nr and \R have two additional special forms to
increment resp. decrement a register.
.nr a 1
.nr a +1
\na
=> 2
|
To assign the negated value of a register to another register, some care must be taken to get the desired result:
.nr a 7
.nr b 3
.nr a -\nb
\na
=> 4
.nr a (-\nb)
\na
=> -3
|
The surrounding parentheses prevent the interpretation of the minus sign as a decrementing operator. An alternative is to start the assignment with a `0':
.nr a 7
.nr b -3
.nr a \nb
\na
=> 4
.nr a 0\nb
\na
=> -3
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Numeric registers can be accessed via the \n escape.
gtroff is parsing the
input line.
.nr a 5
.nr as \na+\na
\n(as
=> 10
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Number registers can also be auto-incremented and auto-decremented. The
increment resp. decrement factor can be specified with a third
argument to the nr request or \R escape.
\R escape
doesn't support this notation.
To activate auto-incrementing, the escape \n has a special syntax
form.
nr request (or the
\R escape). If no auto-increment value has been specified, both
syntax forms are identical to \n.
For example,
.nr a 0 1 .nr xx 0 5 .nr foo 0 -2 \n+a, \n+a, \n+a, \n+a, \n+a .br \n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx .br \n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo] |
produces
1, 2, 3, 4, 5 -5, -10, -15, -20, -25 -2, -4, -6, -8, -10 |
To change the increment value without changing the value of a register, the following can be used:
.nr a \na 10 |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When a register is used in the text of an input file (as opposed to part
of an expression), it is textually replaced (or interpolated) with a
representation of that number. This output format can be changed to a
variety of formats (numbers, Roman numerals, etc.). This is done using
the af request.
1
0...0
In fact, any digit instead of zero will do; gtroff only counts
how many digits are specified. As a consequence, af's default
format `1' could be specified as `0' also (and exactly this is
returned by the \g escape, see below).
I
i
A
a
Omitting the number register format will cause a warning of type `missing'. See section 5.30 Debugging, for more details. Specifying a nonexistent format causes an error.
The following example will produce `10, X, j, 010':
.nr a 10 .af a 1 \" the default format \na, .af a I \na, .af a a \na, .af a 001 \na |
The largest number representable for the `i' and `I' formats
is 39999 (resp. -39999); UNIX troff uses `z' and
`w' to represent 10000 and 5000 in Roman numerals, and so does
gtroff. Currently, the correct glyphs of Roman numeral five
thousand and Roman numeral ten thousand (Unicode code points
U+2182 and U+2181, respectively) are not available.
If ident doesn't exist, it will be created.
Changing the output format of a read-only register causes an error. It
is necessary to first copy the register's value to a writeable register,
then apply the af request to this other register.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following lists some built-in registers which are not described elsewhere in this manual. Any register which begins with a `.' is read-only. A complete listing of all built-in registers can be found in 12. Register Index.
.H
.V
dw
dy
mo
year
yr
troff had a year 2000 bug: It
incorrectly claimed that yr contains the last two digits of the
year. That claim has never been true of either traditional troff
or GNU troff. Old troff input that looks like this:
'\" The following line stopped working after 1999 This document was formatted in 19\n(yr. |
can be corrected as follows:
This document was formatted in \n[year]. |
or, to be portable to older troff versions, as follows:
.nr y4 1900+\n(yr This document was formatted in \n(y4. |
.c
c.
gtroff extension) is writable also,
affecting both `.c' and `c.'.
ln
nm
request to activate line numbering.
.x
.x will contain `1'.
.y
.y will contain `03'.
.Y
groff.
.g
troff.
.A
.P
.T
gtroff is called with the `-T' command line option, the
number register .T is set to 1, and zero otherwise.
See section 2.1 Options.
Additionally, gtroff predefines a single (read/write) string
register .T which contains the current output device (for
example, `latin1' or `ps').
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Various ways of causing breaks were given in 5.1.5 Implicit Line Breaks. The br request will likewise cause a break. Several
other requests will also cause breaks, but implicitly. These are
bp, ce, cf, fi, fl, in,
nf, rj, sp, ti, and trf.
If the no-break control character is used, no break will happen:
a
'br
b
=> a b
|
Initially, gtroff will fill and adjust text to both margins.
Filling can be disabled via the nf request and re-enabled with
the fi request.
.u is set to 1.
The fill mode status is associated with the current environment (see section 5.26 Environments).
.u will be set to 0.
The fill mode status is associated with the current environment (see section 5.26 Environments).
Activation and deactivation of adjusting will be implicitly done with
calls to the fi resp. nf requests.
mode can have one of the following values:
l
r
c
ce request which
only centers text without filling.
b
n
gtroff.
With no argument, gtroff will adjust lines in the same way it did
before adjusting has been deactivated (with a call to na, for
example).
text .ad r text .ad c text .na text .ad \" back to centering text |
The current adjustment mode is available in the number register
.j; it can be stored and subsequently used to set adjustment.
The adjustment mode status is associated with the current environment (see section 5.26 Environments).
ad afterwards will use the previous adjustment
setting.
The adjustment mode status is associated with the current environment (see section 5.26 Environments).
In most cases this will produce very ugly results, since gtroff
doesn't have a sophisticated paragraph building algorithm (as TeX
does, for example); instead, gtroff fills and adjusts a paragraph
line by line:
This is an uninteresting sentence. This is an uninteresting sentence.\p This is an uninteresting sentence. |
is formatted as
This is an uninteresting sentence. This is an uninteresting sentence. This is an uninteresting sentence. |
If two arguments are given to the ss request, the second argument
sets the sentence space size. If the second argument is not given,
sentence space size will be set to word_space_size. 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 ss request. In GNU troff, as in UNIX
troff, a sentence should always be followed by either a newline
or two spaces.
The number registers .ss and .sss hold the values of the
parameters set by the first and second arguments of the ss
request.
The word space and sentence space values are associated with the current environment (see section 5.26 Environments).
This request is ignored in nroff mode; it is also ignored if there is no parameter.
ce will not fill the
text it affects. This request causes a break.
With no arguments, ce will center the next line of text.
nnn specifies the number of lines to be centered. If
the argument is zero or negative, centering is disabled.
The basic length for centering text is the line length (as set with the
ll request) minus the indentation (as set with the in
request). Temporary indentation is ignored.
A common idiom is to turn on centering for a large number of lines, and to turn off centering after text to be centered. This is useful for any request which takes a number of lines as an argument.
.ce 1000 replace this with something more interesting ... .ce 0 |
The .ce number register contains the number of lines remaining to
be centered, as set by the ce request.
ce request. The .rj number register is the number of
lines to be right-justified as set by the rj request. This
request causes a line break.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
As discussed in 5.1.2 Hyphenation, gtroff will hyphenate words.
There are a number of ways to influence hyphenation.
1
gtroff.
2
4
8
Values in the previous table are additive. For example, the value
12 causes gtroff to neither hyphenate the last two nor the first
two characters of a word.
The current hyphenation restrictions can be found in the number register `.hy'.
The hyphenation mode is associated with the current environment (see section 5.26 Environments).
hy is not remembered.
The hyphenation mode is associated with the current environment (see section 5.26 Environments).
\% are counted; explicit hyphens are not.
The current setting of hlm is available in the .hlm
register. Also the number of immediately preceding consecutive
hyphenated lines are available in the number register `.hlc'.
.hw in-sa-lub-rious |
Besides the space character, any character whose hyphenation code value
is zero can be used to separate the arguments of hw (see the
documentation for the hcode request below for more information).
In addition, this request can be used more than once.
Hyphenation exceptions specified with the hw request are
associated with the current hyphenation language; it will cause an error
if there is no current hyphenation language.
This request is ignored if there is no parameter.
In old versions of troff there was a limited amount of space to
store such information; fortunately, with gtroff, this is no
longer a restriction.
gtroff how to hyphenate words on the fly, the \%
escape, also known as the hyphenation character, can be used.
Preceding a word with this character will prevent it from being
hyphenated, putting it in a word will indicate to gtroff that the
word may be hyphenated at that point. Note that this mechanism will
only affect that one occurrence of the word; to change the hyphenation
of a word for the entire document, use the hw request.
\% escape, and thus, no longer appear
in the output. Without an argument, hc will reset the
hyphenation character to be \% (the default) only.
The hyphenation character is associated with the current environment (see section 5.26 Environments).
It should have the same format as the argument to the \patterns
primitive in TeX (without using TeX's macro expansion); the
letters appearing in this file are interpreted as hyphenation codes. A
`%' character in the patterns file introduces a comment that
continues to the end of the line.
If no hpf request is specified (either in the document or in a
macro package), gtroff won't hyphenate at all.
The set of hyphenation patterns is associated with the current language
set by the hla request. The hpf request is usually
invoked by the `troffrc' or `troffrc-end' file; by default,
`troffrc' loads hyphenation patterns for American English (in file
`hyphen.us').
hpf will cause an error if there is no current hyphenation
language.
This request will be ignored if it has no parameter.
m. The hyphenation
margin is associated with the current environment
(see section 5.26 Environments).
A negative argument will reset the hyphenation margin to zero, emitting a warning of type `range'.
The current hyphenation margin is available in the .hym register.
m. The hyphenation space is associated
with the current environment (see section 5.26 Environments).
A negative argument will reset the hyphenation space to zero, emitting a warning of type `range'.
The current hyphenation space is available in the .hys register.
\(hy (this is the start-up value of gtroff also). The
soft hyphen character is the character which will be inserted when a
word is hyphenated at a line break. If the soft hyphen character does
not exist in the font of the character immediately preceding a potential
break point, then the line will not be broken at that point. Neither
definitions (specified with the char request) nor translations
(specified with the tr request) are considered when finding the
soft hyphen character.
hw request and
hyphenation patterns specified with the hpf request are both
associated with the current hyphenation language. The hla
request is usually invoked by the `troffrc' or the
`troffrc-end' files; `troffrc' sets the default language to
`us'.
The current hyphenation language is available as a string in the read-only number register `.hla'.
.ds curr_language \n[.hla]
\*[curr_language]
=> us
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gtroff to move up the page
the specified distance. If the argument is preceded by a `|'
gtroff will move that distance from the top of the page. This
request causes a line break. The default scaling indicator is
v.
gtroff will use the previous value before the last
ls call.
.ls 2 \" This causes double-spaced output .ls 3 \" This causes triple-spaced output .ls \" Again double spaced |
The line spacing is associated with the current environment (see section 5.26 Environments).
The number register .L contains the current line spacing setting.
\x
escape will do this. The escape is given a numerical argument, usually
enclosed in quotes (like `\x'3p''); the default scaling indicator
is v. If this number is positive extra vertical space will
be inserted below the current line. A negative number will add space
above. If this escape is used multiple times on the same line, the
maximum of the values is used.
See section 5.6.3 Escapes, for details on parameter delimiting characters.
The .a number register contains the most recent (nonnegative)
extra vertical line space.
sp
or via blank lines) is disabled. The bp request to advance to
the next page is also disabled, except if it is accompanied by a page
number (see 5.16 Page Control, for more information). This mode will
end when actual text is output or the rs request is encountered.
This request is useful for macros which want to avoid that subsequent macros inadvertently insert some vertical space before the text starts (for example, to set up the first paragraph after a section header). It is associated with the current diversion level.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A tab character (ASCII char 9, EBCDIC char 5) causes a horizontal movement to the next tab stop (much like it did on a typewriter).
\t is the same as a real tab character.
Tab stops can be specified absolutely, i.e., as the distance from the left margin. For example, the following will set 6 tab stops every one inch.
.ta 1i 2i 3i 4i 5i 6i |
Tab stops can also be specified relatively (using a leading `+') which means that the specified tab stop will be set that distance from the previous tab stop. For example, the following is equivalent to the previous example.
.ta 1i +1i +1i +1i +1i +1i |
gtroff supports an extended syntax to specify repeat values after
the `T' mark (these values are always taken as relative) -- this is
the usual way to specify tabs set at equal intervals. The following is,
yet again, the same as the previous examples. It does even more since
it defines an infinite number of tab stops separated by one inch.
.ta T 1i |
Now we are ready to interpret the full syntax given at the beginning: Set tabs at positions n1, n2, ..., nn and then set tabs at nn+r1, nn+r2, ..., nn+rn and then at nn+rn+r1, nn+rn+r2, ..., nn+rn+rn, and so on.
Example: `4c +6c T 3c 5c 2c' is equivalent to `4c 10c 13c 18c 20c 23c 28c 30c ...'.
The material in each tab column (i.e., the column between two tab stops) may be justified to the right or left or centered in the column. This is specified by appending `R', `L', or `C' to the tab specifier. The default justification is `L'. Example:
.ta 1i 2iC 2iR |
Some notes:
ta request is `m'.
.ds foo a\tb\tc .ta T 5i \*[foo] |
creates a single line which is a bit longer than 10 inches (a string is used to show exactly where the tab characters are). Now consider the following:
.ds bar a\tb b\tc .ta T 5i \*[bar] |
gtroff first converts the tab stops of the line into unbreakable
horizontal movements, then splits the line after the second `b'
(assuming a sufficiently short line length). Usually, this isn't what
the user wants.
.ds Z foo\tbar\tfoo .ds ZZ foo\tbar\tfoobar .ds ZZZ foo\tbar\tfoo\tbar .ta 2i 4iR \*[Z] .br \*[ZZ] .br \*[ZZZ] .br |
which produces the following output:
foo bar foo foo bar foobar foo bar foobar |
The first line right-justifies the second `foo' relative to the tab stop. The second line right-justifies `foobar'. The third line finally right-justifies only `foo' because of the additional tab character which marks the end of the string belonging to the last defined tab stop.
ta without an argument will unset all tab stops.
gtroff is `T 0.5i'. This value is
used even in nroff mode (contrary to UNIX nroff which
has tab stops preset every 0.8i).
The number register .tabs contains a string representation of the
current tab settings suitable for use as an argument to the ta
request.
.ds tab-string \n[.tabs]
\*[tab-string]
=> T120u
|
gtroff will fill the space to the next tab stop with
space. This can be changed with the tc request. With no
argument gtroff will revert to using space, which is the default.
The value of this tab repitition character is associated with the
current environment (see section 5.26 Environments).
5.11.1 Leaders 5.11.2 Fields
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Sometimes it may may be desirable to use the tc request to fill a
particular tab stop with a given character (for example dots in a table
of contents), but also normal tab stops on the rest of the line. For
this gtroff provides an alternate tab mechanism, called
leaders which will do just that.
A leader character (character code 1) behaves similarly to a tab character: It moves to the next tab stop. The only difference is that for this movement, the fill character defaults to a period character and not to space.
\a is the same as a real leader
character.
lc
request. Without an argument, leaders will act the same as tabs (i.e.,
using space for filling). gtroff's start-up value is `.'.
The value of this leader repitition character is associated with
the current environment (see section 5.26 Environments).
For a table of contents, to name an example, tab stops may be defined so that the section number is one tab stop, the title is the second with the remaining space being filled with a line of dots, and then the page number slightly separated from the dots.
.ds entry 1.1\tFoo\a\t12 .lc . .ta 1i 5i +.25i \*[entry] |
This produces
1.1 Foo.......................................... 12 |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Fields are a more general way of laying out tabular data. A field
is defined as the data between a pair of delimiting characters.
It contains substrings which are separated by padding characters.
The width of a field is the distance on the input line from the
position where the field starts to the next tab stop. A padding
character inserts stretchable space similar to TeX's \hss
command (thus it can even be negative) to make the sum of all substring
lengths plus the stretchable space equal to the field width. If more
than one padding character is inserted, the available space is evenly
distributed among them.
Example:
.fc # ^ .ta T 3i #foo^bar^smurf# .br #foo^^bar^smurf# |
and here the result:
foo bar smurf foo bar smurf |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The control character (`.') and the no-break control character
(`'') can be changed with the cc and c2 requests,
respectively.
This request can be very helpful in writing macros since it is not necessary then to double the escape character. Here an example:
.\" This is a simplified version of the
.\" .BR request from the man macro package
.eo
.de BR
. ds result \&
. while (\n[.$] >= 2) \{\
. as result \fB\$1\fR\$2
. shift 2
. \}
. if \n[.$] .as result \fB\$1
\*[result]
. ft R
..
.ec
|
eo request.
Note that changing the escape character globally will likely break macro
packages since gtroff has no mechanism (like TeX) to `intern'
macros, i.e., to convert a macro definition into an internal form which
is independent of its representation. If a macro is called, it will be
executed literally.
A translation is a mapping of an input character to an output
character. The default mappings are given in the font definition files
for the specific output device (see section 8.2 Font Files); all mappings (both
with tr and in the font definition files) occur at output time,
i.e., the input character gets assigned the metric information of the
mapped output character.
Some notes:
\(xx, \[xxx],
\C'xxx', \', \`, \-, \_),
characters defined with the char request, and numbered characters
(\N'xxx') can be translated also.
\e escape can be translated also.
\% escape (but \% can't
be mapped onto another character).
\a), tab (and
\t).
shc request.
.tr a\&
foo bar
=> foo br
|
It is even possible to map the space character to nothing:
.tr aa \&
foo bar
=> foobar
|
As shown in the example, the space character can't be the first
character pair as an argument of tr. Additionally, it is not
possible to map the space character to any other character; requests
like `.tr aa x' will undo `.tr aa \&' instead.
If justification is active, lines will be justified inspite of the `empty' space character (but there is no minimal distance, i.e. the space character, between words).
tr.
tr request is ignored.
trnt is the same as the tr request except that the
translations do not apply to text that is transparently throughput into
a diversion with \!. See section 5.25 Diversions, for more information.
For example,
.tr ab .di x \!.tm a .di .x |
will print `b'; if trnt is used instead of tr it will
print `a'.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Originally, nroff and troff were two separate programs,
the former for tty output, the latter for everything else. With GNU
troff, both programs are merged into one executable.
Usually, a macro package can be used with both nroff and
troff. Nevertheless, it is sometimes necessary to make a
distinction between the two programs (resp. modes), and gtroff
provides two built-in conditions `n' and `t' for the
if, ie, and while requests to decide whether
gtroff shall behave like nroff or like troff.
if, ie, and while conditional
requests. This is the default if gtroff (not
groff) is started with the `-R' switch to avoid loading of
the start-up files `troffrc' and `troffrc-end'. Without
`-R', gtroff stays in troff mode if the output device is
not a tty (e.g. `ps').
if, ie, and while conditional
requests. This is the default if gtroff uses a tty output
device; the code for switching to nroff mode is in the file
`tmac.tty' which will be loaded by the start-up file
troffrc.
See section 5.20 Conditionals and Loops, for more details on built-in conditions.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following drawing shows the dimensions which gtroff uses for
placing a line of output onto the page. They are labeled with the
request which manipulates each dimension.
-->| in |<--
|<-----------ll------------>|
+----+----+----------------------+----+
| : : : |
+----+----+----------------------+----+
-->| po |<--
|<--------paper width---------------->|
|
These dimensions are:
po
in
ll
.in +.5i .ll -.5i A bunch of really boring text which should be indented from both margins. Replace me with a better (and more) example! .in -.5i .ll +.5i |
m (and not
v as incorrectly documented in the original UNIX troff
manual).
The current page offset can be found in the built-in number register `.o'.
If po is called without an argument, the page offset is reset to
the previous value before the last call to po.
.po 3i
\n[.o]
=> 720
.po -1i
\n[.o]
=> 480
.po
\n[.o]
=> 720
|
If in is called without an argument, the indentation is reset to
the previous value before the last call to in. The default
scaling indicator is m.
The indentation is associated with the current environment.
If a negative indentation value is specified (which is not allowed),
gtroff emits a warning of type `range' and sets the
indentation to zero.
The effect of in is delayed until a partially collected line (if
it exists) is output.
The current indentation (as set by in) can be found in the
built-in number register `.i'.
in request.
This request causes a break; its value is associated with the current
environment. The default scaling indicator is m. A call of
ti without an argument is ignored.
If the total indentation value is negative (which is not allowed),
gtroff emits a warning of type `range' and sets the
temporary indentation to zero. `Total indentation' is either
offset if specified as an absolute value, or the temporary plus
normal indentation, if offset is given as a relative value.
The effect of ti is delayed until a partially collected line (if
it exists) is output.
The number register .in is the indentation that applies to the
current output line.
The difference between .i and .in is that the latter takes
into account whether a partially collected line still uses the old
indentation value resp. a temporary indentation value is active.
ll is delayed until a partially
collected line (if it exists) is output. The default scaling indicator
is m.
If ll is called without an argument, the line length is reset to
the previous value before the last call to ll. If a negative
line length is specified (which is not allowed), gtroff emits a
warning of type `range' and sets the line length to zero.
The line length is associated with the current environment.
The current line length (as set by ll) can be found in the
built-in number register .l. The number register .ll is
the line length that applies to the current output line.
Similar to .i and .in, the difference between .l
and .ll is that the latter takes into account whether a partially
collected line still uses the old line length value.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gtroff provides some very primitive operations for controlling
page layout.
v.
The current setting can be found in the built-in number register `.p'.
Note that this only specifies the size of the page, not the top and bottom margins. Those are not set by groff directly. See section 5.24 Traps, for further information on how to do this.
Negative pl values are possible also, but not very useful: No
trap is sprung, and each line is output on a single page (thus
suppressing all vertical spacing).
gtroff provides several operations which help in setting up top
and bottom titles (or headers and footers).
The tl request will print a title line, which consists of
three parts: a left justified portion, a centered portion and a right
justified portion. The argument to tl is specified as
'left'center'right'. The `%' character is
replaced with the current page number. This character can be changed
with the pc request (see below).
The title line is printed using its own line length, which is specified
with the lt request. The current setting of this is available in
the .lt number register.
The pn request will change the page number of the next
page. The only argument is the page number.
The current page number is stored in the number register %. The
number register .pn contains the number of the next page: either
the value set by a pn request, or the number of the current page
plus 1.
The pc request will change the page number character (used by the
tl request) to a different character. With no argument, this
mechanism is disabled.
See section 5.24 Traps.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To stop processing the current page, and move to the next page, invoke
the bp request. This request will also cause a break. It can
also take an argument of what the next page should be numbered. The
only difference between bp and pn is that pn does
not cause a break or actually eject a page.
.de newpage 'bp 'sp .5i .tl 'left top'center top'right top' 'sp .3i .. |
It is often necessary to force a certain amount of space before a new
page occurs. This is most useful to make sure that there is not a
single orphan line left at the bottom of a page. The ne
request will ensure that there is a certain distance, specified by the
first argument, before the next page is triggered (see 5.24 Traps, for
further information). The default unit for ne is v and
the default argument is 1v.
For example, to make sure that no fewer than 2 lines get orphaned, do the following before each paragraph:
.ne 2 .ti +5n text |
sv is similar to the ne request; it reserves the specified
amount of vertical space. If the desired amount of space exists before
the next trap (bottom page boundary), the space will be output
immediately. If there is not enough space, it is stored for later
output via the os request. The default argument is 1v
and the default unit is v.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gtroff has the ability to switch fonts at any point in the text.
There are two ways to do this, via the ft request and the
\f escape.
Fonts are generally specified as upper-case strings, which are usually 1 to 4 characters representing an abbreviation or acronym of the font name.
The basic set of fonts are `R', `I', `B', and `BI'. These are Times Roman, Italic, Bold, and Bold Italic. There is also at least one symbol font which contains various special symbols (Greek, mathematics). Such symbols fonts cannot be used directly, but should be used via an escape.
5.17.1 Changing Fonts 5.17.2 Font Families 5.17.3 Font Positions 5.17.4 Using Symbols 5.17.5 Artificial Fonts 5.17.6 Ligatures and Kerning
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Font changes can be done either with the ft request or the
\f request. With no arguments, it will switch to the previous
font (also known as `P').
eggs, bacon, .ft B spam .ft and sausage. |
The \f escape is useful for changing fonts in the middle of
words:
eggs, bacon, \fBspam\fP and sausage. |
Both of the above examples will produce the same output. Note the usage
of `P' to indicate the previous font -- using \f it is not
possible to omit this parameter.
Sometimes, when putting letters of different fonts, more or less space at such boundaries are needed. There are two escapes to help with this.
The \/ escape increases the width of the preceding character so
that the spacing between that character and the following character will
be correct if the following character is a Roman character. For
example, if an italic f is immediately followed by a Roman right
parenthesis, then in many fonts the top right portion of the f will
overlap the top left of the right parenthesis. It is a good idea to use
this escape sequence whenever an italic character is immediately
followed by a Roman character without any intervening space. This small
amount of space is also called italic correction.
The \, escape modifies the spacing of the following character so
that the spacing between that character and the preceding character will
be correct if the preceding character is a Roman character. It is a
good idea to use this escape sequence whenever a Roman character is
immediately followed by an italic character without any intervening
space. In analogy to above, this space could be called left italic
correction, but this term isn't used widely.
The ftr request will translate fonts; its syntax is
.ftr F G |
which translates font F to font G. Whenever a font
named F is referred to in a \f escape sequence, or in the
ft, ul, bd, cs, tkf, special,
fspecial, fp, or code requests, font G
will be used. If G is missing, or equal to F then font
F will not be translated.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Due to the variety of fonts available, gtroff has added the
concept of font families. Each of these families has four styles
(`R', `I', `B' and `BI').
The fonts are specified as the concatenation of the font family and
style. Specifying a font without the family part will cause
gtroff to use that style of the current family. By default,
gtroff uses the Times family.
This way, it is possible to use the basic four fonts and to select a different font family on the command line.
Font families can be switched with the fam request. The current
font family is available in the number register .fam. This is a
string-valued register.
spam, .fam H spam, .ft B spam, .fam T spam, .ft AR baked beans, .ft R and spam. |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
For the sake of old phototypesetters and compatability with old versions
of troff, gtroff has the concept of font positions,
on which various fonts are mounted. The last one or two are reserved
for the symbol font(s).
New fonts can be mounted with the fp request. These numeric
positions can then be referred to with font changing commands. When
gtroff starts it is using font number one.
.fp 1 H .fp 2 HI .fp 3 HB wink, wink, .ft 2 nudge, nudge, .ft .ft 3 say no more! .ft |
Note that after these font changes have taken place, the original font is restored.
The current font in use, as a font position, is available in number
register .f. This can be useful to remember the current font,
for later recall.
.nr save-font \n(.f ... lots 'o text ... .ft \n[save-font] |
The number of the next free font position is available in the number
register .fp. This is useful when mounting a new font, like so:
.fp \n[.fp] NEATOFONT |
Fonts not listed in the `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 fp request on an unused font
position, it should be mounted on the first unused font position, which
can be found in the .fp register. Although gtroff 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.
The 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 gtroff after it has
been mounted. If there is no third argument then the internal name will
be used as the external name. This feature make it possible to use
fonts with long names in compatibility mode.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Symbols can be inserted by using a special escape sequence. This escape
is simply the escape character (usually a backslash) followed by an
identifier. The symbol identifiers have to be two or more characters,
since single characters conflict with all the other escapes. The
identifier can be either preceded by a parenthesis if it is two
characters long, or surrounded by square brackets. So, the symbol for
the mathematical Greek letter `pi' can be produced either by \(*p
or \[*p].
area = \(*p\fIr\fP\u2\d |
The escape \C'xxx' will typeset the character named
xxx. Normally it is more convenient to use \[xxx].
But \C has the advantage that it is compatible with recent
versions of ditroff and is available in compatibility mode.
The escape \N'n' will typeset the character with code
n in the current font. n can be any integer. Most devices
only have characters with codes between 0 and 255. If the current
font does not contain a character with that code, special fonts will
not be searched. The \N escape sequence can be
conveniently used on conjunction with the char request:
.char \[phone] \f(ZD\N'37' |
The code of each character is given in the fourth column in the font
description file after the charset command. It is possible to include
unnamed characters in the font description file by using a name of
`---'; the \N escape sequence is the only way to use these.
Each character has certain properties associated with it. These
properties can be modified with the cflags request. The first
argument is the the sum of the desired flags and the remaining arguments
are the characters to have those properties.
1
2
4
8
16
32
New characters can be created with the char request. It is
called as
.char c string |
This defines character c to be string. Every time
character c needs to be printed, string will be
processed in a temporary environment and the result will be wrapped up
into a single object. Compatibility mode will be turned off and the
escape character will be set to `\' while string is being
processed. Any emboldening, constant spacing or track kerning will be
applied to this object rather than to individual characters in
string. A character defined by this request can be used just like
a normal character provided by the output device. In particular other
characters can be translated to it with the tr request; it can be
made the leader character by the lc request; repeated patterns
can be drawn with the character using the \l and \L escape
sequences; words containing the character can be hyphenated correctly,
if the hcode request is used to give the character a hyphenation
code. There is a special anti-recursion feature: use of character
within the character's definition will be handled like normal characters
not defined with char.
A character definition can be removed with the rchar request.
Its arguments are the characters to be removed. This undoes the effect
of a char request.
See section 7.1 Special Characters.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
There are a number of requests for artificially creating fonts. These
are largely vestigial remains from the days when output devices did not
have a wide variety of fonts, and when nroff and troff
were separate programs. These are no longer necessary in GNU
troff.
The ul request will print subsequent lines in italics on a device
capable of it, or underline the text on a character output device. The
single argument is the number of lines to be "underlined," with no
argument, the next line will be underlined.
The cu request is similar to ul ...
The uf request will set the underline font used by ul and
cu.
The bd request artificially creates a bold font by printing each
character twice, slightly offset. The first argument specifies the font
to embolden, and the second is the number of basic units, minus one, by
which the two characters will be offset. If the second argument is
missing, emboldening will be turned off.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The ligature mechanism can be switched on or off with the lg
request; if the parameter is non-zero or missing, ligatures are enabled,
otherwise disabled. Default is on. The current ligature mode can be
found in the number register .lg (set to 1 if ligatures are
enabled, 0 otherwise).
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 \& between them.
Kerning can be activated with the kern request. If the parameter
is non-zero or missing, enable pairwise kerning, otherwise disable it.
The number register .kern is set to 1 if pairwise kerning is
enabled, 0 otherwise.
Track kerning must be used with great care since it is usually
considered bad typography if the reader notices the effect. The syntax
of the tkf request is like this:
.tkf f s1 n1 s2 n2 |
Enable track kerning for font f. If the current font is f the width of every character will be increased by an amount between n1 and n2; if the current point size is less than or equal to s1 the width will be increased by n1; if it is greater than or equal to s2 the width will be increased by n2; if the point size is greater than or equal to s1 and less than or equal to s2 the increase in width is a linear function of the point size.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gtroff uses two dimensions with each line of text, type size and
vertical spacing. The type size is the height from the text
baseline to the top of the tallest character (descenders may drop
below this baseline). Vertical spacing is the amount of space
gtroff allows for a line of text; normally, this is about 20%
larger than the current type size. Ratios smaller than this can result
in hard-to-read text; larger that this, it will spread the text out more
vertically (useful for term papers). By default, gtroff uses
10 point type on 12 point spacing.
The difference between type size and vertical spacing is known, by typesetters, as leading.
5.18.1 Changing Type Sizes 5.18.2 Fractional Type Sizes
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Using the ps request and the \s escape the type size can
be changed. The vs request will change the vertical spacing.
The default unit for the ps and vs requests are points.
The number registers .s and .v contain the current type
size and vertical spacing.
These requests take parameters in units of points. It is possible to specify sizes as an absolute size, or as a relative change from the current size. The size 0 means go back to the previous size. With no argument it will also revert to the previous size.
snap, snap, .ps +2 grin, grin, .ps +2 wink, wink, \s+2nudge, nudge,\s+8 say no more! .ps 10 |
The \s escape may be called in a variety of ways. Much like
other escapes there must be a way to determine where the argument ends
and the text begins. Any of the following forms are valid:
\sn
\s+n
\s-n
\s(nn
\s+(nn
\s-(nn
\s(+nn
\s(-nn
See section 5.18.2 Fractional Type Sizes, for yet another syntactical form of using
the \s escape.
Some devices may only have certain permissible sizes, in which case
gtroff will round to the nearest permissible size.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A scaled point is equal to 1/sizescale points, where
sizescale is specified in the `DESC' file (1 by default.)
There is a new scale indicator `z' which has the effect of
multiplying by sizescale. Requests and escape sequences in
gtroff interpret arguments that represent a point size as being
in units of scaled points, but they evaluate each such argument using a
default scale indicator of `z'. Arguments treated in this way are
the argument to the ps request, the third argument to the
cs request, the second and fourth arguments to the tkf
request, the argument to the \H escape sequence, and those
variants of the \s escape sequence that take a numeric expression
as their argument (see below).
For example, suppose sizescale is 1000; then a scaled point will be equivalent to a millipoint; the request `.ps 10.25' is equivalent to `.ps 10.25z' and thus sets the point size to 10250 scaled points, which is equal to 10.25 points.
It would make no sense to use the `z' scale indicator in a numeric
expression whose default scale indicator was neither `u' nor
`z', and so gtroff disallows this. Similarly it would make
no sense to use a scaling indicator other than `z' or `u' in a
numeric expression whose default scale indicator was `z', and so
gtroff disallows this as well.
There is also new scale indicator `s' which multiplies by the number of units in a scaled point. So, for example, `\n[.ps]s' is equal to `1m'. Be sure not to confuse the `s' and `z' scale indicators.
The number register .s returns the point size in points as decimal
fraction. There is also a new number register .ps that returns
the point size in scaled points.
The last-requested point size in scaled points is contained in the
.psr number register. The last requested point size in points as
a decimal fraction can be found in .sr. This is a string-valued
register.
\s[n]
\s'n'
\s[+n]
\s[-n]
\s+[n]
\s-[n]
\s'+n'
\s'-n'
\s+'n'
\s-'n'
See section 8.2 Font Files.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gtroff has string variables, which are entirely for user
convenience (i.e. there are no built-in strings). They are defined
via the ds request.
.ds UX \s-1UNIX\s0\u\s-3tm\s0\d |
They are interpolated, or expanded in-place, via the \* escape:
The \*(UX Operating System |
If the string named by the \* does not exist, the escape will be
replaced by nothing.
Caution: Unlike other requests, the second argument to the
ds request takes up the entire line including trailing spaces.
This means that comments on a line with such a request can introduce
unwanted space into a string.
.ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark |
Instead the comment should be put on another line or have the comment escape adjacent with the end of the string.
.ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark |
To produce leading space the string can be started with a double quote. No trailing quote is needed; in fact, any trailing quote is included in your string.
.ds sign " Yours in a white wine sauce, |
The as request will append a string to another string. It works
similar to the ds request except that it appends the second
argument onto the string named by the first argument.
.as sign " with shallots, onions and garlic, |
Strings are not limited to a single line of text. A string can span several lines by escaping the newlines with a backslash. The resulting string will be stored without the newlines.
.ds foo lots and lots \ of text are on these \ next several lines |
Rudimentary string manipulation routines are given with the
substring and length requests. The former has the
following syntax:
.substring xx n1 [n2] |
It replaces the string in register xx with the substring defined by the indices n1 and n2. The first character in the string has index one. If n2 is omitted, it is taken to be equal to the string's length. If the index value n1 or n2 is negative or zero, it will be counted from the end of the string, going backwards: The last character has index 0, the character before the last character has index -1, etc.
Here the syntax of the length request:
.length xx string |
It computes the length of string and returns it in the number register xx (which is not necessarily defined before).
See section 5.5 Identifiers, and 5.6.3.1 Comments.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
In if and while requests, there are several more operators
available:
e
o
n
t
'xxx'yyy'
rxxx
dxxx
cch
\(ch or
\[ch]); the condition will also be true if ch has
been defined by the char request.
5.20.1 if-else 5.20.2 while
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gtroff has if-then-else constructs like other languages, although
the formatting can be painful.
The if request has the following syntax:
.if expr anything |
where expr is the expression to be evaluated; anything (the remainder of the line) will be executed if expr evaluates to non-zero (true). anything will be interpreted as though it was on a line by itself. See section 5.4 Expressions, for more info.
Here are some examples:
.if t .ls 2 \" double spacing in troff .if 0 .ab how'd this happen? |
An if-then-else is written using two requests ie and el.
The first request is the `if' part and the latter is the `else' part.
.ie .el |
In many cases more than one request is to be executed as a result of any
of these requests. This can be done using the \{ and \}
escapes. The following example shows the possible ways to use these
escapes (note the position of the opening and closing braces).
.ie t \{\
. ds lq ``
. ds rq ''
.\}
.el \
.\{\
. ds lq "
. ds rq "\}
.ds qq "
|
See section 5.4 Expressions.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gtroff provides a looping construct using the while
request, which is used much like the if (and related) requests.
The first argument is an expression which will be evaluated. The
while request will interpret the remainder of the line until the
expression evaluates to 0 or false.
.nr a 0 1 .while (\na<9) \&\n+a, \&\n+a |
The preceding example produces:
1, 2, 3, 4, 5, 6, 7, 8, 9, 10 |
Note the usage of the \& escape to avoid a control character at
the beginning of a line.
The break request will break out of a while loop. Be sure
not to confuse this with the br request (causing a line break).
The continue request will finish the current iteration of a while
loop, immediately restarting the next iteration.
See section 5.4 Expressions.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A macro is a collection of text and embedded commands which can be
invoked multiple times. Macros are used for defining common operations.
Macros are defined using the de request. This request takes a
name for the macro as the first argument. Subsequent lines are copied
into an internal buffer until the line .. is encountered. The
optional second argument to de can change this ending token.
Here a small example macro called `P' which will cause a break and the insertion of some vertical space. It could be used to separate paragraphs.
.de P .br .sp .8v .. |
The am request works similarly to de except it appends
onto the macro named by the first argument. So, to make the previously
defined `P' macro actually do indented instead of block paragraphs,
is is possible to add the necessary code to the existing macro like
this:
.am P .ti +5n .. |
Macros can be aliased with the als request.
5.21.1 Copy-in Mode 5.21.2 Parameters
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When gtroff reads in the text for a macro or diversion it copies
the text (including request lines, but excluding escapes) into an
internal buffer. Escapes will be converted into an internal form,
except for \n, \$, \*, \\ and
\RET which are evaluated and inserted into the text where
the escape was located. This is known as copy-in mode or
copy mode.
What this means is that you can specify when these escapes are to be
evaluated (either at copy-in time or at the time of use) by insulating
the escapes with an extra backslash. Compare this to the \def
and \edef commands in TeX.
For example, the following will result in the numbers 20 and being printed:
.nr x 20 .de y .nr x 10 \&\nx \&\\nx .. .y |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The arguments to a macro can be examined using a variety of escapes.
The number of arguments is available in the .$ number register.
Any individual argument can be retrieved with one of the following
escapes:
The escapes \$n, \$(nn and
\$[nnn] will result in the nth, nnth or
nnnth argument. As usual, the first form only accepts a single
number (larger than zero), the second only a two-digit number (larger or
equal to 10), and the third any positive integer value (larger than
zero). Macros can have an unlimited number of arguments. Note that due
to copy-in mode, two backslashes should be used on these in actual use
to prevent interpolation until the macro is actually invoked.
The request shift will shift the arguments 1 position, or as
many positions as specified by its argument. After executing this
request, argument i will become argument i-n;
arguments 1 to n will no longer be available. Shifting by
negative amounts is currently undefined.
In some cases it is convenient to use all of the arguments at once (for
example, to pass the arguments along to another macro). The \$*
escape is the concatenation of all the arguments separated by spaces. A
similar escape is \$@, which is the concatenation of all the
arguments with each surrounded by double quotes, and separated by
spaces.
The \$0 escape is the name by which the current macro was
invoked. The als request can make a macro have more than one
name.
.de vl .ie \\n(.$=1 .ds Vl Pre-Release Version .el .ds Vl Version \\$3, \\$4. .. |
This would be called as
.vl $Id: groff.texinfo,v 1.40 2000/06/18 10:13:51 wlemb Exp $ |
See section 5.6.1.1 Request Arguments.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Motions up and down the page can be done with the sp request.
However, this causes a break so that the actual effect is to move to the
left margin and then to the specified location.
The request mk can be used to mark a location on a page, for
movement to later. This request takes a register name as an argument in
which to store the current page location. With no argument it will
store the location in an internal register. The results of this can be
used later by the rt or the sp request. The rt
request will return upwards to the location given in the register
name given as an argument, with no argument it will return to the
location marked with the mk request
The following escapes give fine control of movements about the page.
The \v'e' enables arbitrary vertical motion from the
current location on the page. The argument e specifies the
distance to move; positive is downwards and negative upwards. The
default unit for this escape is vertical spaces, v's. Beware,
however, that gtroff will leave text processing to continue
wherever the motion ends, so to avoid interference with text processing,
motions should be balanced.
There are some special case escapes for vertical motion.
Horizontal motions can be done via the \h'e' escape. The
expression e indicates how far to move: positive is rightwards
and negative leftwards.
There are a number of special case escapes for horizontal motion:
\SP
\~
\|
\^
\0
\&
\)
\& except that it behaves like a character declared with the
cflags request to be transparent for the purposes of end of
sentence recognition.
A frequent need is to do horizontal movement based on the width of some
arbitrary text (e.g. given as an argument to a macro). For that,
there is the escape \w'text' which will interpolate to the
width of the given text in basic units.
Font changes may occur in text which don't affect current settings.
After use, \w sets several registers:
st
sb
rst
rsb
st and sb registers, but takes account of the
heights and depths of characters.
ct
ssc
skw
\w
argument, the center of an accent from a Roman font should be placed
over that character.
.k
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gtroff provides a number of ways to draw lines and other figures
on the page. Used in combination with the page motion commands (see
5.22 Page Motions, for more info), a wide variety of figures can be
drawn. However, for complex drawings these operations can be quite
cumbersome, and it may be wise to use graphic preprocessors like
gpic or ggrn. See section 6.3 gpic, and 6.4 ggrn, for more
information.
All drawing is done via escapes.
The \l escape will draw a line rightwards from the current
location. The full syntax for this escape is like this:
\l'lc' |
where l is the length of the line to be drawn, starting at the current location; positive numbers will draw to the right, and negative will draw towards the left. This can also be specified absolutely (i.e. with a leading `|') which will draw back to the beginning of the line.
The optional second parameter c is a character to draw the line
with. If this second argument is not specified, gtroff will use
the underscore character.
To separate the two arguments (to prevent gtroff from
interpreting a drawing character as a scaling indicator) use \&.
Here a small useful example:
.de box \(br\\$*\(br\l'|0\(rn'\l'|0\(ul' .. |
Note that this works by outputting a box rule (a vertical line), then the text given as an argument and then another box rule. Then the line drawing escapes both draw from the current location to the beginning of the input line.
Vertical lines are drawn using the \L escape. Its parameters are
specified similar to the \l escape. If the length is positive,
the movement will be downwards, and upwards for negative values. The
default character is the box rule character. As with the vertical
motion escapes, text processing will blindly continue where the line
ends.
More flexible drawing functions are available via the \D escape.
While the previous escapes will work on a character device, these
escapes will not.
\D'l dx dy'
\D'c d'
\D'C d'
\D'e dx dy'
\D'E dx dy'
\D'a dx1 dy1 dx2 dy2'
\D'~ dx1 dy1 dx2 dy2 ...'
\D'f n'
\D'p dx1 dy1 dx2 dy2 ...'
\D'P dx1 dy1 dx2 dy2 ...'
\D't n'
ditroff).
The \b escape will pile a sequence of characters
vertically, and center it vertically on the current line. This can be
used to build large brackets and braces.
\b'\(lt\(bv\(lk\(bv\(lb' |
See section 8.1.3 Drawing Functions.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Traps are locations, which, when reached, will call a specified macro. These traps can occur at a given location on the page, at a given location in the current diversion, after a certain number of input lines or at the end of input.
5.24.1 Page Location Traps 5.24.2 Diversion Traps 5.24.3 Input Line Traps 5.24.4 End-of-input Traps
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Page location traps are frequently used for page headers and footers. The following is a simple example of this.
.de hd \" Page header 'sp .5i .tl 'Title''date' 'sp .3i .. .de fo \" Page footer 'sp 1v .tl ''%'' 'bp .. .wh 0 hd \" trap at top of the page .wh -1i fo \" trap one inch from bottom |
The number register .t is the distance to the next trap.
The location of a trap can be changed later on with the ch
request. The first argument is the name of the macro to be invoked at
the trap, and the second argument is the new location for the trap.
This is useful for building up footnotes in a diversion to allow more
space at the bottom of the page for them.
The vpt request will enable vertical position traps if the
argument is non-zero, disable them otherwise. Vertical position traps
are traps set by the wh or dt requests. Traps set by the
it request are not vertical position traps. The parameter that
controls whether vertical position traps are enabled is global.
Initially vertical position traps are enabled. The current setting of
this is available in the number register .vpt.
The number register .trunc contains the amount of vertical space
truncated by the most recently sprung vertical position trap, or, if the
trap was sprung by a ne request, minus the amount of vertical
motion produced by the 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.
The number register .ne contains the amount of space that was
needed in the last ne request that caused a trap to be sprung.
Useful in conjunction with the .trunc register. See section 5.16 Page Control, for more information.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Traps can also be set within a diversion using the dt
request. Like wh the first argument is the location of the trap
and the second argument is the name of the macro to be invoked. The
number register .t will still work within diversions.
See section 5.25 Diversions, for more information.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The it request will set an input line trap. The format for
calling this is
.it n name |
where n is the number of lines of input which may be read before springing the trap, name is the macro to be invoked. Request lines are not counted as input lines.
For example, one possible use is to have a macro which will print the next n lines in a bold font.
.de B .it B-end \\$1 .ft B .. .de B-end .ft R .. |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The em request will set a trap at the end of input. The macro
specified as an argument will be executed after the last line of the
input file has been processed.
For example, if the document had to have a section at the bottom of the
last page for someone to approve it, the em request could be
used.
.de approval .ne 5v .sp |(\\n(.t-6v) .in +4i .lc _ .br Approved:\t\a .sp Date:\t\t\a .. .em approval |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
In gtroff it is possible to divert text into a named
storage area. Due to the similarity to defining macros it is sometimes
said to be stored in a macro. This is used for saving text for output
at a later time, which is useful for keeping blocks of text on the same
page, footnotes, tables of contents and indices.
A diversion is initiated by the di request. Like the de
request, it takes an argument of a macro name to divert subsequent text
into. The da macro will append to an existing diversion.
di (resp. da) without an argument ends the diversion.
Diversions may be nested. The number register .z contains the
name of the current diversion. The number register .d contains
the current vertical place in the diversion. If not in a diversion it
is the same as the register nl.
.h
After completing a diversion, the built-in number registers dn
and dl contain the vertical and horizontal size of the diversion.
.\" Center text both horizontally & vertically .de (c .br .nf .di @c .. .de )c .br .di .nr @s (((\\n(.tu-\\n(dnu)/2u)-1v) .sp \\n(@su .ce 1000 .nf . .br .ce 0 .sp \\n(@su .br .fi .rr @s .. |
Requests, macros and escapes are interpreted when read into a diversion.
There are two ways to prevent this; either way will take the given text
and transparently embed it into the diversion. The first method
is to prefix the line with \!. This will cause the entire line
to be transparently inserted into the diversion. This is useful for
macros which shouldn't be invoked until the diverted text is actually
output.
The other way is to surround the text by the \? escape, i.e.
\?anything\? |
anything may not contain newlines; use \! to embed
newlines in a diversion. The escape sequence \? is also
recognized in copy mode and turned into a single internal code; it is
this code that terminates anything. Thus the following example will
print 4.
.nr x 1 .nf .di d \?\\?\\\\?\\\\\\\\nx\\\\?\\?\? .di .nr x 2 .di e .d .di .nr x 3 .di f .e .di .nr x 4 .f |
The asciify request only exists in order to make certain gross
hacks work with GNU troff. It unformats the diversion
specified as an argument in such a way that ASCII characters
that were formatted and diverted will be treated like ordinary input
characters when the diversion is reread. For example, the following
will set register n to 1.
.tr @. .di x @nr\ n\ 1 .br .di .tr @@ .asciify x .x |
See section 5.21.1 Copy-in Mode.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
It happens frequently that some text should be printed in a certain
format regardless of what may be in effect at the time, for example, in
a trap invoked macro to print headers and footers. To solve this
gtroff has environments in which text is processed. An
environment contains most of the parameters that control text
processing. It is possible to switch amongst these environments; by
default gtroff processes text in environment 0. The
following is the information kept in an environment.
These environments may be given arbitrary names (see 5.5 Identifiers,
for more info). Old versions of troff only had environments
named `0', `1' and `2'.
The ev request will switch to another environment. The single
argument is the name of the environment to switch to. With no argument
gtroff will switch back to the previous environment. There is no
limit on the number of named environments; they will be created the
first time that they are referenced. The .ev register contains
the name or number of the current environment. This is a string-valued
register.
Note that a call to ev (with argument) will push the previously
active environment onto a stack. If, say, environments `foo',
`bar', and `zap' are called (in that order), the first
ev request without parameter will switch back to environment
`bar' (which will be popped off the stack), and a second call will
switch back to environment `foo'.
Here is another example:
.ev footnote-env .fam N .ps 6 .vs 8 .ll -.5i .ev ... .ev footnote-env \(dg Note the large, friendly letters. .ev |
To copy an environment into the current one, use the evc request,
which takes the name of the environment to copy from as an argument.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The so request will read in the file given as an argument and
include it in place of the so request. This is quite useful for
large documents, i.e. keeping each chapter in a separate file.
See section 6.7 gsoelim, for more information.
The mso request is the same as the so request except that
the file is searched for in the same directories as
`tmac.name' is searched for when the `-mname'
option is specified.
The cf and trf requests are to include a file. It will
transparently output the contents of file filename. Each line is output
as it were preceded by \!; however, the lines are not subject to
copy mode interpretation. If the file does not end with a newline, then
a newline will be added. For example, to define a macro x
containing the contents of file `f', use
.di x .trf f .di |
The request .cf filename, when used in a diversion,
will embed in the diversion an object which, when reread, will cause the
contents of filename to be transparently copied through to the
output. In UNIX troff, the contents of filename
is immediately copied through to the output regardless of whether there
is a current diversion; this behaviour is so anomalous that it must be
considered a bug. This request causes a line break.
With trf, unlike cf, the file cannot contain characters
such as NUL that are not valid gtroff input characters
(see section 5.5 Identifiers). This request causes a line break.
The nx request will force gtroff to continue processing of
the file specified as an argument.
The rd request will read from standard input, and include what is
read as though it were part of the input file. Text is read until a
blank line is encountered.
Using these two requests it is easy to set up form letters. The form letter template is constructed like this:
.ce \*(td .sp 2 .nf .rd .sp .rd .fi Body of letter. .bp .nx repeat.let |
When this is run, the following file should be redirected in. Note that
requests included in this file are executed as though they were part of
the form letter. The last block of input is the ex requests
which tells groff to stop processing. If this was not there, groff
would not know when to stop.
Trent A. Fisher 708 NW 19th Av., #202 Portland, OR 97209 Dear Trent, Len Adollar 4315 Sierra Vista San Diego, CA 92103 Dear Mr. Adollar, .ex |
The sy request will allow arbitrary system commands to be
executed from within a gtroff document. The output is not saved
anyplace, so it is up to the user to do so.
For example, the following example will introduce the current time into a document:
.sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\ (localtime(time))[2,1,0]' > /tmp/x\n[$$] .so /tmp/x\n[$$] .sy rm /tmp/x\n[$$] \nH:\nM:\nS |
Note that this works by having the perl script (run by sy)
print out the nr requests which will set the number registers
`H', `M' and `S', and then reads those commands in with
the so request.
The systat number register contains the return value of the
system() function executed by the last sy request.
The open request will open a file (specified as the second
argument) for writing and associate the stream (specified as the first
argument) with it.
The opena is like open, but if the file exists, append to
it instead of truncating it.
The write request will write to the file associated with the
stream specified by the first argument. The stream must previously have
been the subject of an open request. The remainder of the line is
interpreted as the ds request reads its second argument: A
leading `"' will be stripped, and it will be read in copy-in mode.
The close request will close the stream specified by the first
argument; stream will no longer be an acceptable argument to the
write request.
The \V escape will interpolate the contents of the specified
environment variable, as returned by the function getenv. The
argument to \V is specified as an identifier, i.e.
`\Vx', `\V(xx' or `\V[xxx]'. \V
is interpreted in copy-in mode.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
There are two escapes which will allow information to be directly given to the postprocessor. This is particularly useful for embedding POSTSCRIPT into the final document.
The \X escape will embed its argument into the gtroff
output preceded with `x X'.
The \Y escape is called with an identifier (i.e.
\Yx, \Y(xx or \Y[xxx]). This is
approximately equivalent to `\X'\*[xxx]''. However, the
contents of the string or macro xxx are not interpreted; also it
is permitted for xxx to have been defined as a macro and thus
contain newlines (it is not permitted for the argument to \X to
contain newlines). The inclusion of newlines requires an extension to
the UNIX troff output format, and will confuse drivers
that do not know about this extension.
See section 7. Output Devices.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This section documents parts of gtroff which cannot (yet) be
categorized elsewhere in this manual.
Line numbers can be printed in the left margin using the nm
request. The first argument is the line number of the next
output line; this defaults to 1. The second argument indicates on
which lines numbers will be printed, i.e. 5 means put line numbers on
every 5 lines; this defaults to 1. The third argument is the
space to be left between the number and the text; this defaults to
1. The fourth argument is the indentation of the line numbers.
Without arguments, line numbers are turned off.
The nn request will temporarily turn off line numbering. The
first argument is the number of lines not to be numbered; this defaults
to 1.
Margin characters can be automatically printed to the right of the text
with the mc request. The first argument is the character to be
printed, and the second argument is the distance away from the main body
text. With no arguments the margin characters are turned off. If this
occurs before a break, no margin character will be printed.
This is quite useful for indicating text that has changed, and, in fact,
there are programs available for doing this (they are called
nrchbar and changebar and can be found in any
`comp.sources.unix' archive.
The primary reason for the existence of lf is to make debugging
documents which are split into many files, which are then put together
with soelim and other preprocessors. The first argument is the
name of the file and the second argument is the input line number in
that file. This way gtroff can produce error messages which are
intelligible to the user.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gtroff is not easy to debug, but there are some useful features
and strategies for debugging.
tm request will send output to the standard error stream;
this is very useful for printing debugging output.
.if \n(DB .tm debugging output |
To activate these statements say
groff -rDB=1 file |
ab request is similar to the tm request, except that
it will cause gtroff to stop processing. With no argument it
will print `User Abort'.
ex request will also cause gtroff to stop processing
if encountered at the topmost level; see also 5.27 I/O.
gtroff can be forced to suppress formatted output with
the `-z' flag.
pm request will dump out the entire symbol table.
pnr request will print the names and contents of all
currently defined number registers on stderr.
ptr request will print the names and positions of all traps
(not including input line traps and diversion traps) on stderr. Empty
slots in the page trap list are printed as well, because they can affect
the priority of subsequently planted traps.
fl request instructs gtroff to flush its output
immediately. The intention is that this be used when using
gtroff interactively. There is little other use for it. This
request causes a line break.
backtrace request will print a backtrace of the input stack
to the standard error stream.
gtroff has command line options for printing out more warnings
(`-w') and for printing backtraces (`-b') when a warning
or an error occurs. The most verbose level of warnings is `-ww'.
warn request controls the level of warnings checked for. The
only argument is the sum of the numbers associated with each warning
that is to be enabled; all other warnings will be disabled. The number
associated with each warning is listed below. For example,
.warn 0 will disable all warnings, and .warn 1
will disable all warnings except that about missing characters. If an
argument is not given, all warnings will be enabled. The number
register .warn contains the current warning level.
5.30.1 Warnings
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The warnings that can be given to gtroff 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.
el request with no matching ie request.
See section 5.20.1 if-else.
di or da without an argument when there is no
current diversion.
\} where a number was expected.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GNU troff has a number of features which cause incompatibilities
with documents written with old versions of troff.
Long names cause some incompatibilities. UNIX troff
will interpret
.dsabcd |
as defining a string `ab' with contents `cd'. Normally, GNU
troff will interpret this as a call of a macro named
dsabcd. Also UNIX troff will interpret
\*[ or \n[ as references to a string or number register
called `['. In GNU troff, however, this will normally be
interpreted as the start of a long name. In compatibility mode GNU
troff will interpret these things in the traditional way. In
compatibility mode, however, long names are not recognized.
Compatibility mode can be turned on with the `-C' command line
option, and turned on or off with the cp request. The number
register .C is 1 if compatibility mode is on, 0
otherwise.
GNU troff does not allow the use of the escape sequences
\|, \^, \&, \}, \{,
\SP, \', \`, \-, \_, \!,
\%, and \c in names of strings, macros, diversions, number
registers, fonts or environments; UNIX troff does. The
\A escape sequence (see section 5.5 Identifiers) may be helpful in
avoiding use of these escape sequences in names.
Fractional point sizes cause one noteworthy incompatibility. In
UNIX troff the ps request ignores scale
indicators and thus
.ps 10u |
will set the point size to 10 points, whereas in GNU troff it
will set the point size to 10 scaled points. See section 5.18.2 Fractional Type Sizes, for more information.
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
bd, cs, tkf, tr, or 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,
.di x \\\\ .br .di .x |
will print `\\' in GNU troff; each pair of input backslashes
is turned into one output backslash and the resulting output backslashes
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 `\'. The
correct way to obtain a printable backslash is to use the \e
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. To store, for some reason, an escape sequence in a
diversion that will be interpreted when the diversion is reread, either
use the traditional \! transparent output facility, or, if this
is unsuitable, the new \? escape sequence.
See section 5.25 Diversions, for more information.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |