GNU Info
(groff)Strings
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]
- Escape: \*N
- Escape: \*(NM
- Escape: \*[NAME]
Define and access a string variable NAME (one-character name N,
two-character name NM). If NAME already exists, `ds' overwrites
the previous definition.
Example:
.ds UX \s-1UNIX\s0\u\s-3tm\s0\d
.
The \*(UX Operating System
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. a string variables can be called within string
variables.
If the string named by the `\*' 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.
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. It is
not possible to pass arguments to a macro if called with `\*'.
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]
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,
Rudimentary string manipulation routines are given with the next two
requests.
- Request: .substring str n1 [n2]
Replace the string in register STR 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 is 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.
.ds xxx abcdefgh
.substring xxx 2 -3
\*[xxx]
=> bcde
- Request: .length reg str
Compute the length of STR and returns it in the number
register REG. If REG doesn't exist, it is created.
.ds xxx abcdefgh
.length yyy xxx
\n[yyy]
=> 8
- Request: .rn xx yy
Rename the request, macro, or string XX to YY.
- Request: .rm xx
Remove the request, macro, 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 by `gtroff' automatically.
Note: Identifiers, and Note: Comments.
automatically generated by info2www version 1.2.2.9