groff: Using Symbols
5.17.4 Using Symbols
--------------------
A "glyph" is a graphical representation of a "character". While a
character is an abstract entity containing semantic information, a glyph
is something that can be actually seen on screen or paper. It is
possible that a character has multiple glyph representation forms (for
example, the character 'A' can be either written in a roman or an italic
font, yielding two different glyphs); sometimes more than one character
maps to a single glyph (this is a "ligature" - the most common is 'fi').
A "symbol" is simply a named glyph. Within 'gtroff', all glyph names
of a particular font are defined in its font file. If the user requests
a glyph not available in this font, 'gtroff' looks up an ordered list of
"special fonts". By default, the POSTSCRIPT output device supports the
two special fonts 'SS' (slanted symbols) and 'S' (symbols) (the former
is looked up before the latter). Other output devices use different
names for special fonts. Fonts mounted with the 'fonts' keyword in the
'DESC' file are globally available. To install additional special fonts
locally (i.e. for a particular font), use the 'fspecial' request.
Here the exact rules how 'gtroff' searches a given symbol:
* If the symbol has been defined with the 'char' request, use it.
This hides a symbol with the same name in the current font.
* Check the current font.
* If the symbol has been defined with the 'fchar' request, use it.
* Check whether the current font has a font-specific list of special
fonts; test all fonts in the order of appearance in the last
'fspecial' call if appropriate.
* If the symbol has been defined with the 'fschar' request for the
current font, use it.
* Check all fonts in the order of appearance in the last 'special'
call.
* If the symbol has been defined with the 'schar' request, use it.
* As a last resort, consult all fonts loaded up to now for special
fonts and check them, starting with the lowest font number. Note
that this can sometimes lead to surprising results since the
'fonts' line in the 'DESC' file often contains empty positions,
which are filled later on. For example, consider the following:
fonts 3 0 0 FOO
This mounts font 'foo' at font position 3. We assume that 'FOO' is
a special font, containing glyph 'foo', and that no font has been
loaded yet. The line
.fspecial BAR BAZ
makes font 'BAZ' special only if font 'BAR' is active. We further
assume that 'BAZ' is really a special font, i.e., the font
description file contains the 'special' keyword, and that it also
contains glyph 'foo' with a special shape fitting to font 'BAR'.
After executing 'fspecial', font 'BAR' is loaded at font
position 1, and 'BAZ' at position 2.
We now switch to a new font 'XXX', trying to access glyph 'foo'
that is assumed to be missing. There are neither font-specific
special fonts for 'XXX' nor any other fonts made special with the
'special' request, so 'gtroff' starts the search for special fonts
in the list of already mounted fonts, with increasing font
positions. Consequently, it finds 'BAZ' before 'FOO' even for
'XXX', which is not the intended behaviour.
Font Files, and Special Fonts, for more details.
The list of available symbols is device dependent; see the
'groff_char(7)' man page for a complete list of all glyphs. For
example, say
man -Tdvi groff_char > groff_char.dvi
for a list using the default DVI fonts (not all versions of the 'man'
program support the '-T' option). If you want to use an additional
macro package to change the used fonts, 'groff' must be called directly:
groff -Tdvi -mec -man groff_char.7 > groff_char.dvi
Glyph names not listed in groff_char(7) are derived algorithmically,
using a simplified version of the Adobe Glyph List (AGL) algorithm,
which is described in
<http://partners.adobe.com/public/developer/opentype/index_glyph.html>.
The (frozen) set of glyph names that can't be derived algorithmically is
called "groff glyph list (GGL)".
* A glyph for Unicode character U+XXXX[X[X]], which is not a
composite character is named 'uXXXX[X[X]]'. X must be an uppercase
hexadecimal digit. Examples: 'u1234', 'u008E', 'u12DB8'. The
largest Unicode value is 0x10FFFF. There must be at least four 'X'
digits; if necessary, add leading zeroes (after the 'u'). No zero
padding is allowed for character codes greater than 0xFFFF.
Surrogates (i.e., Unicode values greater than 0xFFFF represented
with character codes from the surrogate area U+D800-U+DFFF) are not
allowed too.
* A glyph representing more than a single input character is named
'u' COMPONENT1 '_' COMPONENT2 '_' COMPONENT3 ...
Example: 'u0045_0302_0301'.
For simplicity, all Unicode characters that are composites must be
decomposed maximally (this is normalization form D in the Unicode
standard); for example, 'u00CA_0301' is not a valid glyph name
since U+00CA (LATIN CAPITAL LETTER E WITH CIRCUMFLEX) can be
further decomposed into U+0045 (LATIN CAPITAL LETTER E) and U+0302
(COMBINING CIRCUMFLEX ACCENT). 'u0045_0302_0301' is thus the glyph
name for U+1EBE, LATIN CAPITAL LETTER E WITH CIRCUMFLEX AND ACUTE.
* groff maintains a table to decompose all algorithmically derived
glyph names that are composites itself. For example, 'u0100'
(LATIN LETTER A WITH MACRON) is automatically decomposed into
'u0041_0304'. Additionally, a glyph name of the GGL is preferred
to an algorithmically derived glyph name; groff also automatically
does the mapping. Example: The glyph 'u0045_0302' is mapped to
'^E'.
* glyph names of the GGL can't be used in composite glyph names; for
example, '^E_u0301' is invalid.
-- Escape: \(nm
-- Escape: \[name]
-- Escape: \[component1 component2 ...]
Insert a symbol NAME (two-character name NM) or a composite glyph
with component glyphs COMPONENT1, COMPONENT2, ... There is no
special syntax for one-character names - the natural form '\N'
would collide with escapes.(1) (Using Symbols-Footnote-1)
If NAME is undefined, a warning of type 'char' is generated, and
the escape is ignored. Debugging, for information about
warnings.
groff resolves '\[...]' with more than a single component as
follows:
* Any component that is found in the GGL is converted to the
'uXXXX' form.
* Any component 'uXXXX' that is found in the list of
decomposable glyphs is decomposed.
* The resulting elements are then concatenated with '_' in
between, dropping the leading 'u' in all elements but the
first.
No check for the existence of any component (similar to 'tr'
request) is done.
Examples:
'\[A ho]'
'A' maps to 'u0041', 'ho' maps to 'u02DB', thus the final
glyph name would be 'u0041_02DB'. Note this is not the
expected result: The ogonek glyph 'ho' is a spacing ogonek,
but for a proper composite a non-spacing ogonek (U+0328) is
necessary. Looking into the file 'composite.tmac' one can
find '.composite ho u0328', which changes the mapping of 'ho'
while a composite glyph name is constructed, causing the final
glyph name to be 'u0041_0328'.
'\[^E u0301]'
'\[^E aa]'
'\[E a^ aa]'
'\[E ^ ']'
'^E' maps to 'u0045_0302', thus the final glyph name is
'u0045_0302_0301' in all forms (assuming proper calls of the
'composite' request).
It is not possible to define glyphs with names like 'A ho' within a
groff font file. This is not really a limitation; instead, you
have to define 'u0041_0328'.
-- Escape: \C'xxx'
Typeset the glyph named XXX.(2) (Using Symbols-Footnote-2)
Normally it is more convenient to use '\[XXX]', but '\C' has the
advantage that it is compatible with newer versions of AT&T 'troff'
and is available in compatibility mode.
-- Request: .composite from to
Map glyph name FROM to glyph name TO if it is used in '\[...]' with
more than one component. See above for examples.
This mapping is based on glyph names only; no check for the
existence of either glyph is done.
A set of default mappings for many accents can be found in the file
'composite.tmac', which is loaded at start-up.
-- Escape: \N'n'
Typeset the glyph with code N in the current font ('n' is *not* the
input character code). The number N can be any non-negative
decimal integer. Most devices only have glyphs with codes between
0 and 255; the Unicode output device uses codes in the range
0-65535. If the current font does not contain a glyph with that
code, special fonts are _not_ searched. The '\N' escape sequence
can be conveniently used in conjunction with the 'char' request:
.char \[phone] \f[ZD]\N'37'
The code of each glyph is given in the fourth column in the font
description file after the 'charset' command. It is possible to
include unnamed glyphs in the font description file by using a name
of '---'; the '\N' escape sequence is the only way to use these.
No kerning is applied to glyphs accessed with '\N'.
Some escape sequences directly map onto special glyphs.
-- Escape: \'
This is a backslash followed by the apostrophe character, ASCII
character '0x27' (EBCDIC character '0x7D'). The same as '\[aa]',
the acute accent.
-- Escape: \`
This is a backslash followed by ASCII character '0x60' (EBCDIC
character '0x79' usually). The same as '\[ga]', the grave accent.
-- Escape: \-
This is the same as '\[-]', the minus sign in the current font.
-- Escape: \_
This is the same as '\[ul]', the underline character.
-- Request: .cflags n c1 c2 ...
Input characters and symbols have certain properties associated
with it.(3) (Using Symbols-Footnote-3) These properties
can be modified with the 'cflags' request. The first argument is
the sum of the desired flags and the remaining arguments are the
characters or symbols to have those properties. It is possible to
omit the spaces between the characters or symbols. Instead of
single characters or symbols you can also use character classes
(see Character Classes for more details).
'1'
The character ends sentences (initially characters '.?!' have
this property).
'2'
Lines can be broken before the character (initially no
characters have this property). This only works if both the
characters before and after have non-zero hyphenation codes
(as set with the 'hcode' request). Use value 64 to override
this behaviour.
'4'
Lines can be broken after the character (initially the
character '-' and the symbols '\[hy]' and '\[em]' have this
property). This only works if both the characters before and
after have non-zero hyphenation codes (as set with the 'hcode'
request). Use value 64 to override this behaviour.
'8'
The character overlaps horizontally if used as a horizontal
line building element. Initially the symbols '\[ul]',
'\[rn]', '\[ru]', '\[radicalex]', and '\[sqrtex]' have this
property.
'16'
The character overlaps vertically if used as vertical line
building element. Initially symbol '\[br]' has this property.
'32'
An end-of-sentence character followed by any number of
characters with this property is treated as the end of a
sentence if followed by a newline or two spaces; in other
words the character is "transparent" for the purposes of
end-of-sentence recognition - this is the same as having a
zero space factor in TeX (initially characters '"')]*' and the
symbols '\[dg]', '\[rq]', and '\[cq]' have this property).
'64'
Ignore hyphenation code values of the surrounding characters.
Use this in combination with values 2 and 4 (initially no
characters have this property). For example, if you need an
automatic break point after the hyphen in number ranges like
'3000-5000', insert
.cflags 68 -
into your document. Note, however, that this can lead to bad
layout if done without thinking; in most situations, a better
solution instead of changing the 'cflags' value is to insert
'\:' right after the hyphen at the places that really need a
break point.
'128'
Prohibit a line break before the character, but allow a line
break after the character. This works only in combination
with flags 256 and 512 (see below) and has no effect
otherwise.
'256'
Prohibit a line break after the character, but allow a line
break before the character. This works only in combination
with flags 128 and 512 (see below) and has no effect
otherwise.
'512'
Allow line break before or after the character. This works
only in combination with flags 128 and 256 and has no effect
otherwise.
Contrary to flag values 2 and 4, the flags 128, 256, and 512
work pairwise. If, for example, the left character has value
512, and the right character 128, no line break gets inserted.
If we use value 6 instead for the left character, a line break
after the character can't be suppressed since the right
neighbour character doesn't get examined.
-- Request: .char g [string]
-- Request: .fchar g [string]
-- Request: .fschar f g [string]
-- Request: .schar g [string]
Define a new glyph G to be STRING (which can be empty).(4) (
Using Symbols-Footnote-4) Every time glyph G needs to be printed,
STRING is processed in a temporary environment and the result is
wrapped up into a single object. Compatibility mode is turned off
and the escape character is set to '\' while STRING is being
processed. Any emboldening, constant spacing or track kerning is
applied to this object rather than to individual characters in
STRING.
A glyph defined by these requests can be used just like a normal
glyph provided by the output device. In particular, other
characters can be translated to it with the 'tr' or 'trin'
requests; it can be made the leader character by the 'lc' request;
repeated patterns can be drawn with the glyph using the '\l' and
'\L' escape sequences; words containing the glyph can be hyphenated
correctly if the 'hcode' request is used to give the glyph's symbol
a hyphenation code.
There is a special anti-recursion feature: Use of 'g' within the
glyph's definition is handled like normal characters and symbols
not defined with 'char'.
Note that the 'tr' and 'trin' requests take precedence if 'char'
accesses the same symbol.
.tr XY
X
=> Y
.char X Z
X
=> Y
.tr XX
X
=> Z
The 'fchar' request defines a fallback glyph: 'gtroff' only checks
for glyphs defined with 'fchar' if it cannot find the glyph in the
current font. 'gtroff' carries out this test before checking
special fonts.
'fschar' defines a fallback glyph for font F: 'gtroff' checks for
glyphs defined with 'fschar' after the list of fonts declared as
font-specific special fonts with the 'fspecial' request, but before
the list of fonts declared as global special fonts with the
'special' request.
Finally, the 'schar' request defines a global fallback glyph:
'gtroff' checks for glyphs defined with 'schar' after the list of
fonts declared as global special fonts with the 'special' request,
but before the already mounted special fonts.
Using Symbols, for a detailed description of the glyph
searching mechanism in 'gtroff'.
-- Request: .rchar c1 c2 ...
-- Request: .rfschar f c1 c2 ...
Remove the definitions of glyphs C1, C2, ... This undoes the
effect of a 'char', 'fchar', or 'schar' request.
It is possible to omit the whitespace between arguments.
The request 'rfschar' removes glyph definitions defined with
'fschar' for glyph f.
Special Characters.
Info Catalog
groff: Font Positions
groff: Fonts and Symbols
groff: Character Classes