Next: Conditionals and Loops, Previous: Sizes, Up: gtroff Reference [Contents][Index]
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).
Although the following requests can be used to create strings, simply using an undefined string will cause it to be defined as empty. See Identifiers.
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 that are handled identically to
macro arguments; the single exception is that a closing bracket as an
argument must be enclosed in double quotes. See Request and Macro Arguments, and 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
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.
In particular, interpolating a string does not hide existing macro arguments. Thus in a macro, a more efficient way of doing
.xx \\$@
is
\\*[xx]\\
Note that the latter calling syntax doesn’t change the value of
\$0, which is then inherited from the calling macro.
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.
See Gtroff Internals, for more information.
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.
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 implicitly set to the largest valid value (the string length minus one). 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
.substring xxx 2
\*[xxx]
⇒ de
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 \*[xxx]
\n[yyy]
⇒ 14
Rename the request, macro, diversion, or string xx to yy.
Remove the request, macro, diversion, or string xx. gtroff
treats subsequent invocations as if the object had never been defined.
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.
To understand how the als request works it is probably best to
think of two different pools: one pool for objects (macros, strings,
etc.), and another one for names. As soon as an object is defined,
gtroff adds it to the object pool, adds its name to the name
pool, and creates a link between them. When als creates an
alias, it adds a new name to the name pool that gets linked to the same
object as the old name.
Now consider this example.
.de foo
..
.
.als bar foo
.
.de bar
. foo
..
.
.bar
⇒ input stack limit exceeded
The definition of macro bar replaces the old object this name is
linked to. However, the alias to foo is still active! In
other words, foo is still linked to the same object as
bar, and the result of calling bar is an infinite,
recursive loop that finally leads to an error.
To undo an alias, simply call rm on the aliased name. The object
itself is not destroyed until there are no more aliases.
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 Gtroff Internals, for details on nodes
inserted additionally by gtroff.
See Identifiers, and Comments.
Next: Conditionals and Loops, Previous: Sizes, Up: gtroff Reference [Contents][Index]