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 (see 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 (see Environments).

See 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 (see 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. See 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.

  See 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 \!. See 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’.