groff_char - GNU roff special character and glyph repertoire
The GNU roff typesetting system has a large glyph repertoire suitable for production of varied literary, professional, technical, and mathematical documents. However, its input character set is restricted to that defined by the standards ISO Latin-1 (ISO 8859-1) and IBM code page 1047 (an arrangement of EBCDIC). For ease of document maintenance in UTF-8 environments, it is advisable to use only the Unicode basic Latin code points, a subset of all of the foregoing historically referred to as US-ASCII, which has only 94 visible, printable code points.
AT&T troff in the 1970s faced a similar problem of typesetter devices with a glyph repertoire differing from that of the computers that controlled them. The solution troff adopted was a form of escape sequence known as a special character to access several dozen additional glyphs available in the fonts prepared for mounting in the phototypesetter. These glyphs were mapped onto a two-character name space for a degree of mnemonic convenience; for example, the escape sequence \(aa encoded an acute accent and \(sc a section sign.
As in other respects, groff has removed historical roff limitations on the lengths of special character escapes, but recognizes and retains compatibility with the historical names. groff expands the lexicon of glyphs available by name and permits users to define their own special character escapes with the .char request.
This document lists all of the glyph names predefined by groff and describes the systematic notation by which it enables access to arbitrary Unicode code points and construction of composite glyphs. The glyphs listed in this document may not be available, or may vary in appearance, depending on the output driver chosen when the page was rendered (with the -T option to the man(1) or roff programs). The driver used in generation of this page was “html”.
A few escape sequences that are not special character escapes also produce glyphs; these exist for syntactical or historical reasons. They include \\, \', \`, \-, \. (backslash-dot), and \e; see groff(7). Of these, only \- is also available as a special character of the same name, in the form \[-]. A small number of special characters represent glyphs that are not encoded in Unicode; examples include the baseline rule \[ru] and the Bell Systems logo \[bs].
In groff, you can test output driver support for any character (ordinary or special) with the conditional “c”.
.ie c \[bs] \{Welcome to the
\[bs] Bell System;
did you get the Wehrmacht helmet or the Death Star?\}
.el No Bell Systems logo.
For brevity in the remainder of this document, we shall refer to systems conforming to the ISO 646:1991 IRV, ISO 8859, or ISO 10646 (“Unicode”) character encoding standards as “ISO” systems, and those employing IBM code page 1047 as “EBCDIC” systems. That said, EBCDIC systems that support groff are known to also support UTF-8.
While groff accepts eight-bit encoded input, not all such code points are valid as input. On ISO platforms, character codes 0, 11, 13–31, and 128–159 are invalid. (This is all C0 and C1 controls except for SOH through LF [Control+A to Control+J], and FF [Control+L].) On EBCDIC platforms, 0, 8–9, 11, 13–20, 23–31, and 48–63 are invalid. Some of these code points are used by groff for internal purposes, which is one reason it does not support UTF-8 natively.
The ninety-four characters catalogued above, plus the space and the newline, form the fundamental character set for groff input; anything in the language, even over one million code points in Unicode, can be expressed using it. On ISO systems, code points in the range 33–126 comprise a common set of printable glyphs in all of the aforementioned ISO character encoding standards. It is this character set and (with some noteworthy exceptions) the corresponding glyph repertoire for which AT&T troff was implemented. On EBCDIC systems, printable characters are in the range 66–201 and 203–254; those without counterparts in the ISO range 33–126 are discussed in the next subsection.
All of the following characters map to glyphs as you would expect.
The remaining seven of the ninety-four code points in this range surprise computing professionals and others intimately familiar with the ISO character encodings. The developers of AT&T troff chose mappings for them that would be useful for typesetting technical literature in a broad range of scientific disciplines; the preparation of AT&T’s patent filings with the U.S. government was the application of the system that “paid the bills” at the Bell Labs site where troff and Unix were first developed. It is also worth noting that the prevailing character encoding standard in the 1970s, USAS X3.4-1968 (“ASCII”) deliberately supported semantic ambiguity at some code points, and outright substitution at several others, to suit the localization demands of various national standards bodies.
The table below presents the seven exceptional code points with their typical keycap engravings, their glyph mappings and semantics in roff systems, and the escapes producing the Unicode basic Latin character they replace. The first, the neutral double quote, is a partial exception because it does represent itself, but since it is also used by roff systems to quote macro arguments, groff supports a special character escape as an alternative form so that the glyph can be easily included in macro arguments without requiring the user to master the quoting rules that AT&T troff required in that context. Furthermore, not all of the special character escapes are portable to AT&T troff and all of its descendants; these groff extensions are presented using its special character escape form \[], whereas portable special character escapes are shown in the traditional \( form. \- and \e are portable to all known troffs. \e means “the glyph of the current escape character”; it therefore can produce unexpected output if the .ec or .eo requests are used. On devices with a limited glyph repertoire, the appearances of glyphs on the same row of the table may be identical; except for the neutral double quote, this will not be the case on more-capable devices. Review your document using as many different postprocessors as possible.
The hyphen-minus is a particularly unfortunate case of overloading. Its awkward name in ISO 8859 and later standards reflects the many conflicting purposes to which it had already been put in the 1980s, including a hyphen, a minus sign, and (alone or in repetition) dashes of varying widths. For best results in groff, use the character in input without an escape only to mean a hyphen, as in the phrase “long-term”. For a minus sign in running prose or a Unix command-line option dash, use \- (or \[-] in groff if you find it helps the clarity of the source document). AT&T troff supported em-dashes as \(em.
The special character escape for the apostrophe as a neutral single quote is typically needed only in technical content; typing words like “can’t” and “Anne’s” in a natural way will render correctly, because in ordinary prose an apostrophe is typeset either as a closing single quotation mark or as a neutral single quote, depending on the capabilities of the output device. By contrast, special character escapes should be used for quotation marks unless portability to limited or historical troff implementations is necessary; on those systems, the input convention is to pair the grave accent with the apostrophe for single quotes, and to double both characters for double quotes. AT&T troff defined no special characters for quotation marks or the apostrophe. Repeated single quotes (‘‘thus’’) will be visually distinguishable from double quotes (“thus”) on terminal devices, and perhaps on others (depending on the font selected).
If you expect to use quotation marks frequently in your document, see if the macro package you’re using defines strings or macros to facilitate quotation.
Using Unicode basic Latin characters to compose boxes and lines is ill-advised. roff systems have special characters for drawing straight horizontal and vertical lines; see subsection “Rules and lines” below. Preprocessors like tbl(1) and pic(1) draw boxes and will produce the best possible output for the device, falling back to basic Latin glyphs only when necessary.
ISO 646 is a seven-bit code encoding 128 code points; eight-bit codes are twice the size. ISO 8859-1 and code page 1047 allocated the additional space to what Unicode calls “C1 controls” (control characters) and the “Latin-1 supplement”. The C1 controls are neither printable nor usable as groff input.
Two characters in the Latin-1 supplement are handled specially. troff never produces them as output.
|
NBSP |
encodes the no-break space. On input it is mapped to \~, the adjustable non-breaking space escape. | ||
|
SHY |
encodes the soft hyphen character. On input it is mapped to \%, the hyphenation control escape. |
The remaining characters in the Latin-1 supplement represent themselves. Although they can be specified directly with the keyboard on systems configured to use Latin-1 as the character encoding, it is more portable, both to other roff systems and to UTF-8 environments, to use their glyph names, shown below.
Glyphs that lack a character code in the basic Latin repertoire to directly represent them are entered by one of several special character escape forms. Such glyphs can be simple or composite, and accessed either by name or numerically by code point. Code points and combining properties are determined by character encoding standards, whereas glyph names originated in AT&T troff special character escapes. Glyph names are not limited to alphanumeric characters; any of the printable characters from the Unicode basic Latin repertoire may be used.
|
\(gl |
is a special character escape for the glyph with the two-character name gl. This is the syntax form supported by AT&T troff. The acute accent, \(aa, is an example. |
\[glyph-name]
is a special character escape for glyph-name, which can be of arbitrary length. The foregoing acute accent example could be expressed in groff as \[aa].
An ordinary input character “c” is not the same as \[c]; the latter is internally mapped to glyph name “\c”. In other words, “\[a]” is not “a”, but rather \a, the uninterpreted leader escape sequence. By default, groff defines a single glyph name of length one, namely the hyphen-minus, which can be accessed as either \- or \[-].
\[base-glyph composite-1 composite-2 ... composite-n]
is a composite glyph. Glyphs like a lowercase “e” with an acute accent, as in the word “café”, can be expressed as \[e aa]. See subsection “Accents” below for a table of combining glyph names.
Unicode encodes
far more characters than groff has glyph names for;
special character escape forms based on numerical code
points enable access to any of them. Frequently used glyphs
or glyph combinations can be stored in strings, and new
glyph names can be created with the .char request,
enabling the user to devise ad hoc names for them;
see groff(7).
\[unnnn[n[n]]]
is a Unicode numeric special character escape. With this form, any Unicode point can be indicated using four to six hexadecimal digits, with hexadecimal letters accepted in uppercase form only. Thus, \[u02DA] accesses the (spacing) ring accent, producing “˚”.
Unicode code
points can be composed as well; when they are, troff
requires NFD (Normalization Form D), where all Unicode
glyphs are maximally decomposed. (Exception: precomposed
characters in the Latin-1 supplement described above are
also accepted. Do not count on this exception remaining in a
future troff that accepts UTF-8 input directly.)
Thus, troff accepts “caf\['e]”,
“caf\[e aa]”, and
“caf\[u0065_0301]”, as ways to input
“café”. (Due to its ISO Latin-1 and IBM
code page 1047 compatibility, at present it also accepts
“caf\[u00E9]”).
\[ubase-glyph[_combining-component
]...] constructs a composite glyph from Unicode numeric special character escapes. The code points of the base glyph and the combining components are each expressed in hexadecimal, with an underscore (_) separating each component. Thus, \[u0065_0301] produces “é”.
\[charnnn]
expresses an eight-bit code point where nnn is the code point of the character, a decimal number between 0 and 255 without leading zeroes. This legacy numeric special character escape is used to map characters onto glyphs via the .trin request in macro files loaded by grotty(1).
In this section, groff’s glyph name repertoire is presented in tabular form. The meanings of the columns are as follows.
|
Output |
shows the glyph as it appears on the device used to render this document; although it can have a notably different shape on other devices (and is subject to user-directed translation and replacement), groff attempts reasonable equivalency on all output devices. | ||
|
Input |
shows the groff character (ordinary or special) that normally produces the glyph. Some code points have multiple glyph names. |
Unicode
is the code point notation for the glyph or combining glyph sequence as described in subsection “Special character escape forms” above. It corresponds to the standard notation for Unicode short identifiers such that groff’s unnnn is equivalent to Unicode’s U+nnnn.
|
Notes |
describes the glyph, elucidating the mnemonic value of the glyph name where possible. |
A plus sign “+” indicates that the glyph name appears in the AT&T troff user’s manual, CSTR #54 (1992 revision). When using the AT&T special character syntax \(xx, widespread portability can be expected from such names.
Entries marked with “***” denote glyphs used for mathematical purposes. On typesetter devices, such glyphs are typically drawn from a special font (see groff_font(5)). Often, such glyphs have metrics which look incongruous in normal text. A few which are not uncommon in running prose have “text variants”, which should work better in that context. Conversely, a handful of glyphs that are normally drawn from a regular font are required in mathematical text. Both sets of exceptions are noted in the tables where they appear (“Logical symbols” and “Mathematical symbols”).
Apart from basic Latin characters with special mappings, described in subsection “Fundamental character set” above, a few others in that range have special character glyph names. These were defined for ease of input on non-U.S. keyboards lacking keycaps for them, or for symmetry with other special character glyph names serving a similar purpose.
The vertical bar is overloaded; the \[ba] and \[or] escapes may render differently. See subsection “Mathematical symbols” below for special variants of the plus, minus, and equals signs normally drawn from this range.
Historically, \[ss] could be considered a ligature of “sz”. An uppercase form is available as \[u1e9e], but in the German language it is of specialized use; ß does not normally uppercase-transform to it, but rather to “SS”. “Lowercase f with hook” is also used as a function symbol; see subsection “Mathematical symbols” below.
All of these glyphs can be composed using combining glyph names as described in subsection “Special character escape forms” above; the names below can be thought of short aliases for convenience.
The .composite request is used to map the accents to code points with non-spacing semantics; the values given in parentheses are their spacing counterparts.
On typestter devices, the bracket extensions are font-invariant glyphs; that is, they are rendered the same way regardless of font. On terminals, they are not font-invariant; groff maps them rather arbitrarily to U+23AA (“curly bracket extension”). In AT&T troff, only one glyph was available to vertically extend brackets, braces, and parentheses: \(bv.
Not all devices supply bracket pieces that can be piled up with \b due to the restrictions of the escape’s piling algorithm. A general solution to build brackets out of pieces is the following macro:
.\" Make a pile centered
vertically 0.5em above the baseline.
.\" The first argument is placed at the top.
.\" The pile is returned in string 'pile'.
.eo
.de pile-make
. nr pile-wd 0
. nr pile-ht 0
. ds pile-args
.
. nr pile-# \n[.$]
. while \n[pile-#] \{\
. nr pile-wd (\n[pile-wd] >? \w'\$[\n[pile-#]]')
. nr pile-ht +(\n[rst] - \n[rsb])
. as pile-args \v'\n[rsb]u'\"
. as pile-args \Z'\$[\n[pile-#]]'\"
. as pile-args \v'-\n[rst]u'\"
. nr pile-# -1
. \}
.
. ds pile \v'(-0.5m + (\n[pile-ht]u / 2u))'\"
. as pile \*[pile-args]\"
. as pile \v'((\n[pile-ht]u / 2u) + 0.5m)'\"
. as pile \h'\n[pile-wd]u'\"
..
.ec
Another complication is the fact that some glyphs which represent bracket pieces in AT&T troff can be used for other mathematical symbols as well, for example \(lf and \(rf which provide the floor operator. Some output postprocessors, such as grodvi(1), don’t unify such glyphs. For this reason, the four glyphs \[lf], \[rf], \[lc], and \[rc], are not unified with similar-looking bracket pieces. In groff, only glyphs with long names are guaranteed to pile up correctly for all devices—provided those glyphs exist.
On typesetter devices, the font-invariant glyphs (see subsection “Brackets” above) \[br], \[ul], and \[rn] form corners when adjacent; they can be used to build boxes. On terminal devices, they are mapped as shown in the table. The Unicode-derived names of these three glyphs are approximations.
\[rn] also serves in AT&T troff as the horizontal extension of the radical (square root) sign. The baseline rule \[ru] is a font-invariant glyph, namely a rule of one-half em. In groff, use \[radicalex] (see subsection “Mathematical symbols” below) instead of \[rn], for continuation of radical signs (e.g., square roots).
The Bell Systems logo is not supported in groff.
Whether the two variants of the not sign differ in appearance or spacing will depend on the device and font selected.
\[Fn] also appears in subsection “Supplementary Latin letters” above. Observe the two varieties of the plus-minus, multiplication, and division signs; \[+-], \[mu], and \[di] are normally drawn from the special font, but have regular (“text”) font variants. Also be aware of three glyphs available in special font variants that are normally drawn from regular fonts: the plus, minus, and equals signs. Whether these variants differ in appearance or spacing will depend on the device and font selected.
These glyphs are intended for technical use, not for typesetting Greek language text; normally, the uppercase letters have upright shape, and the lowercase ones are slanted.
This document was written by James Clark, with additions by Werner Lemberg and Bernd Warken, revised to use tbl(1) by Eric S. Raymond, and largely rewritten by G. Branden Robinson.
Groff: The GNU Implementation of troff, by Trent A. Fisher and Werner Lemberg, is the primary groff manual. Section “Using Symbols” may be of particular note. You can browse it interactively with “info '(groff) Using Symbols'”.
“An
extension to the troff character set for
Europe”, E.G. Keizer, K.J. Simonsen, J. Akkerhuis;
EUUG Newsletter, Volume 9, No. 2, Summer 1989
The Unicode Standard
“7-bit
Character Sets” by Tuomas Salste documents the
inherent ambiguity and configurability (in terms of variable
code points) of the ASCII encoding standard.
groff(1), troff(1), groff(7)