ISPELL(5) File Formats Manual ISPELL(5)
NAME
ispell - format of ispell dictionaries and affix files
DESCRIPTION
Ispell(1) requires two files to define the language that it is spell-
checking. The first file is a dictionary containing words for the lan-
guage, and the second is an "affix" file that defines the meaning of
special flags in the dictionary. The two files are combined by build-
hash (see ispell(1)) and written to a hash file which is not described
here.
A raw ispell dictionary (either the main dictionary or your own per-
sonal dictionary) contains a list of words, one per line. Each word
may optionally be followed by a slash ("/") and one or more flags,
which modify the root word as explained below. Depending on the op-
tions with which ispell was built, case may or may not be significant
in either the root word or the flags, independently. Specifically, if
the compile-time option CAPITALIZATION is defined, case is significant
in the root word; if not, case is ignored in the root word. If the
compile-time option MASKBITS is set to a value of 32, case is ignored
in the flags; otherwise case is significant in the flags. Contact your
system administrator or ispell maintainer for more information (or use
the -vv flag to find out). The dictionary should be sorted with the -f
flag of sort(1) before the hash file is built; this is done automati-
cally by munchlist(1), which is the normal way of building dictionar-
ies.
If the dictionary contains words that have string characters (see the
affix-file documentation below), they must be written in the format
given by the defstringtype statement in the affix file. This will be
the case for most non-English languages. Be careful to use this for-
mat, rather than that of your favorite formatter, when adding words to
a dictionary. (If you add words to your personal dictionary during an
ispell session, they will automatically be converted to the correct
format. This feature can be used to convert an entire dictionary if
necessary:)
echo qqqqq > dummy.dict
buildhash dummy.dict affix-file dummy.hash
awk '{print "*"}END{print "#"}' old-dict-file \
| ispell -a -T old-dict-string-type \
-d ./dummy.hash -p ./new-dict-file \
> /dev/null
rm dummy.*
The case of the root word controls the case of words accepted by is-
pell, as follows:
(1) If the root word appears only in lower case (e.g., bob), it will
be accepted in lower case, capitalized, or all capitals.
(2) If the root word appears capitalized (e.g., Robert), it will not
be accepted in all-lower case, but will be accepted capitalized
or all in capitals.
(3) If the root word appears all in capitals (e.g., UNIX), it will
only be accepted all in capitals.
(4) If the root word appears with a "funny" capitalization (e.g.,
ITCorp), a word will be accepted only if it follows that capi-
talization, or if it appears all in capitals.
(5) More than one capitalization of a root word may appear in the
dictionary. Flags from different capitalizations are combined
by OR-ing them together.
Redundant capitalizations (e.g., bob and Bob) will be combined by
buildhash and by ispell (for personal dictionaries), and can be removed
from a raw dictionary by munchlist.
For example, the dictionary:
bob
Robert
UNIX
ITcorp
ITCorp
will accept bob, Bob, BOB, Robert, ROBERT, UNIX, ITcorp, ITCorp, and
ITCORP, and will reject all others. Some of the unacceptable forms are
bOb, robert, Unix, and ItCorp.
As mentioned above, root words in any dictionary may be extended by
flags. Each flag is a single alphabetic character, which represents a
prefix or suffix that may be added to the root to form a new word. For
example, in an English dictionary the D flag can be added to bathe to
make bathed. Since flags are represented as a single bit in the hashed
dictionary, this results in significant space savings. The munchlist
script will reduce an existing raw dictionary by adding flags when pos-
sible.
When a word is extended with an affix, the affix will be accepted only
if it appears in the same case as the initial (prefix) or final (suf-
fix) letter of the word. Thus, for example, the entry UNIX/M in the
main dictionary (M means add an apostrophe and an "s" to make a posses-
sive) would accept UNIX'S but would reject UNIX's. If UNIX's is legal,
it must appear as a separate dictionary entry, and it will not be com-
bined by munchlist. (In general, you don't need to worry about these
things; munchlist guarantees that its output dictionary will accept the
same set of words as its input, so all you have to do is add words to
the dictionary and occasionally run munchlist to reduce its size).
As mentioned, the affix definition file describes the affixes associ-
ated with particular flags. It also describes the character set used
by the language.
Although the affix-definition grammar is designed for a line-oriented
layout, it is actually a free-format yacc grammar and can be laid out
weirdly if you want. Comments are started by a pound (sharp) sign (#),
and continue to the end of the line. Backslashes are supported in the
usual fashion (\nnn, plus specials \n, \r, \t, \v, \f, \b, and the new
hex format \xnn). Any character with special meaning to the parser can
be changed to an uninterpreted token by backslashing it; for example,
you can declare a flag named 'asterisk' or 'colon' with flag \*: or
flag \::.
The grammar will be presented in a top-down fashion, with discussion of
each element. An affix-definition file must contain exactly one table:
table : [headers] [prefixes] [suffixes]
At least one of prefixes and suffixes is required. They can appear in
either order.
headers : [ options ] char-sets
The headers describe options global to this dictionary and language.
These include the character sets to be used and the formatter, and the
defaults for certain ispell flags.
options : { fmtr-stmt | opt-stmt | flag-stmt | num-stmt }
The options statements define the defaults for certain ispell flags and
for the character sets used by the formatters.
fmtr-stmt : { nroff-stmt | tex-stmt }
A fmtr-stmt describes characters that have special meaning to a format-
ter. Normally, this statement is not necessary, but some languages may
have preempted the usual defaults for use as language-specific charac-
ters. In this case, these statements may be used to redefine the spe-
cial characters expected by the formatter.
nroff-stmt : { nroffchars | troffchars } string
The nroffchars statement allows redefinition of certain nroff control
characters. The string given must be exactly five characters long, and
must list substitutions for the left and right parentheses ("()") , the
period ("."), the backslash ("\"), and the asterisk ("*"). (The right
parenthesis is not currently used, but is included for completeness.)
For example, the statement:
nroffchars {}.\\*
would replace the left and right parentheses with left and right curly
braces for purposes of parsing nroff/troff strings, with no effect on
the others (admittedly a contrived example). Note that the backslash
is escaped with a backslash.
tex-stmt : { TeXchars | texchars } string
The TeXchars statement allows redefinition of certain TeX/LaTeX control
characters. The string given must be exactly thirteen characters long,
and must list substitutions for the left and right parentheses ("()") ,
the left and right square brackets ("[]"), the left and right curly
braces ("{}"), the left and right angle brackets ("<>"), the backslash
("\"), the dollar sign ("$"), the asterisk ("*"), the period or dot
("."), and the percent sign ("%"). For example, the statement:
texchars ()\[]<\><\>\\$*.%
would replace the functions of the left and right curly braces with the
left and right angle brackets for purposes of parsing TeX/LaTeX con-
structs, while retaining their functions for the tib bibliographic pre-
processor. Note that the backslash, the left square bracket, and the
right angle bracket must be escaped with a backslash.
opt-stmt : { cmpnd-stmt | aff-stmt }
cmpnd-stmt : compoundwords compound-opt
aff-stmt : allaffixes on-or-off
on-or-off : { on | off }
compound-opt : { on-or-off | controlled character }
An opt-stmt controls certain ispell defaults that are best made lan-
guage-specific. The allaffixes statement controls the default for the
-P and -m options to ispell. If allaffixes is turned off (the de-
fault), ispell will default to the behavior of the -P flag: root/affix
suggestions will only be made if there are no "near misses". If allaf-
fixes is turned on, ispell will default to the behavior of the -m flag:
root/affix suggestions will always be made. The compoundwords state-
ment controls the default for the -B and -C options to ispell. If com-
poundwords is turned off (the default), ispell will default to the be-
havior of the -B flag: run-together words will be reported as errors.
If compoundwords is turned on, ispell will default to the behavior of
the -C flag: run-together words will be considered as compounds if both
are in the dictionary. This is useful for languages such as German and
Norwegian, which form large numbers of compound words. Finally, if
compoundwords is set to controlled, only words marked with the flag in-
dicated by character (which should not be otherwise used) will be al-
lowed to participate in compound formation. Because this option re-
quires the flags to be specified in the dictionary, it is not available
from the command line.
flag-stmt : flagmarker character
The flagmarker statement describes the character which is used to sepa-
rate affix flags from the root word in a raw dictionary file. This
must be a character which is not found in any word (including in string
characters; see below). The default is "/" because this character is
not normally used to represent special characters in any language.
num-stmt : compoundmin digit
The compoundmin statement controls the length of the two components of
a compound word. This only has an effect if compoundwords is turned on
or if the -C flag is given to ispell. In that case, only words at
least as long as the given minimum will be accepted as components of a
compound. The default is 3 characters.
char-sets : norm-sets [ alt-sets ]
The character-set section describes the characters that can be part of
a word, and defines their collating order. There must always be a def-
inition of "normal" character sets; in addition, there may be one or
more partial definitions of "alternate" sets which are used with vari-
ous text formatters.
norm-sets : [ deftype ] charset-group
A "normal" character set may optionally begin with a definition of the
file suffixes that make use of this set. Following this are one or
more character-set declarations.
deftype : defstringtype name deformatter suffix*
The defstringtype declaration gives a list of file suffixes which
should make use of the default string characters defined as part of the
base character set; it is only necessary if string characters are being
defined. The name parameter is a string giving the unique name associ-
ated with these suffixes; often it is a formatter name. If the format-
ter is a member of the troff family, "nroff" should be used for the
name associated with the most popular macro package; members of the TeX
family should use "tex". Other names may be chosen freely, but they
should be kept simple, as they are used in ispell 's -T switch to spec-
ify a formatter type. The deformatter parameter specifies the defor-
matting style to use when processing files with the given suffixes.
Currently, this must be either tex or nroff. The suffix parameters are
a whitespace-separated list of strings which, if present at the end of
a filename, indicate that the associated set of string characters
should be used by default for this file. For example, the suffix list
for the troff family typically includes suffixes such as ".ms", ".me",
".mm", etc.
charset-group : { char-stmt | string-stmt | dup-stmt}*
A char-stmt describes single characters; a string-stmt describes char-
acters that must appear together as a string, and which usually repre-
sent a single character in the target language. Either may also de-
scribe conversion between upper and lower case. A dup-stmt is used to
describe alternate forms of string characters, so that a single dictio-
nary may be used with several formatting programs that use different
conventions for representing non-ASCII characters.
char-stmt : wordchars character-range
| wordchars lowercase-range uppercase-range
| boundarychars character-range
| boundarychars lowercase-range uppercase-range
string-stmt : stringchar string
| stringchar lowercase-string uppercase-string
Characters described with the boundarychars statement are considered
part of a word only if they appear singly, embedded between characters
declared with the wordchars or stringchar statements. For example, if
the hyphen is a boundary character (useful in French), the string "foo-
bar" would be a single word, but "-foo" would be the same as "foo", and
"foo--bar" would be two words separated by non-word characters.
If two ranges or strings are given in a char-stmt or string-stmt, the
first describes characters that are interpreted as lowercase and the
second describes uppercase. In the case of a stringchar statement, the
two strings must be of the same length. Also, in a stringchar state-
ment, the actual strings may contain both uppercase and characters
themselves without difficulty; for instance, the statement
stringchar "\\*(sS" "\\*(Ss"
is legal and will not interfere with (or be interfered with by) other
declarations of of "s" and "S" as lower and upper case, respectively.
A final note on string characters: some languages collate certain spe-
cial characters as if they were strings. For example, the German "a-
umlaut" is traditionally sorted as if it were "ae". Ispell is not ca-
pable of this; each character must be treated as an individual entity.
So in certain cases, ispell will sort a list of words into a different
order than the standard "dictionary" order for the target language.
alt-sets : alttype [ alt-stmt* ]
Because different formatters use different notations to represent non-
ASCII characters, ispell must be aware of the representations used by
these formatters. These are declared as alternate sets of string char-
acters.
alttype : altstringtype name suffix*
The altstringtype statement introduces each set by declaring the asso-
ciated formatter name and filename suffix list. This name and list are
interpreted exactly as in the defstringtype statement above. Following
this header are one or more alt-stmts which declare the alternate
string characters used by this formatter.
alt-stmt : altstringchar alt-string std-string
The altstringchar statement describes alternate representations for
string characters. For example, the -mm macro package of troff repre-
sents the German "a-umlaut" as a\*:, while TeX uses the sequence \"a.
If the troff versions are declared as the standard versions using
stringchar, the TeX versions may be declared as alternates by using the
statement
altstringchar \\\"a a\\*
When the altstringchar statement is used to specify alternate forms,
all forms for a particular formatter must be declared together as a
group. Also, each formatter or macro package must provide a complete
set of characters, both upper- and lower-case, and the character se-
quences used for each formatter must be completely distinct. Character
sequences which describe upper- and lower-case versions of the same
printable character must also be the same length. It may be necessary
to define some new macros for a given formatter to satisfy these re-
strictions. (The current version of buildhash does not enforce these
restrictions, but failure to obey them may result in errors being in-
troduced into files that are processed with ispell.)
An important minor point is that ispell assumes that all characters de-
clared as wordchars or boundarychars will occupy exactly one position
on the terminal screen.
A single character-set statement can declare either a single character
or a contiguous range of characters. A range is given as in egrep and
the shell: [a-z] means lowercase alphabetics; [^a-z] means all but low-
ercase, etc. All character-set statements are combined (unioned) to
produce the final list of characters that may be part of a word. The
collating order of the characters is defined by the order of their dec-
laration; if a range is used, the characters are considered to have
been declared in ASCII order. Characters that have case are collated
next to each other, with the uppercase character first.
The character-declaration statements have a rather strange behavior
caused by its need to match each lowercase character with its uppercase
equivalent. In any given wordchars or boundarychars statement, the
characters in each range are first sorted into ASCII collating se-
quence, then matched one-for-one with the other range. (The two ranges
must have the same number of characters). Thus, for example, the two
statements:
wordchars [aeiou] [AEIOU]
wordchars [aeiou] [UOIEA]
would produce exactly the same effect. To get the vowels to match up
"wrong", you would have to use separate statements:
wordchars a U
wordchars e O
wordchars i I
wordchars o E
wordchars u A
which would cause uppercase 'e' to be 'O', and lowercase 'O' to be 'e'.
This should normally be a problem only with languages which have been
forced to use a strange ASCII collating sequence. If your uppercase
and lowercase letters both collate in the same order, you shouldn't
have to worry about this "feature".
The prefixes and suffixes sections have exactly the same syntax, except
for the introductory keyword.
prefixes : prefixes flagdef*
suffixes : suffixes flagdef*
flagdef : flag [*|~] char : repl*
A prefix or suffix table consists of an introductory keyword and a list
of flag definitions. Flags can be defined more than once, in which
case the definitions are combined. Each flag controls one or more re-
pls (replacements) which are conditionally applied to the beginnings or
endings of various words.
Flags are named by a single character char. Depending on a configura-
tion option, this character can be either any uppercase letter (the de-
fault configuration) or any 7-bit ASCII character. Most languages
should be able to get along with just 26 flags.
A flag character may be prefixed with one or more option characters.
(If you wish to use one of the option characters as a flag character,
simply enclose it in double quotes.)
The asterisk (*) option means that this flag participates in cross-
product formation. This only matters if the file contains both prefix
and suffix tables. If so, all prefixes and suffixes marked with an as-
terisk will be applied in all cross-combinations to the root word. For
example, consider the root fix with prefixes pre and in, and suffixes
es and ed. If all flags controlling these prefixes and suffixes are
marked with an asterisk, then the single root fix would also generate
prefix, prefixes, prefixed, infix, infixes, infixed, fix, fixes, and
fixed. Cross-product formation can produce a large number of words
quickly, some of which may be illegal, so watch out. If cross-products
produce illegal words, munchlist will not produce those flag combina-
tions, and the flag will not be useful.
repl : condition* > [ - strip-string , ] append-string
The ~ option specifies that the associated flag is only active when a
compound word is being formed. This is useful in a language like Ger-
man, where the form of a word sometimes changes inside a compound.
A repl is a conditional rule for modifying a root word. Up to 8 condi-
tions may be specified. If the conditions are satisfied, the rules on
the right-hand side of the repl are applied, as follows:
(1) If a strip-string is given, it is first stripped from the begin-
ning or ending (as appropriate) of the root word.
(2) Then the append-string is added at that point.
For example, the condition . means "any word", and the condition Y
means "any word ending in Y". The following (suffix) replacements:
. > MENT
Y > -Y,IES
would change induce to inducement and fly to flies. (If they were con-
trolled by the same flag, they would also change fly to flyment, which
might not be what was wanted. Munchlist can be used to protect against
this sort of problem; see the command sequence given below.)
No matter how much you might wish it, the strings on the right must be
strings of specific characters, not ranges. The reasons are rooted
deeply in the way ispell works, and it would be difficult or impossible
to provide for more flexibility. For example, you might wish to write:
[EY] > -[EY],IES
This will not work. Instead, you must use two separate rules:
E > -E,IES
Y > -Y,IES
The application of repls can be restricted to certain words with condi-
tions:
condition : { . | character | range }
A condition is a restriction on the characters that adjoin, and/or are
replaced by, the right-hand side of the repl. Up to 8 conditions may
be given, which should be enough context for anyone. The right-hand
side will be applied only if the conditions in the repl are satisfied.
The conditions also implicitly define a length; roots shorter than the
number of conditions will not pass the test. (As a special case, a
condition of a single dot "." defines a length of zero, so that the
rule applies to all words indiscriminately). This length is indepen-
dent of the separate test that insists that all flags produce an output
word length of at least four.
Conditions that are single characters should be separated by white
space. For example, to specify words ending in "ED", write:
E D > -ED,ING # As in covered > covering
If you write:
ED > -ED,ING
the effect will be the same as:
[ED] > -ED,ING
As a final minor, but important point, it is sometimes useful to re-
build a dictionary file using an incompatible suffix file. For exam-
ple, suppose you expanded the "R" flag to generate "er" and "ers" (thus
making the Z flag somewhat obsolete). To build a new dictionary new-
dict that, using newaffixes, will accept exactly the same list of words
as the old list olddict did using oldaffixes, the -c switch of munch-
list is useful, as in the following example:
$ munchlist -c oldaffixes -l newaffixes olddict > newdict
If you use this procedure, your new dictionary will always accept the
same list the original did, even if you badly screwed up the affix
file. This is because munchlist compares the words generated by a flag
with the original word list, and refuses to use any flags that generate
illegal words. (But don't forget that the munchlist step takes a long
time and eats up temporary file space).
EXAMPLES
As an example of conditional suffixes, here is the specification of the
S flag from the English affix file:
flag *S:
[^AEIOU]Y > -Y,IES # As in imply > implies
[AEIOU]Y > S # As in convey > conveys
[SXZH] > ES # As in fix > fixes
[^SXZHY] > S # As in bat > bats
The first line applies to words ending in Y, but not in vowel-Y. The
second takes care of the vowel-Y words. The third then handles those
words that end in a sibilant or near-sibilant, and the last picks up
everything else.
Note that the conditions are written very carefully so that they apply
to disjoint sets of words. In particular, note that the fourth line
excludes words ending in Y as well as the obvious SXZH. Otherwise, it
would convert "imply" into "implys".
Although the English affix file does not do so, you can also have a
flag generate more than one variation on a root word. For example, we
could extend the English "R" flag as follows:
flag *R:
E > R # As in skate > skater
E > RS # As in skate > skaters
[^AEIOU]Y > -Y,IER # As in multiply > multiplier
[^AEIOU]Y > -Y,IERS # As in multiply > multipliers
[AEIOU]Y > ER # As in convey > conveyer
[AEIOU]Y > ERS # As in convey > conveyers
[^EY] > ER # As in build > builder
[^EY] > ERS # As in build > builders
This flag would generate both "skater" and "skaters" from "skate".
This capability can be very useful in languages that make use of noun,
verb, and adjective endings. For instance, one could define a single
flag that generated all of the German "weak" verb endings.
SEE ALSO
ispell(1)
local ISPELL(5)