groff: Character Translations
5.11 Character Translations
===========================
The control character ('.') and the no-break control character (''') can
be changed with the 'cc' and 'c2' requests, respectively.
-- Request: .cc [c]
Set the control character to C. With no argument the default
control character '.' is restored. The value of the control
character is associated with the current environment (
Environments).
-- Request: .c2 [c]
Set the no-break control character to C. With no argument the
default control character ''' is restored. The value of the
no-break control character is associated with the current
environment (Environments).
Requests.
-- Request: .eo
Disable the escape mechanism completely. After executing this
request, the backslash character '\' no longer starts an escape
sequence.
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
-- Request: .ec [c]
Set the escape character to C. With no argument the default escape
character '\' is restored. It can be also used to re-enable the
escape mechanism after an 'eo' request.
Note that changing the escape character globally likely breaks
macro packages since 'gtroff' has no mechanism to 'intern' macros,
i.e., to convert a macro definition into an internal form that is
independent of its representation (TeX has this mechanism). If a
macro is called, it is executed literally.
-- Request: .ecs
-- Request: .ecr
The 'ecs' request saves the current escape character in an internal
register. Use this request in combination with the 'ec' request to
temporarily change the escape character.
The 'ecr' request restores the escape character saved with 'ecs'.
Without a previous call to 'ecs', this request sets the escape
character to '\'.
-- Escape: \\
-- Escape: \e
-- Escape: \E
Print the current escape character (which is the backslash
character '\' by default).
'\\' is a 'delayed' backslash; more precisely, it is the default
escape character followed by a backslash, which no longer has
special meaning due to the leading escape character. It is _not_
an escape sequence in the usual sense! In any unknown escape
sequence '\X' the escape character is ignored and X is printed.
But if X is equal to the current escape character, no warning is
emitted.
As a consequence, only at top-level or in a diversion a backslash
glyph is printed; in copy-in mode, it expands to a single
backslash, which then combines with the following character to an
escape sequence.
The '\E' escape differs from '\e' by printing an escape character
that is not interpreted in copy mode. Use this to define strings
with escapes that work when used in copy mode (for example, as a
macro argument). The following example defines strings to begin
and end a superscript:
.ds { \v'-.3m'\s'\En[.s]*60/100'
.ds } \s0\v'.3m'
Another example to demonstrate the differences between the various
escape sequences, using a strange escape character, '-'.
.ec -
.de xxx
--A'123'
..
.xxx
=> -A'foo'
The result is surprising for most users, expecting '1' since 'foo'
is a valid identifier. What has happened? As mentioned above, the
leading escape character makes the following character ordinary.
Written with the default escape character the sequence '--' becomes
'\-' - this is the minus sign.
If the escape character followed by itself is a valid escape
sequence, only '\E' yields the expected result:
.ec -
.de xxx
-EA'123'
..
.xxx
=> 1
-- Escape: \.
Similar to '\\', the sequence '\.' isn't a real escape sequence.
As before, a warning message is suppressed if the escape character
is followed by a dot, and the dot itself is printed.
.de foo
. nop foo
.
. de bar
. nop bar
\\..
.
..
.foo
.bar
=> foo bar
The first backslash is consumed while the macro is read, and the
second is swallowed while executing macro 'foo'.
A "translation" is a mapping of an input character to an output
glyph. The mapping occurs at output time, i.e., the input character
gets assigned the metric information of the mapped output character
right before input tokens are converted to nodes (Gtroff
Internals, for more on this process).
-- Request: .tr abcd...
-- Request: .trin abcd...
Translate character A to glyph B, character C to glyph D, etc. If
there is an odd number of arguments, the last one is translated to
an unstretchable space ('\ ').
The 'trin' request is identical to 'tr', but when you unformat a
diversion with 'asciify' it ignores the translation.
Diversions, for details about the 'asciify' request.
Some notes:
* Special characters ('\(XX', '\[XXX]', '\C'XXX'', '\'', '\`',
'\-', '\_'), glyphs defined with the 'char' request, and
numbered glyphs ('\N'XXX'') can be translated also.
* The '\e' escape can be translated also.
* Characters can be mapped onto the '\%' and '\~' escapes (but
'\%' and '\~' can't be mapped onto another glyph).
* The following characters can't be translated: space (with one
exception, see below), backspace, newline, leader (and '\a'),
tab (and '\t').
* Translations are not considered for finding the soft hyphen
character set with the 'shc' request.
* The pair 'C\&' (this is an arbitrary character C followed by
the zero width space character) maps this character to
nothing.
.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/glyph pair as an argument of 'tr'.
Additionally, it is not possible to map the space character to
any other glyph; requests like '.tr aa x' undo '.tr aa \&'
instead.
If justification is active, lines are justified in spite of
the 'empty' space character (but there is no minimal distance,
i.e. the space character, between words).
* After an output glyph has been constructed (this happens at
the moment immediately before the glyph is appended to an
output glyph list, either by direct output, in a macro,
diversion, or string), it is no longer affected by 'tr'.
* Translating character to glyphs where one of them or both are
undefined is possible also; 'tr' does not check whether the
entities in its argument do exist.
Gtroff Internals.
* 'troff' no longer has a hard-coded dependency on Latin-1; all
'charXXX' entities have been removed from the font description
files. This has a notable consequence that shows up in
warnings like 'can't find character with input code XXX' if
the 'tr' request isn't handled properly.
Consider the following translation:
.tr éÉ
This maps input character 'é' onto glyph 'É', which is
identical to glyph 'char201'. But this glyph intentionally
doesn't exist! Instead, '\[char201]' is treated as an input
character entity and is by default mapped onto '\['E]', and
'gtroff' doesn't handle translations of translations.
The right way to write the above translation is
.tr é\['E]
In other words, the first argument of 'tr' should be an input
character or entity, and the second one a glyph entity.
* Without an argument, the 'tr' request is ignored.
-- Request: .trnt abcd...
'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 '\!'. Diversions, for more information.
For example,
.tr ab
.di x
\!.tm a
.di
.x
prints 'b' to the standard error stream; if 'trnt' is used instead
of 'tr' it prints 'a'.
Info Catalog
groff: Tabs and Fields
groff: gtroff Reference
groff: Troff and Nroff Mode