1416 lines
44 KiB
Plaintext
1416 lines
44 KiB
Plaintext
|
This is groff, produced by makeinfo version 4.2 from ./groff.texinfo.
|
|||
|
|
|||
|
This manual documents GNU `troff' version 1.18.
|
|||
|
|
|||
|
Copyright (C) 1994-2000, 2001, 2002 Free Software Foundation, Inc.
|
|||
|
|
|||
|
Permission is granted to copy, distribute and/or modify this
|
|||
|
document under the terms of the GNU Free Documentation License,
|
|||
|
Version 1.1 or any later version published by the Free Software
|
|||
|
Foundation; with no Invariant Sections, with the Front-Cover texts
|
|||
|
being `A GNU Manual," and with the Back-Cover Texts as in (a)
|
|||
|
below. A copy of the license is included in the section entitled
|
|||
|
`GNU Free Documentation License."
|
|||
|
|
|||
|
(a) The FSF's Back-Cover Text is: `You have freedom to copy and
|
|||
|
modify this GNU Manual, like GNU software. Copies published by
|
|||
|
the Free Software Foundation raise funds for GNU development."
|
|||
|
|
|||
|
INFO-DIR-SECTION Miscellaneous
|
|||
|
START-INFO-DIR-ENTRY
|
|||
|
* Groff: (groff). The GNU troff document formatting system.
|
|||
|
END-INFO-DIR-ENTRY
|
|||
|
|
|||
|
|
|||
|
File: groff, Node: Strings, Next: Conditionals and Loops, Prev: Sizes, Up: gtroff Reference
|
|||
|
|
|||
|
Strings
|
|||
|
=======
|
|||
|
|
|||
|
`gtroff' has string variables, which are entirely for user
|
|||
|
convenience (i.e. there are no built-in strings exept `.T', but even
|
|||
|
this is a read-write string variable).
|
|||
|
|
|||
|
- Request: .ds name [string]
|
|||
|
- Request: .ds1 name [string]
|
|||
|
- Escape: \*N
|
|||
|
- Escape: \*(NM
|
|||
|
- Escape: \*[NAME ARG1 ARG2 ...]
|
|||
|
Define and access a string variable NAME (one-character name N,
|
|||
|
two-character name NM). If NAME already exists, `ds' overwrites
|
|||
|
the previous definition. Only the syntax form using brackets can
|
|||
|
take arguments which are handled identically to macro arguments;
|
|||
|
the single exception is that a closing bracket as an argument must
|
|||
|
be enclosed in double quotes. *Note Request Arguments::, and
|
|||
|
*Note Parameters::.
|
|||
|
|
|||
|
Example:
|
|||
|
|
|||
|
|
|||
|
.ds foo a \\$1 test
|
|||
|
.
|
|||
|
This is \*[foo nice].
|
|||
|
=> This is a nice test.
|
|||
|
|
|||
|
The `\*' escape "interpolates" (expands in-place) a
|
|||
|
previously-defined string variable. To be more precise, the stored
|
|||
|
string is pushed onto the input stack which is then parsed by
|
|||
|
`gtroff'. Similar to number registers, it is possible to nest
|
|||
|
strings, i.e. string variables can be called within string
|
|||
|
variables.
|
|||
|
|
|||
|
If the string named by the `\*' escape does not exist, it is
|
|||
|
defined as empty, and a warning of type `mac' is emitted (see
|
|||
|
*Note Debugging::, for more details).
|
|||
|
|
|||
|
*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,
|
|||
|
|
|||
|
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 is stored _without_ the newlines.
|
|||
|
|
|||
|
|
|||
|
.ds foo lots and lots \
|
|||
|
of text are on these \
|
|||
|
next several lines
|
|||
|
|
|||
|
It is not possible to have real newlines in a string. To put a
|
|||
|
single double quote character into a string, use two consecutive
|
|||
|
double quote characters.
|
|||
|
|
|||
|
The `ds1' request turns off compatibility mode while interpreting
|
|||
|
a string. To be more precise, a "compatibility save" input token
|
|||
|
is inserted at the beginning of the string, and a "compatibility
|
|||
|
restore" input token at the end.
|
|||
|
|
|||
|
|
|||
|
.nr xxx 12345
|
|||
|
.ds aa The value of xxx is \\n[xxx].
|
|||
|
.ds1 bb The value of xxx ix \\n[xxx].
|
|||
|
.
|
|||
|
.cp 1
|
|||
|
.
|
|||
|
\*(aa
|
|||
|
=> warning: number register `[' not defined
|
|||
|
=> The value of xxx is 0xxx].
|
|||
|
\*(bb
|
|||
|
=> The value of xxx ix 12345.
|
|||
|
|
|||
|
Strings, macros, and diversions (and boxes) share the same name
|
|||
|
space. Internally, even the same mechanism is used to store them.
|
|||
|
This has some interesting consequences. For example, it is
|
|||
|
possible to call a macro with string syntax and vice versa.
|
|||
|
|
|||
|
|
|||
|
.de xxx
|
|||
|
a funny test.
|
|||
|
..
|
|||
|
This is \*[xxx]
|
|||
|
=> This is a funny test.
|
|||
|
|
|||
|
.ds yyy a funny test
|
|||
|
This is
|
|||
|
.yyy
|
|||
|
=> This is a funny test.
|
|||
|
|
|||
|
Diversions and boxes can be also called with string syntax.
|
|||
|
|
|||
|
Another consequence is that you can copy one-line diversions or
|
|||
|
boxes to a string.
|
|||
|
|
|||
|
|
|||
|
.di xxx
|
|||
|
a \fItest\fR
|
|||
|
.br
|
|||
|
.di
|
|||
|
.ds yyy This is \*[xxx]\c
|
|||
|
\*[yyy].
|
|||
|
=> This is a test.
|
|||
|
|
|||
|
As the previous example shows, it is possible to store formatted
|
|||
|
output in strings. The `\c' escape prevents the insertion of an
|
|||
|
additional blank line in the output.
|
|||
|
|
|||
|
Copying diversions longer than a single output line produces
|
|||
|
unexpected results.
|
|||
|
|
|||
|
|
|||
|
.di xxx
|
|||
|
a funny
|
|||
|
.br
|
|||
|
test
|
|||
|
.br
|
|||
|
.di
|
|||
|
.ds yyy This is \*[xxx]\c
|
|||
|
\*[yyy].
|
|||
|
=> test This is a funny.
|
|||
|
|
|||
|
Usually, it is not predictable whether a diversion contains one or
|
|||
|
more output lines, so this mechanism should be avoided. With UNIX
|
|||
|
`troff', this was the only solution to strip off a final newline
|
|||
|
from a diversion. Another disadvantage is that the spaces in the
|
|||
|
copied string are already formatted, making them unstretchable.
|
|||
|
This can cause ugly results.
|
|||
|
|
|||
|
A clean solution to this problem is available in GNU `troff',
|
|||
|
using the requests `chop' to remove the final newline of a
|
|||
|
diversion, and `unformat' to make the horizontal spaces
|
|||
|
stretchable again.
|
|||
|
|
|||
|
|
|||
|
.box xxx
|
|||
|
a funny
|
|||
|
.br
|
|||
|
test
|
|||
|
.br
|
|||
|
.box
|
|||
|
.chop xxx
|
|||
|
.unformat xxx
|
|||
|
This is \*[xxx].
|
|||
|
=> This is a funny test.
|
|||
|
|
|||
|
*Note Gtroff Internals::, for more information.
|
|||
|
|
|||
|
- Request: .as name [string]
|
|||
|
- Request: .as1 name [string]
|
|||
|
The `as' request is similar to `ds' but appends STRING to the
|
|||
|
string stored as NAME instead of redefining it. If NAME doesn't
|
|||
|
exist yet, it is created.
|
|||
|
|
|||
|
|
|||
|
.as sign " with shallots, onions and garlic,
|
|||
|
|
|||
|
The `as1' request is similar to `as', but compatibility mode is
|
|||
|
switched off while the appended string is interpreted. To be more
|
|||
|
precise, a "compatibility save" input token is inserted at the
|
|||
|
beginning of the appended string, and a "compatibility restore"
|
|||
|
input token at the end.
|
|||
|
|
|||
|
Rudimentary string manipulation routines are given with the next two
|
|||
|
requests.
|
|||
|
|
|||
|
- Request: .substring str n1 [n2]
|
|||
|
Replace the string named STR with the substring defined by the
|
|||
|
indices N1 and N2. The first character in the string has index 0.
|
|||
|
If N2 is omitted, it is taken to be equal to the string's length.
|
|||
|
If the index value N1 or N2 is negative, it is counted from the
|
|||
|
end of the string, going backwards: The last character has
|
|||
|
index -1, the character before the last character has index -2,
|
|||
|
etc.
|
|||
|
|
|||
|
|
|||
|
.ds xxx abcdefgh
|
|||
|
.substring xxx 1 -4
|
|||
|
\*[xxx]
|
|||
|
=> bcde
|
|||
|
|
|||
|
|
|||
|
- Request: .length reg str
|
|||
|
Compute the number of characters of STR and return it in the
|
|||
|
number register REG. If REG doesn't exist, it is created. `str'
|
|||
|
is read in copy mode.
|
|||
|
|
|||
|
|
|||
|
.ds xxx abcd\h'3i'efgh
|
|||
|
.length yyy \n[xxx]
|
|||
|
\n[yyy]
|
|||
|
=> 14
|
|||
|
|
|||
|
|
|||
|
- Request: .rn xx yy
|
|||
|
Rename the request, macro, diversion, or string XX to YY.
|
|||
|
|
|||
|
- Request: .rm xx
|
|||
|
Remove the request, macro, diversion, or string XX. `gtroff'
|
|||
|
treats subsequent invocations as if the object had never been
|
|||
|
defined.
|
|||
|
|
|||
|
- Request: .als new old
|
|||
|
Create an alias named NEW for the request, string, macro, or
|
|||
|
diversion object named OLD. The new name and the old name are
|
|||
|
exactly equivalent (it is similar to a hard rather than a soft
|
|||
|
link). If OLD is undefined, `gtroff' generates a warning of type
|
|||
|
`mac' and ignores the request.
|
|||
|
|
|||
|
- Request: .chop xx
|
|||
|
Remove (chop) the last character from the macro, string, or
|
|||
|
diversion named XX. This is useful for removing the newline from
|
|||
|
the end of diversions that are to be interpolated as strings.
|
|||
|
This command can be used repeatedly; see *Note Gtroff Internals::,
|
|||
|
for details on nodes inserted additionally by `gtroff'.
|
|||
|
|
|||
|
*Note Identifiers::, and *Note Comments::.
|
|||
|
|
|||
|
|
|||
|
File: groff, Node: Conditionals and Loops, Next: Writing Macros, Prev: Strings, Up: gtroff Reference
|
|||
|
|
|||
|
Conditionals and Loops
|
|||
|
======================
|
|||
|
|
|||
|
* Menu:
|
|||
|
|
|||
|
* Operators in Conditionals::
|
|||
|
* if-else::
|
|||
|
* while::
|
|||
|
|
|||
|
|
|||
|
File: groff, Node: Operators in Conditionals, Next: if-else, Prev: Conditionals and Loops, Up: Conditionals and Loops
|
|||
|
|
|||
|
Operators in Conditionals
|
|||
|
-------------------------
|
|||
|
|
|||
|
In `if' and `while' requests, there are several more operators
|
|||
|
available:
|
|||
|
|
|||
|
`e'
|
|||
|
`o'
|
|||
|
True if the current page is even or odd numbered (respectively).
|
|||
|
|
|||
|
`n'
|
|||
|
True if the document is being processed in nroff mode (i.e., the
|
|||
|
`.nroff' command has been issued).
|
|||
|
|
|||
|
`t'
|
|||
|
True if the document is being processed in troff mode (i.e., the
|
|||
|
`.troff' command has been issued).
|
|||
|
|
|||
|
`v'
|
|||
|
Always false. This condition is for compatibility with other
|
|||
|
`troff' versions only.
|
|||
|
|
|||
|
`'XXX'YYY''
|
|||
|
True if the string XXX is equal to the string YYY. Other
|
|||
|
characters can be used in place of the single quotes; the same set
|
|||
|
of delimiters as for the `\D' escape is used (*note Escapes::).
|
|||
|
`gtroff' formats the strings before being compared:
|
|||
|
|
|||
|
|
|||
|
.ie "|"\fR|\fP" \
|
|||
|
true
|
|||
|
.el \
|
|||
|
false
|
|||
|
=> true
|
|||
|
|
|||
|
The resulting motions, glyph sizes, and fonts have to match,(1)
|
|||
|
(*note Operators in Conditionals-Footnote-1::) and not the
|
|||
|
individual motion, size, and font requests. In the previous
|
|||
|
example, `|' and `\fR|\fP' both result in a roman `|' glyph with
|
|||
|
the same point size and at the same location on the page, so the
|
|||
|
strings are equal. If `.ft I' had been added before the `.ie',
|
|||
|
the result would be "false" because (the first) `|' produces an
|
|||
|
italic `|' rather than a roman one.
|
|||
|
|
|||
|
`r XXX'
|
|||
|
True if there is a number register named XXX.
|
|||
|
|
|||
|
`d XXX'
|
|||
|
True if there is a string, macro, diversion, or request named XXX.
|
|||
|
|
|||
|
`m XXX'
|
|||
|
True if there is a color named XXX.
|
|||
|
|
|||
|
`c G'
|
|||
|
True if there is a glyph G available(2) (*note Operators in
|
|||
|
Conditionals-Footnote-2::); G is either an ASCII character or a
|
|||
|
special character (`\(GG' or `\[GGG]'); the condition is also true
|
|||
|
if G has been defined by the `char' request.
|
|||
|
|
|||
|
Note that these operators can't be combined with other operators like
|
|||
|
`:' or `&'; only a leading `!' (without whitespace between the
|
|||
|
exclamation mark and the operator) can be used to negate the result.
|
|||
|
|
|||
|
|
|||
|
.nr xxx 1
|
|||
|
.ie !r xxx \
|
|||
|
true
|
|||
|
.el \
|
|||
|
false
|
|||
|
=> false
|
|||
|
|
|||
|
A whitespace after `!' always evaluates to zero (this bizarre
|
|||
|
behaviour is due to compatibility with UNIX `troff').
|
|||
|
|
|||
|
|
|||
|
.nr xxx 1
|
|||
|
.ie ! r xxx \
|
|||
|
true
|
|||
|
.el \
|
|||
|
false
|
|||
|
=> r xxx true
|
|||
|
|
|||
|
It is possible to omit the whitespace before the argument to the
|
|||
|
`r', `d', and `c' operators.
|
|||
|
|
|||
|
*Note Expressions::.
|
|||
|
|
|||
|
|
|||
|
File: groff, Node: Operators in Conditionals-Footnotes, Up: Operators in Conditionals
|
|||
|
|
|||
|
(1) The created output nodes must be identical. *Note Gtroff
|
|||
|
Internals::.
|
|||
|
|
|||
|
(2) The name of this conditional operator is a misnomer since it
|
|||
|
tests names of output glyphs.
|
|||
|
|
|||
|
|
|||
|
File: groff, Node: if-else, Next: while, Prev: Operators in Conditionals, Up: Conditionals and Loops
|
|||
|
|
|||
|
if-else
|
|||
|
-------
|
|||
|
|
|||
|
`gtroff' has if-then-else constructs like other languages, although
|
|||
|
the formatting can be painful.
|
|||
|
|
|||
|
- Request: .if expr anything
|
|||
|
Evaluate the expression EXPR, and executes ANYTHING (the remainder
|
|||
|
of the line) if EXPR evaluates to non-zero (true). ANYTHING is
|
|||
|
interpreted as though it was on a line by itself (except that
|
|||
|
leading spaces are swallowed). *Note Expressions::, for more info.
|
|||
|
|
|||
|
|
|||
|
.nr xxx 1
|
|||
|
.nr yyy 2
|
|||
|
.if ((\n[xxx] == 1) & (\n[yyy] == 2)) true
|
|||
|
=> true
|
|||
|
|
|||
|
|
|||
|
- Request: .nop anything
|
|||
|
Executes ANYTHING. This is similar to `.if 1'.
|
|||
|
|
|||
|
- Request: .ie expr anything
|
|||
|
- Request: .el anything
|
|||
|
Use the `ie' and `el' requests to write an if-then-else. The
|
|||
|
first request is the `if' part and the latter is the `else' part.
|
|||
|
|
|||
|
|
|||
|
.ie n .ls 2 \" double-spacing in nroff
|
|||
|
.el .ls 1 \" single-spacing in troff
|
|||
|
|
|||
|
|
|||
|
- Escape: \{
|
|||
|
- Escape: \}
|
|||
|
In many cases, an if (or if-else) construct needs to execute more
|
|||
|
than one request. 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 "\}
|
|||
|
|
|||
|
|
|||
|
*Note Expressions::.
|
|||
|
|
|||
|
|
|||
|
File: groff, Node: while, Prev: if-else, Up: Conditionals and Loops
|
|||
|
|
|||
|
while
|
|||
|
-----
|
|||
|
|
|||
|
`gtroff' provides a looping construct using the `while' request,
|
|||
|
which is used much like the `if' (and related) requests.
|
|||
|
|
|||
|
- Request: .while expr anything
|
|||
|
Evaluate the expression EXPR, and repeatedly execute ANYTHING (the
|
|||
|
remainder of the line) until EXPR evaluates to 0.
|
|||
|
|
|||
|
|
|||
|
.nr a 0 1
|
|||
|
.while (\na < 9) \{\
|
|||
|
\n+a,
|
|||
|
.\}
|
|||
|
\n+a
|
|||
|
=> 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
|
|||
|
|
|||
|
Some remarks.
|
|||
|
|
|||
|
* The body of a `while' request is treated like the body of a
|
|||
|
`de' request: `gtroff' temporarily stores it in a macro which
|
|||
|
is deleted after the loop has been exited. It can
|
|||
|
considerably slow down a macro if the body of the `while'
|
|||
|
request (within the macro) is large. Each time the macro is
|
|||
|
executed, the `while' body is parsed and stored again as a
|
|||
|
temporary macro.
|
|||
|
|
|||
|
|
|||
|
.de xxx
|
|||
|
. nr num 10
|
|||
|
. while (\\n[num] > 0) \{\
|
|||
|
. \" many lines of code
|
|||
|
. nr num -1
|
|||
|
. \}
|
|||
|
..
|
|||
|
|
|||
|
The traditional and ofter better solution (UNIX `troff'
|
|||
|
doesn't have the `while' request) is to use a recursive macro
|
|||
|
instead which is parsed only once during its definition.
|
|||
|
|
|||
|
|
|||
|
.de yyy
|
|||
|
. if (\\n[num] > 0) \{\
|
|||
|
. \" many lines of code
|
|||
|
. nr num -1
|
|||
|
. yyy
|
|||
|
. \}
|
|||
|
..
|
|||
|
.
|
|||
|
.de xxx
|
|||
|
. nr num 10
|
|||
|
. yyy
|
|||
|
..
|
|||
|
|
|||
|
Note that the number of available recursion levels is set
|
|||
|
to 1000 (this is a compile-time constant value of `gtroff').
|
|||
|
|
|||
|
* The closing brace of a `while' body must end a line.
|
|||
|
|
|||
|
|
|||
|
.if 1 \{\
|
|||
|
. nr a 0 1
|
|||
|
. while (\n[a] < 10) \{\
|
|||
|
. nop \n+[a]
|
|||
|
.\}\}
|
|||
|
=> unbalanced \{ \}
|
|||
|
|
|||
|
|
|||
|
- Request: .break
|
|||
|
Break out of a `while' loop. Be sure not to confuse this with the
|
|||
|
`br' request (causing a line break).
|
|||
|
|
|||
|
- Request: .continue
|
|||
|
Finish the current iteration of a `while' loop, immediately
|
|||
|
restarting the next iteration.
|
|||
|
|
|||
|
*Note Expressions::.
|
|||
|
|
|||
|
|
|||
|
File: groff, Node: Writing Macros, Next: Page Motions, Prev: Conditionals and Loops, Up: gtroff Reference
|
|||
|
|
|||
|
Writing Macros
|
|||
|
==============
|
|||
|
|
|||
|
A "macro" is a collection of text and embedded commands which can be
|
|||
|
invoked multiple times. Use macros to define common operations.
|
|||
|
|
|||
|
- Request: .de name [end]
|
|||
|
- Request: .de1 name [end]
|
|||
|
- Request: .dei name [end]
|
|||
|
Define a new macro named NAME. `gtroff' copies subsequent lines
|
|||
|
(starting with the next one) into an internal buffer until it
|
|||
|
encounters the line `..' (two dots). The optional second argument
|
|||
|
to `de' changes this to a macro to `.END'.
|
|||
|
|
|||
|
There can be whitespace after the first dot in the line containing
|
|||
|
the ending token (either `.' or macro `END').
|
|||
|
|
|||
|
Here a small example macro called `P' which causes a break and
|
|||
|
inserts some vertical space. It could be used to separate
|
|||
|
paragraphs.
|
|||
|
|
|||
|
|
|||
|
.de P
|
|||
|
. br
|
|||
|
. sp .8v
|
|||
|
..
|
|||
|
|
|||
|
The following example defines a macro within another. Remember
|
|||
|
that expansion must be protected twice; once for reading the macro
|
|||
|
and once for executing.
|
|||
|
|
|||
|
|
|||
|
\# a dummy macro to avoid a warning
|
|||
|
.de end
|
|||
|
..
|
|||
|
.
|
|||
|
.de foo
|
|||
|
. de bar end
|
|||
|
. nop \f[B]Hallo \\\\$1!\f[]
|
|||
|
. end
|
|||
|
..
|
|||
|
.
|
|||
|
.foo
|
|||
|
.bar Joe
|
|||
|
=> Hallo Joe!
|
|||
|
|
|||
|
Since `\f' has no expansion, it isn't necessary to protect its
|
|||
|
backslash. Had we defined another macro within `bar' which takes
|
|||
|
a parameter, eight backslashes would be necessary before `$1'.
|
|||
|
|
|||
|
The `de1' request turns off compatibility mode while executing the
|
|||
|
macro. On entry, the current compatibility mode is saved and
|
|||
|
restored at exit.
|
|||
|
|
|||
|
|
|||
|
.nr xxx 12345
|
|||
|
.
|
|||
|
.de aa
|
|||
|
The value of xxx is \\n[xxx].
|
|||
|
..
|
|||
|
.de1 bb
|
|||
|
The value of xxx ix \\n[xxx].
|
|||
|
..
|
|||
|
.
|
|||
|
.cp 1
|
|||
|
.
|
|||
|
.aa
|
|||
|
=> warning: number register ' not defined
|
|||
|
=> The value of xxx is 0xxx].
|
|||
|
.bb
|
|||
|
=> The value of xxx ix 12345.
|
|||
|
|
|||
|
The `dei' request defines a macro indirectly. That is, it expands
|
|||
|
strings whose names are NAME or END before performing the append.
|
|||
|
|
|||
|
This:
|
|||
|
|
|||
|
|
|||
|
.ds xx aa
|
|||
|
.ds yy bb
|
|||
|
.dei xx yy
|
|||
|
|
|||
|
is equivalent to:
|
|||
|
|
|||
|
|
|||
|
.de aa bb
|
|||
|
|
|||
|
Using `trace.tmac', you can trace calls to `de' and `de1'.
|
|||
|
|
|||
|
Note that macro identifiers are shared with identifiers for
|
|||
|
strings and diversions.
|
|||
|
|
|||
|
- Request: .am xx
|
|||
|
- Request: .am1 xx
|
|||
|
- Request: .ami xx yy
|
|||
|
Works similarly to `de' except it appends onto the macro named XX.
|
|||
|
So, to make the previously defined `P' macro actually do indented
|
|||
|
instead of block paragraphs, add the necessary code to the
|
|||
|
existing macro like this:
|
|||
|
|
|||
|
|
|||
|
.am P
|
|||
|
.ti +5n
|
|||
|
..
|
|||
|
|
|||
|
The `am1' request turns off compatibility mode while executing the
|
|||
|
appended macro piece. To be more precise, a "compatibility save"
|
|||
|
input token is inserted at the beginning of the appended code, and
|
|||
|
a "compatibility restore" input token at the end.
|
|||
|
|
|||
|
The `ami' request appends indirectly, meaning that `gtroff'
|
|||
|
expands strings whose names are XX or YY before performing the
|
|||
|
append.
|
|||
|
|
|||
|
Using `trace.tmac', you can trace calls to `am' and `am1'.
|
|||
|
|
|||
|
*Note Strings::, for the `als' request to rename a macro.
|
|||
|
|
|||
|
The `de', `am', `di', `da', `ds', and `as' requests (together with
|
|||
|
its variants) only create a new object if the name of the macro,
|
|||
|
diversion or string diversion is currently undefined or if it is
|
|||
|
defined to be a request; normally they modify the value of an existing
|
|||
|
object.
|
|||
|
|
|||
|
- Request: .return
|
|||
|
Exit a macro, immediately returning to the caller.
|
|||
|
|
|||
|
* Menu:
|
|||
|
|
|||
|
* Copy-in Mode::
|
|||
|
* Parameters::
|
|||
|
|
|||
|
|
|||
|
File: groff, Node: Copy-in Mode, Next: Parameters, Prev: Writing Macros, Up: Writing Macros
|
|||
|
|
|||
|
Copy-in Mode
|
|||
|
------------
|
|||
|
|
|||
|
When `gtroff' reads in the text for a macro, string, or diversion,
|
|||
|
it copies the text (including request lines, but excluding escapes) into
|
|||
|
an internal buffer. Escapes are 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.
|
|||
|
|
|||
|
The following example prints the numbers 20 and 10:
|
|||
|
|
|||
|
|
|||
|
.nr x 20
|
|||
|
.de y
|
|||
|
.nr x 10
|
|||
|
\&\nx
|
|||
|
\&\\nx
|
|||
|
..
|
|||
|
.y
|
|||
|
|
|||
|
|
|||
|
File: groff, Node: Parameters, Prev: Copy-in Mode, Up: Writing Macros
|
|||
|
|
|||
|
Parameters
|
|||
|
----------
|
|||
|
|
|||
|
The arguments to a macro or string can be examined using a variety of
|
|||
|
escapes.
|
|||
|
|
|||
|
- Register: \n[.$]
|
|||
|
The number of arguments passed to a macro or string. This is a
|
|||
|
read-only number register.
|
|||
|
|
|||
|
Any individual argument can be retrieved with one of the following
|
|||
|
escapes:
|
|||
|
|
|||
|
- Escape: \$N
|
|||
|
- Escape: \$(NN
|
|||
|
- Escape: \$[NNN]
|
|||
|
Retrieve the Nth, NNth or NNNth argument. As usual, the first
|
|||
|
form only accepts a single number (larger than zero), the second a
|
|||
|
two-digit number (larger or equal to 10), and the third any
|
|||
|
positive integer value (larger than zero). Macros and strings can
|
|||
|
have an unlimited number of arguments. Note that due to copy-in
|
|||
|
mode, use two backslashes on these in actual use to prevent
|
|||
|
interpolation until the macro is actually invoked.
|
|||
|
|
|||
|
- Request: .shift [n]
|
|||
|
Shift the arguments 1 position, or as many positions as specified
|
|||
|
by its argument. After executing this request, argument I becomes
|
|||
|
argument I-N; arguments 1 to N are no longer available. Shifting
|
|||
|
by negative amounts is currently undefined.
|
|||
|
|
|||
|
- Escape: \$*
|
|||
|
- Escape: \$@
|
|||
|
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 concatenates all the arguments separated by spaces. A
|
|||
|
similar escape is `\$@', which concatenates all the arguments with
|
|||
|
each surrounded by double quotes, and separated by spaces. If not
|
|||
|
in compatibility mode, the input level of double quotes is
|
|||
|
preserved (see *Note Request Arguments::).
|
|||
|
|
|||
|
- Escape: \$0
|
|||
|
The name used to invoke the current macro. The `als' request can
|
|||
|
make a macro have more than one name.
|
|||
|
|
|||
|
|
|||
|
.de generic-macro
|
|||
|
. ...
|
|||
|
. if \\n[error] \{\
|
|||
|
. tm \\$0: Houston, we have a problem.
|
|||
|
. return
|
|||
|
. \}
|
|||
|
..
|
|||
|
.
|
|||
|
.als foo generic-macro
|
|||
|
.als bar generic-macro
|
|||
|
|
|||
|
|
|||
|
*Note Request Arguments::.
|
|||
|
|
|||
|
|
|||
|
File: groff, Node: Page Motions, Next: Drawing Requests, Prev: Writing Macros, Up: gtroff Reference
|
|||
|
|
|||
|
Page Motions
|
|||
|
============
|
|||
|
|
|||
|
*Note Manipulating Spacing::, for a discussion of the main request
|
|||
|
for vertical motion, `sp'.
|
|||
|
|
|||
|
- Request: .mk [reg]
|
|||
|
- Request: .rt [dist]
|
|||
|
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 stores the location in an internal register. The
|
|||
|
results of this can be used later by the `rt' or the `sp' request
|
|||
|
(or the `\v' escape).
|
|||
|
|
|||
|
The `rt' request returns _upwards_ to the location marked with the
|
|||
|
last `mk' request. If used with an argument, return to a position
|
|||
|
which distance from the top of the page is DIST (no previous call
|
|||
|
to `mk' is necessary in this case). Default scaling indicator is
|
|||
|
`v'.
|
|||
|
|
|||
|
Here a primitive solution for a two-column macro.
|
|||
|
|
|||
|
|
|||
|
.nr column-length 1.5i
|
|||
|
.nr column-gap 4m
|
|||
|
.nr bottom-margin 1m
|
|||
|
.
|
|||
|
|
|||
|
|
|||
|
.de 2c
|
|||
|
. br
|
|||
|
. mk
|
|||
|
. ll \\n[column-length]u
|
|||
|
. wh -\\n[bottom-margin]u 2c-trap
|
|||
|
. nr right-side 0
|
|||
|
..
|
|||
|
.
|
|||
|
|
|||
|
|
|||
|
.de 2c-trap
|
|||
|
. ie \\n[right-side] \{\
|
|||
|
. nr right-side 0
|
|||
|
. po -(\\n[column-length]u + \\n[column-gap]u)
|
|||
|
. \" remove trap
|
|||
|
. wh -\\n[bottom-margin]u
|
|||
|
. \}
|
|||
|
. el \{\
|
|||
|
. \" switch to right side
|
|||
|
. nr right-side 1
|
|||
|
. po +(\\n[column-length]u + \\n[column-gap]u)
|
|||
|
. rt
|
|||
|
. \}
|
|||
|
..
|
|||
|
.
|
|||
|
|
|||
|
|
|||
|
.pl 1.5i
|
|||
|
.ll 4i
|
|||
|
This is a small test which shows how the
|
|||
|
rt request works in combination with mk.
|
|||
|
|
|||
|
.2c
|
|||
|
Starting here, text is typeset in two columns.
|
|||
|
Note that this implementation isn't robust
|
|||
|
and thus not suited for a real two-column
|
|||
|
macro.
|
|||
|
|
|||
|
Result:
|
|||
|
|
|||
|
|
|||
|
This is a small test which shows how the
|
|||
|
rt request works in combination with mk.
|
|||
|
|
|||
|
Starting here, isn't robust
|
|||
|
text is typeset and thus not
|
|||
|
in two columns. suited for a
|
|||
|
Note that this real two-column
|
|||
|
implementation macro.
|
|||
|
|
|||
|
|
|||
|
The following escapes give fine control of movements about the page.
|
|||
|
|
|||
|
- Escape: \v'E'
|
|||
|
Move vertically, usually from the current location on the page (if
|
|||
|
no absolute position operator `|' is used). The argument E
|
|||
|
specifies the distance to move; positive is downwards and negative
|
|||
|
upwards. The default scaling indicator for this escape is `v'.
|
|||
|
Beware, however, that `gtroff' continues text processing at the
|
|||
|
point where the motion ends, so you should always balance motions
|
|||
|
to avoid interference with text processing.
|
|||
|
|
|||
|
`\v' doesn't trigger a trap. This can be quite useful; for
|
|||
|
example, consider a page bottom trap macro which prints a marker
|
|||
|
in the margin to indicate continuation of a footnote or something
|
|||
|
similar.
|
|||
|
|
|||
|
There are some special-case escapes for vertical motion.
|
|||
|
|
|||
|
- Escape: \r
|
|||
|
Move upwards 1v.
|
|||
|
|
|||
|
- Escape: \u
|
|||
|
Move upwards .5v.
|
|||
|
|
|||
|
- Escape: \d
|
|||
|
Move down .5v.
|
|||
|
|
|||
|
- Escape: \h'E'
|
|||
|
Move horizontally, usually from the current location (if no
|
|||
|
absolute position operator `|' is used). The expression E
|
|||
|
indicates how far to move: positive is rightwards and negative
|
|||
|
leftwards. The default scaling indicator for this escape is `m'.
|
|||
|
|
|||
|
There are a number of special-case escapes for horizontal motion.
|
|||
|
|
|||
|
- Escape: \<SP>
|
|||
|
An unbreakable and unpaddable (i.e. not expanded during filling)
|
|||
|
space. (Note: This is a backslash followed by a space.)
|
|||
|
|
|||
|
- Escape: \~
|
|||
|
An unbreakable space that stretches like a normal inter-word space
|
|||
|
when a line is adjusted.
|
|||
|
|
|||
|
- Escape: \|
|
|||
|
A 1/6th em space. Ignored for TTY output devices (rounded to
|
|||
|
zero).
|
|||
|
|
|||
|
- Escape: \^
|
|||
|
A 1/12th em space. Ignored for TTY output devices (rounded to
|
|||
|
zero).
|
|||
|
|
|||
|
- Escape: \0
|
|||
|
A space the size of a digit.
|
|||
|
|
|||
|
The following string sets the TeX logo:
|
|||
|
|
|||
|
|
|||
|
.ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
|
|||
|
|
|||
|
- Escape: \w'TEXT'
|
|||
|
- Register: \n[st]
|
|||
|
- Register: \n[sb]
|
|||
|
- Register: \n[rst]
|
|||
|
- Register: \n[rsb]
|
|||
|
- Register: \n[ct]
|
|||
|
- Register: \n[ssc]
|
|||
|
- Register: \n[skw]
|
|||
|
Return the width of the specified TEXT in basic units. This
|
|||
|
allows horizontal movement based on the width of some arbitrary
|
|||
|
text (e.g. given as an argument to a macro).
|
|||
|
|
|||
|
|
|||
|
The length of the string `abc' is \w'abc'u.
|
|||
|
=> The length of the string `abc' is 72u.
|
|||
|
|
|||
|
Font changes may occur in TEXT which don't affect current settings.
|
|||
|
|
|||
|
After use, `\w' sets several registers:
|
|||
|
|
|||
|
`st'
|
|||
|
`sb'
|
|||
|
The highest and lowest point of the baseline, respectively,
|
|||
|
in TEXT.
|
|||
|
|
|||
|
`rst'
|
|||
|
`rsb'
|
|||
|
Like the `st' and `sb' registers, but takes account of the
|
|||
|
heights and depths of glyphs. With other words, this gives
|
|||
|
the highest and lowest point of TEXT.
|
|||
|
|
|||
|
`ct'
|
|||
|
Defines the kinds of glyphs occurring in TEXT:
|
|||
|
|
|||
|
0
|
|||
|
only short glyphs, no descenders or tall glyphs.
|
|||
|
|
|||
|
1
|
|||
|
at least one descender.
|
|||
|
|
|||
|
2
|
|||
|
at least one tall glyph.
|
|||
|
|
|||
|
3
|
|||
|
at least one each of a descender and a tall glyph.
|
|||
|
|
|||
|
`ssc'
|
|||
|
The amount of horizontal space (possibly negative) that
|
|||
|
should be added to the last glyph before a subscript.
|
|||
|
|
|||
|
`skw'
|
|||
|
How far to right of the center of the last glyph in the `\w'
|
|||
|
argument, the center of an accent from a roman font should be
|
|||
|
placed over that glyph.
|
|||
|
|
|||
|
- Escape: \kP
|
|||
|
- Escape: \k(PS
|
|||
|
- Escape: \k[POSITION]
|
|||
|
Store the current horizontal position in the _input_ line in
|
|||
|
number register with name POSITION (one-character name P,
|
|||
|
two-character name PS). Use this, for example, to return to the
|
|||
|
beginning of a string for highlighting or other decoration.
|
|||
|
|
|||
|
- Register: \n[hp]
|
|||
|
The current horizontal position at the input line.
|
|||
|
|
|||
|
- Register: \n[.k]
|
|||
|
A read-only number register containing the current horizontal
|
|||
|
output position.
|
|||
|
|
|||
|
- Escape: \o'ABC'
|
|||
|
Overstrike glyphs A, B, C, ...; the glyphs are centered, and the
|
|||
|
resulting spacing is the largest width of the affected glyphs.
|
|||
|
|
|||
|
- Escape: \zG
|
|||
|
Print glyph G with zero width, i.e., without spacing. Use this to
|
|||
|
overstrike glyphs left-aligned.
|
|||
|
|
|||
|
- Escape: \Z'ANYTHING'
|
|||
|
Print ANYTHING, then restore the horizontal and vertical position.
|
|||
|
The argument may not contain tabs or leaders.
|
|||
|
|
|||
|
The following is an example of a strike-through macro:
|
|||
|
|
|||
|
|
|||
|
.de ST
|
|||
|
.nr ww \w'\\$1'
|
|||
|
\Z@\v'-.25m'\l'\\n[ww]u'@\\$1
|
|||
|
..
|
|||
|
.
|
|||
|
This is
|
|||
|
.ST "a test"
|
|||
|
an actual emergency!
|
|||
|
|
|||
|
|
|||
|
|
|||
|
File: groff, Node: Drawing Requests, Next: Traps, Prev: Page Motions, Up: gtroff Reference
|
|||
|
|
|||
|
Drawing Requests
|
|||
|
================
|
|||
|
|
|||
|
`gtroff' provides a number of ways to draw lines and other figures
|
|||
|
on the page. Used in combination with the page motion commands (see
|
|||
|
*Note 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'. *Note gpic::, and *Note ggrn::, for more information.
|
|||
|
|
|||
|
All drawing is done via escapes.
|
|||
|
|
|||
|
- Escape: \l'L'
|
|||
|
- Escape: \l'LG'
|
|||
|
Draw a line horizontally. L is the length of the line to be
|
|||
|
drawn. If it is positive, start the line at the current location
|
|||
|
and draw to the right; its end point is the new current location.
|
|||
|
Negative values are handled differently: The line starts at the
|
|||
|
current location and draws to the left, but the current location
|
|||
|
doesn't move.
|
|||
|
|
|||
|
L can also be specified absolutely (i.e. with a leading `|') which
|
|||
|
draws back to the beginning of the input line. Default scaling
|
|||
|
indicator is `m'.
|
|||
|
|
|||
|
The optional second parameter G is a glyph to draw the line with.
|
|||
|
If this second argument is not specified, `gtroff' uses the
|
|||
|
underscore glyph, `\[ru]'.
|
|||
|
|
|||
|
To separate the two arguments (to prevent `gtroff' from
|
|||
|
interpreting a drawing glyph as a scaling indicator if the glyph is
|
|||
|
represented by a single character) 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.
|
|||
|
Finally, the line drawing escapes both draw from the current
|
|||
|
location to the beginning of the _input_ line - this works because
|
|||
|
the line length is negative, not moving the current point.
|
|||
|
|
|||
|
- Escape: \L'L'
|
|||
|
- Escape: \L'LG'
|
|||
|
Draw vertical lines. Its parameters are similar to the `\l'
|
|||
|
escape, except that the default scaling indicator is `v'. The
|
|||
|
movement is downwards for positive values, and upwards for
|
|||
|
negative values. The default glyph is the box rule glyph,
|
|||
|
`\[br]'. As with the vertical motion escapes, text processing
|
|||
|
blindly continues where the line ends.
|
|||
|
|
|||
|
|
|||
|
This is a \L'3v'test.
|
|||
|
|
|||
|
Here the result, produced with `grotty'.
|
|||
|
|
|||
|
|
|||
|
This is a
|
|||
|
|
|
|||
|
|
|
|||
|
|test.
|
|||
|
|
|||
|
|
|||
|
- Escape: \D'COMMAND ARG ...'
|
|||
|
The `\D' escape provides a variety of drawing functions. Note
|
|||
|
that on character devices, only vertical and horizontal lines are
|
|||
|
supported within `grotty'; other devices may only support a subset
|
|||
|
of the available drawing functions.
|
|||
|
|
|||
|
The default scaling indicator for all subcommands of `\D' is `m'
|
|||
|
for horizontal distances and `v' for vertical ones. Exceptions
|
|||
|
are `\D'f ...'' and `\D't ...'' which use `u' as the default.
|
|||
|
|
|||
|
`\D'l DX DY''
|
|||
|
Draw a line from the current location to the relative point
|
|||
|
specified by (DX,DY).
|
|||
|
|
|||
|
The following example is a macro for creating a box around a
|
|||
|
text string; for simplicity, the box margin is taken as a
|
|||
|
fixed value, 0.2m.
|
|||
|
|
|||
|
|
|||
|
.de BOX
|
|||
|
. nr @wd \w'\\$1'
|
|||
|
\h'.2m'\
|
|||
|
\h'-.2m'\v'(.2m - \\n[rsb]u)'\
|
|||
|
\D'l 0 -(\\n[rst]u - \\n[rsb]u + .4m)'\
|
|||
|
\D'l (\\n[@wd]u + .4m) 0'\
|
|||
|
\D'l 0 (\\n[rst]u - \\n[rsb]u + .4m)'\
|
|||
|
\D'l -(\\n[@wd]u + .4m) 0'\
|
|||
|
\h'.2m'\v'-(.2m - \\n[rsb]u)'\
|
|||
|
\\$1\
|
|||
|
\h'.2m'
|
|||
|
..
|
|||
|
|
|||
|
First, the width of the string is stored in register `@wd'.
|
|||
|
Then, four lines are drawn to form a box, properly offset by
|
|||
|
the box margin. The registers `rst' and `rsb' are set by the
|
|||
|
`\w' escape, containing the largest height and depth of the
|
|||
|
whole string.
|
|||
|
|
|||
|
`\D'c D''
|
|||
|
Draw a circle with a diameter of D with the leftmost point at
|
|||
|
the current position.
|
|||
|
|
|||
|
`\D'C D''
|
|||
|
Draw a solid circle with the same parameters as an outlined
|
|||
|
circle. No outline is drawn.
|
|||
|
|
|||
|
`\D'e X Y''
|
|||
|
Draw an ellipse with a horizontal diameter of X and a vertical
|
|||
|
diameter of Y with the leftmost point at the current position.
|
|||
|
|
|||
|
`\D'E X Y''
|
|||
|
Draw a solid ellipse with the same parameters as an outlined
|
|||
|
ellipse. No outline is drawn.
|
|||
|
|
|||
|
`\D'a DX1 DY1 DX2 DY2''
|
|||
|
Draw an arc clockwise from the current location through the
|
|||
|
two specified relative locations (DX1,DY1) and (DX2,DY2).
|
|||
|
The coordinates of the first point are relative to the
|
|||
|
current position, and the coordinates of the second point are
|
|||
|
relative to the first point.
|
|||
|
|
|||
|
`\D'~ DX1 DY1 DX2 DY2 ...''
|
|||
|
Draw a spline from the current location to the relative point
|
|||
|
(DX1,DY1) and then to (DX2,DY2), and so on.
|
|||
|
|
|||
|
`\D'f N''
|
|||
|
Set the shade of gray to be used for filling solid objects
|
|||
|
to N; N must be an integer between 0 and 1000, where 0
|
|||
|
corresponds solid white and 1000 to solid black, and values
|
|||
|
in between correspond to intermediate shades of gray. This
|
|||
|
applies only to solid circles, solid ellipses, and solid
|
|||
|
polygons. By default, a level of 1000 is used.
|
|||
|
|
|||
|
`\D'p DX1 DY1 DX2 DY2 ...''
|
|||
|
Draw a polygon from the current location to the relative
|
|||
|
position (DX1,DY1) and then to (DX2,DY2) and so on. When the
|
|||
|
specified data points are exhausted, a line is drawn back to
|
|||
|
the starting point.
|
|||
|
|
|||
|
`\D'P DX1 DY1 DX2 DY2 ...''
|
|||
|
Draw a solid polygon with the same parameters as an outlined
|
|||
|
polygon. No outline is drawn.
|
|||
|
|
|||
|
Here a better variant of the box macro to fill the box with
|
|||
|
some color. Note that the box must be drawn before the text
|
|||
|
since colors in `gtroff' are not transparent; the filled
|
|||
|
polygon would hide the text completely.
|
|||
|
|
|||
|
|
|||
|
.de BOX
|
|||
|
. nr @wd \w'\\$1'
|
|||
|
\h'.2m'\
|
|||
|
\h'-.2m'\v'(.2m - \\n[rsb]u)'\
|
|||
|
\M[lightcyan]\
|
|||
|
\D'P 0 -(\\n[rst]u - \\n[rsb]u + .4m) \
|
|||
|
(\\n[@wd]u + .4m) 0 \
|
|||
|
0 (\\n[rst]u - \\n[rsb]u + .4m) \
|
|||
|
-(\\n[@wd]u + .4m) 0'\
|
|||
|
\h'.2m'\v'-(.2m - \\n[rsb]u)'\
|
|||
|
\M[]\
|
|||
|
\\$1\
|
|||
|
\h'.2m'
|
|||
|
..
|
|||
|
|
|||
|
`\D't N''
|
|||
|
Set the current line thickness to N machine units. A value of
|
|||
|
zero selects the smallest available line thickness. A
|
|||
|
negative value makes the line thickness proportional to the
|
|||
|
current point size (this is the default behaviour of AT&T
|
|||
|
`troff').
|
|||
|
|
|||
|
*Note Graphics Commands::.
|
|||
|
|
|||
|
- Escape: \b'STRING'
|
|||
|
"Pile" a sequence of glyphs vertically, and center it vertically
|
|||
|
on the current line. Use it to build large brackets and braces.
|
|||
|
|
|||
|
Here an example how to create a large opening brace:
|
|||
|
|
|||
|
|
|||
|
\b'\[lt]\[bv]\[lk]\[bv]\[lb]'
|
|||
|
|
|||
|
The first glyph is on the top, the last glyph in STRING is at the
|
|||
|
bottom. Note that `gtroff' separates the glyphs vertically by 1m,
|
|||
|
and the whole object is centered 0.5m above the current baseline;
|
|||
|
the largest glyph width is used as the width for the whole object.
|
|||
|
This rather unflexible positioning algorithm doesn't work with
|
|||
|
`-Tdvi' since the bracket pieces vary in height for this device.
|
|||
|
Instead, use the `eqn' preprocessor.
|
|||
|
|
|||
|
*Note Manipulating Spacing::, how to adjust the vertical spacing
|
|||
|
with the `\x' escape.
|
|||
|
|
|||
|
|
|||
|
File: groff, Node: Traps, Next: Diversions, Prev: Drawing Requests, Up: gtroff Reference
|
|||
|
|
|||
|
Traps
|
|||
|
=====
|
|||
|
|
|||
|
"Traps" are locations, which, when reached, call a specified macro.
|
|||
|
These traps can occur at a given location on the page, at a given
|
|||
|
location in the current diversion, at a blank line, after a certain
|
|||
|
number of input lines, or at the end of input.
|
|||
|
|
|||
|
Setting a trap is also called "planting". It is also said that a
|
|||
|
trap is "sprung" if the associated macro is executed.
|
|||
|
|
|||
|
* Menu:
|
|||
|
|
|||
|
* Page Location Traps::
|
|||
|
* Diversion Traps::
|
|||
|
* Input Line Traps::
|
|||
|
* Blank Line Traps::
|
|||
|
* End-of-input Traps::
|
|||
|
|
|||
|
|
|||
|
File: groff, Node: Page Location Traps, Next: Diversion Traps, Prev: Traps, Up: Traps
|
|||
|
|
|||
|
Page Location Traps
|
|||
|
-------------------
|
|||
|
|
|||
|
"Page location traps" perform an action when `gtroff' reaches or
|
|||
|
passes a certain vertical location on the page. Page location traps
|
|||
|
have a variety of purposes, including:
|
|||
|
|
|||
|
* setting headers and footers
|
|||
|
|
|||
|
* setting body text in multiple columns
|
|||
|
|
|||
|
* setting footnotes
|
|||
|
|
|||
|
- Request: .vpt flag
|
|||
|
- Register: \n[.vpt]
|
|||
|
Enable vertical position traps if FLAG is non-zero, or disables
|
|||
|
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
|
|||
|
`.vpt' read-only number register.
|
|||
|
|
|||
|
- Request: .wh dist [macro]
|
|||
|
Set a page location trap. Positive values for DIST set the trap
|
|||
|
relative to the top of the page; negative values set the trap
|
|||
|
relative to the bottom of the page. Default scaling indicator is
|
|||
|
`v'.
|
|||
|
|
|||
|
MACRO is the name of the macro to execute when the trap is sprung.
|
|||
|
If MACRO is missing, remove the first trap (if any) at DIST.
|
|||
|
|
|||
|
The following is a simple example of how many macro packages set
|
|||
|
headers and footers.
|
|||
|
|
|||
|
|
|||
|
.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
|
|||
|
|
|||
|
A trap at or below the bottom of the page is ignored; it can be
|
|||
|
made active by either moving it up or increasing the page length
|
|||
|
so that the trap is on the page.
|
|||
|
|
|||
|
It is possible to have more than one trap at the same location; to
|
|||
|
do so, the traps must be defined at different locations, then
|
|||
|
moved together with the `ch' request; otherwise the second trap
|
|||
|
would replace the first one. Earlier defined traps hide later
|
|||
|
defined traps if moved to the same position (the many empty lines
|
|||
|
caused by the `bp' request are omitted):
|
|||
|
|
|||
|
|
|||
|
.de a
|
|||
|
. nop a
|
|||
|
..
|
|||
|
.de b
|
|||
|
. nop b
|
|||
|
..
|
|||
|
.de c
|
|||
|
. nop c
|
|||
|
..
|
|||
|
.
|
|||
|
.wh 1i a
|
|||
|
.wh 2i b
|
|||
|
.wh 3i c
|
|||
|
.bp
|
|||
|
=> a b c
|
|||
|
|
|||
|
|
|||
|
.ch b 1i
|
|||
|
.ch c 1i
|
|||
|
.bp
|
|||
|
=> a
|
|||
|
|
|||
|
|
|||
|
.ch a 0.5i
|
|||
|
.bp
|
|||
|
=> a b
|
|||
|
|
|||
|
|
|||
|
- Register: \n[.t]
|
|||
|
A read-only number register holding the distance to the next trap.
|
|||
|
|
|||
|
If there are no traps between the current position and the bottom
|
|||
|
of the page, it contains the distance to the page bottom. In a
|
|||
|
diversion, the distance to the page bottom is infinite (the
|
|||
|
returned value is the biggest integer which can be represented in
|
|||
|
`groff') if there are no diversion traps.
|
|||
|
|
|||
|
- Request: .ch macro dist
|
|||
|
Change the location of a trap. 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 (note that the parameters are
|
|||
|
specified the opposite of the `wh' request). This is useful for
|
|||
|
building up footnotes in a diversion to allow more space at the
|
|||
|
bottom of the page for them.
|
|||
|
|
|||
|
Default scaling indicator for DIST is `v'. If DIST is missing,
|
|||
|
the trap is removed.
|
|||
|
|
|||
|
|
|||
|
- Register: \n[.ne]
|
|||
|
The read-only 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. *Note
|
|||
|
Page Control::, for more information.
|
|||
|
|
|||
|
- Register: \n[.trunc]
|
|||
|
A read-only register containing the amount of vertical space
|
|||
|
truncated by the most recently sprung vertical position trap, or,
|
|||
|
if the trap was sprung by an `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.
|
|||
|
|
|||
|
|
|||
|
File: groff, Node: Diversion Traps, Next: Input Line Traps, Prev: Page Location Traps, Up: Traps
|
|||
|
|
|||
|
Diversion Traps
|
|||
|
---------------
|
|||
|
|
|||
|
- Request: .dt dist macro
|
|||
|
Set a trap _within_ a diversion. DIST is the location of the trap
|
|||
|
(identical to the `.wh' request; default scaling indicator is `v')
|
|||
|
and MACRO is the name of the macro to be invoked. The number
|
|||
|
register `.t' still works within diversions. *Note Diversions::,
|
|||
|
for more information.
|
|||
|
|
|||
|
|
|||
|
File: groff, Node: Input Line Traps, Next: Blank Line Traps, Prev: Diversion Traps, Up: Traps
|
|||
|
|
|||
|
Input Line Traps
|
|||
|
----------------
|
|||
|
|
|||
|
- Request: .it n macro
|
|||
|
- Request: .itc n macro
|
|||
|
Set an input line trap. N is the number of lines of input which
|
|||
|
may be read before springing the trap, MACRO 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 prints the
|
|||
|
next N lines in a bold font.
|
|||
|
|
|||
|
|
|||
|
.de B
|
|||
|
. it \\$1 B-end
|
|||
|
. ft B
|
|||
|
..
|
|||
|
.
|
|||
|
.de B-end
|
|||
|
. ft R
|
|||
|
..
|
|||
|
|
|||
|
The `itc' request is identical, except that a line interrupted
|
|||
|
with `\c' counts as one input line.
|
|||
|
|
|||
|
Both requests are associated with the current environment (*note
|
|||
|
Environments::); switching to another environment disables the
|
|||
|
current input trap, and going back reactivates it, restoring the
|
|||
|
number of already processed lines.
|
|||
|
|
|||
|
|
|||
|
File: groff, Node: Blank Line Traps, Next: End-of-input Traps, Prev: Input Line Traps, Up: Traps
|
|||
|
|
|||
|
Blank Line Traps
|
|||
|
----------------
|
|||
|
|
|||
|
- Request: .blm macro
|
|||
|
Set a blank line trap. `gtroff' executes MACRO when it encounters
|
|||
|
a blank line in the input file.
|
|||
|
|
|||
|
|
|||
|
File: groff, Node: End-of-input Traps, Prev: Blank Line Traps, Up: Traps
|
|||
|
|
|||
|
End-of-input Traps
|
|||
|
------------------
|
|||
|
|
|||
|
- Request: .em macro
|
|||
|
Set a trap at the end of input. MACRO is 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
|
|||
|
|
|||
|
|