groff_char - Man Page

The ordinary characters catalogued above, plus the space, tab, newline, and leader (Control+A), 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 ordinary characters 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: Bell Labs used the system for preparation of AT&T's patent filings with the U.S. government. Further, 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 escape sequences 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 the roff language also uses it to quote macro arguments, groff supports a special character escape sequence 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. (Some requests, like ds, also treat " non-literally.) Furthermore, not all of the special character escape sequences are portable to AT&T troff and all of its descendants; these groff extensions are presented using its special character form \[], whereas portable special character escape sequences 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 request is used. On devices with a limited glyph repertoire, glyphs in the “keycap” and “appearance” columns on the same row of the table may look identical; except for the neutral double quote, this will not be the case on more-capable devices. Review your document using as many different output devices as possible.

The hyphen-minus is a particularly unfortunate case of overloading. Its awkward name in ISO 8859 and later standards reflects the many distinguishable purposes to which it had already been put by the 1980s, including a hyphen, a minus sign, and (alone or in repetition) dashes of varying widths. For best results in roff systems, use the “-” character in input outside an escape sequence only to mean a hyphen, as in the phrase “long-term”. For a minus sign in running text or a Unix command-line option dash, use \- (or \[-] in groff if you find it helps the clarity of the source document). (Another minus sign, for use in mathematical equations, is available as \[mi]). AT&T troff supported em-dashes as \(em, as does groff.

The special character escape sequence 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 escape sequences 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 frequently require quotation marks in your document, see if the macro package you're using supplies strings or macros to facilitate quotation, or define them yourself (except in man pages).

Using Unicode basic Latin characters to compose boxes and lines is ill-advised. roff systems have special characters for drawing 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 Latin-1 supplement characters are handled specially on input. troff never produces them as output.

NBSP

encodes a no-break space; it is mapped to \~, the adjustable non-breaking space escape sequence.

SHY

encodes a soft hyphen; it is mapped to \%, the hyphenation control escape sequence.

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 special character escape sequences, shown below. The glyph descriptions we use are non-standard in some cases, for brevity.

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 as used here originated in AT&T troff special character escape sequences. Predefined glyph names use only characters in the basic Latin repertoire.

\(gl

is a special character escape sequence for the glyph with the two-character name gl. This is the original syntax form supported by AT&T troff. The acute accent, \(aa, is an example.

\C'glyph-name'

is a special character escape sequence for glyph-name, which can be of arbitrary length. The delimiter, shown here as a neutral apostrophe, can be any character not occurring in glyph-name. This syntax form was introduced in later versions of AT&T device-independent troff. The foregoing acute accent example can be expressed as \C'aa'.

\[glyph-name]

is a special character escape sequence for glyph-name, which can be of arbitrary length but must not contain a closing square bracket “]”. (No glyph names predefined by groff employ “]”.) The foregoing acute accent example can be expressed in groff as \[aa].

\C'c' and \[c] are not synonyms for the ordinary character “c”, but request the special character named “\c”. For example, “\[a]” is not “a”, but rather a special character with the internal glyph name (used in font description files and diagnostic messages) \a, which is typically undefined. The only such glyph name groff predefines is the minus sign, which can therefore be accessed as \C'-' or \[-].

\[base-char composite-1 composite-2 ... composite-n]

is a composite glyph. Glyphs like a lowercase “e” with an acute accent, as in the word “caf[e aa]”, 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 ad hoc with the char request; see groff(7).

\[unnnn[n[n]]]

is a Unicode numeric special character escape sequence. Any Unicode code point can be accessed with 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, GNU 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 GNU troff that accepts UTF-8 input directly.) Thus, GNU troff accepts “caf\['e]”, “caf\[e aa]”, and “caf\[u0065_0301]”, as ways to input “café”. (Due to its legacy 8-bit encoding compatibility, at present it also accepts “caf\[u00E9]” on ISO Latin-1 systems.)

\[ubase-char[_combining-component]...]

constructs a composite glyph from Unicode numeric special character escape sequences. The code points of the base glyph and the combining components are each expressed in hexadecimal, with an underscore (_) separating each component. Thus, \[u006E_0303] 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 sequence is used to map characters onto glyphs via the trin request in macro files loaded by grotty(1).

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] escape sequences 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.

Normally, the formatting of a special character advances the drawing position as an ordinary character does. groff's composite request designates a special character as combining. The composite.tmac macro file, loaded automatically by the default troffrc, maps the following special characters to the combining characters shown below. The non-combining code point in parentheses is used when the special character occurs in isolation (compare “caf\[e aa]” and “caf\[aa]e”).

All of these glyphs can be composed using combining glyph names as described in subsection “Special character escape forms” above; the names below are short aliases for convenience.

The neutral double quote, often useful when documenting programming languages, is also available as a special character for convenient embedding in macro arguments; see subsection “Fundamental character set” above.

The Unicode name for U+00B7 is “middle dot”, which is unfortunately confusable with the groff mnemonic for the visually similar but semantically distinct multiplication dot; see subsection “Mathematical symbols” below.

On typesetting devices, the bracket extensions are font-invariant glyphs; that is, they are rendered the same way regardless of font (with a drawing escape sequence). 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 devices, such as dvi, don't unify such glyphs. For this reason, the 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 are available.

On typesetting 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.

The input character _ always accesses the underscore glyph in a font; \[ul], by contrast, may be font-invariant on typesetting devices.

The baseline rule \[ru] is a font-invariant glyph, namely a rule of one-half em.

In AT&T troff, \[rn] also served as a one en extension of the square root symbol. groff favors \[radicalex] for this purpose; see subsection “Mathematical symbols” below.

The Bell System logo is not supported in groff.

The variants of the not sign may differ in appearance or spacing depending on the device and font selected. Unicode does not encode a discrete “bitwise or” sign: on typesetting devices, it is drawn shorter than the bar, about the same height as a capital letter. Terminal devices unify \[ba] and \[or].

\[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 text font variants. Also be aware of three glyphs available in special font variants that are normally drawn from text fonts: the plus, minus, and equals signs. These variants may differ in appearance or spacing depending on the device and font selected.

In AT&T troff, \(rn (“root en extender”) served as the horizontal extension of the radical (square root) sign, \(sr, and was drawn at the maximum height of the typeface's bounding box; this enabled the special character to double as an overline (see subsection “Rules and lines” above). A contemporary font's radical sign might not ascend to such an extreme. In groff, you can instead use \[radicalex] to continue the radical sign \[sr]; these special characters are intended for use with text fonts. \[sqrt] and \[sqrtex] are their counterparts with mathematical spacing.

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.