5.13 Character Translations

A character translation remaps input characters, usually to make input more convenient. GNU troff performs the translation just before formatting the glyph; that is, right before it converts the character’s token to a node.¹⁵⁰

Request: .tr abcd…

Request: .trin abcd…

Translate character a to b, c to d, and so on prior to output. Unusually, spaces are not permitted between the arguments. If number of arguments is odd, the formatter translates the last to a fixed-width space (the same one obtained by the \SPC escape sequence).

The trin request works as does tr, except that asciify (see Diversions) ignores the translation when a diversion is interpolated.

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 \~ escape sequences (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\&’ (an arbitrary character c followed by the dummy character) maps this character to “nothing”.

  .tr a\&
  foo bar
      ⇒ foo br
  

  Even the space character can be mapped to the dummy character.

  .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 adjustment is enabled, it occurs in spite of the ‘empty’ space character; but no minimum distance—no minimum inter-word space—separates 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 elements of its argument exist.

  See GNU troff Internals.

• 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 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’.