Provided by: ispell_3.4.05-1_amd64 
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 language, and the second is an "affix" file
that defines the meaning of special flags in the dictionary. The two files are combined
by buildhash (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 personal 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 options 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 automatically by munchlist(1), which is the normal way of building
dictionaries.
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 format, 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 ispell, 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 capitalization, 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 possible.
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 (suffix) 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 possessive) 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 combined 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 associated 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 formatter. Normally, this
statement is not necessary, but some languages may have preempted the usual defaults for
use as language-specific characters. In this case, these statements may be used to
redefine the special 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 constructs, while retaining their
functions for the tib bibliographic preprocessor. 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 language-specific. The
allaffixes statement controls the default for the -P and -m options to ispell. If
allaffixes is turned off (the default), ispell will default to the behavior of the -P
flag: root/affix suggestions will only be made if there are no "near misses". If
allaffixes is turned on, ispell will default to the behavior of the -m flag: root/affix
suggestions will always be made. The compoundwords statement controls the default for the
-B and -C options to ispell. If compoundwords is turned off (the default), ispell will
default to the behavior 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
indicated by character (which should not be otherwise used) will be allowed to participate
in compound formation. Because this option requires 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 separate 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 definition of "normal" character sets; in
addition, there may be one or more partial definitions of "alternate" sets which are used
with various text formatters.
norm-sets : [ deftype ] [ set-options ] 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 associated with these suffixes; often it is a formatter name. If the formatter 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
specify a formatter type. The deformatter parameter specifies the deformatting style to
use when processing files with the given suffixes. Currently, this must be plain, tex,
nroff, or html. 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.
set-options : options charset-options*
The options declaration activates one or more white-separated options for the given
character set (default or alternate). Currently, two options are supported: The
raw_display option indicates that string characters should be displayed as-is even if some
of their components appear to be non-printing; this option is useful for character sets
such as UTF-8 or (if the terminal is configured appropriately) ISO Latin-1. The
squeeze_string option indicates that when ispell is interacting with an external client
such as emacs (via the -a flag), string characters should be considered to be of length 1
rather than their true length in bytes. This option is needed to allow ispell to
synchronize with emacs when processing files containing UTF-8 characters; it should only
be given for UTF-8 character sets.
charset-group : { char-stmt | string-stmt | dup-stmt}*
A char-stmt describes single characters; a string-stmt describes characters that must
appear together as a string, and which usually represent a single character in the target
language. Either may also describe conversion between upper and lower case. A dup-stmt
is used to describe alternate forms of string characters, so that a single dictionary 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 statement, 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 special characters as if
they were strings. For example, the German "a-umlaut" is traditionally sorted as if it
were "ae". Ispell is not capable 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 [ set-options ] [ 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 characters.
alttype : altstringtype name suffix*
The altstringtype statement introduces each set by declaring the associated 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 represents 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 sequences 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 restrictions. (The current version of buildhash does not
enforce these restrictions, but failure to obey them may result in errors being introduced
into files that are processed with ispell.)
An important minor point is that ispell assumes that all characters declared 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 lowercase, 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 declaration; 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 a collating
sequence by their byte values, 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 that have been forced to use a strange 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 repls (replacements) which are conditionally
applied to the beginnings or endings of various words.
Flags are named by a single character char. Depending on a configuration option, this
character can be either any uppercase letter (the default 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 asterisk 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 combinations, 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 German, 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 conditions 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 beginning 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 controlled 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 conditions:
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 independent 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 rebuild a dictionary file
using an incompatible suffix file. For example, suppose you expanded the "R" flag to
generate "er" and "ers" (thus making the Z flag somewhat obsolete). To build a new
dictionary newdict that, using newaffixes, will accept exactly the same list of words as
the old list olddict did using oldaffixes, the -c switch of munchlist 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.
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)