     ISPELL(5)                                                         ISPELL(5)
                                        local

     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.

                                        - 1 -         Formatted:  March 28, 2007

     ISPELL(5)                                                         ISPELL(5)
                                        local

          (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).

                                        - 2 -         Formatted:  March 28, 2007

     ISPELL(5)                                                         ISPELL(5)
                                        local

          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:

                                        - 3 -         Formatted:  March 28, 2007

     ISPELL(5)                                                         ISPELL(5)
                                        local

               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

                                        - 4 -         Formatted:  March 28, 2007

     ISPELL(5)                                                         ISPELL(5)
                                        local

          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 ] 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 either tex or nroff.  The

                                        - 5 -         Formatted:  March 28, 2007

     ISPELL(5)                                                         ISPELL(5)
                                        local

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

                                        - 6 -         Formatted:  March 28, 2007

     ISPELL(5)                                                         ISPELL(5)
                                        local

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

                                        - 7 -         Formatted:  March 28, 2007

     ISPELL(5)                                                         ISPELL(5)
                                        local

          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 sequence, 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 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

                                        - 8 -         Formatted:  March 28, 2007

     ISPELL(5)                                                         ISPELL(5)
                                        local

          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:

                                        - 9 -         Formatted:  March 28, 2007

     ISPELL(5)                                                         ISPELL(5)
                                        local

               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.  (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

                                       - 10 -         Formatted:  March 28, 2007

     ISPELL(5)                                                         ISPELL(5)
                                        local

                   [^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)

                                       - 11 -         Formatted:  March 28, 2007