#86 "Hunspell features" documentation unclear
In general, hunspell(4) is pretty heavy going. Some things that might help:
* Under "Description" Introduce .dic, then .aff, and THEN bring up Personal dictionary
* More subsections. Under "Description", have subsections for each file. Have a subsection for each worked example.
* Either separate sections for those that go in .dic and those in .aff, or make it very clear which goes where. E.g. "General Options" belong in the .aff file.
Some specific sections I had trouble understanding:
"and the second is an "affix" file that defines the meaning of special flags in the dictionary."
But the .aff file does way more than that, this should say something like:
"an "affix" file that defines the meaning of special flags in the dictionary file and sets options for Hunspell's dictionary processing."
The Foo/Simpson example makes no sense: "plus Foo will be recognized with affixes of Simpson (Foo’s etc.)". What is a "Simpson affix"? Do you mean FooSimpson is OK? Or is Simpson a set of codes in the .aff file? But then why is 's' repeated?
"‘TRY’ suggestions differ from the bad word with an English letter or an apostrophe ...
TRY esianrtolcdugmphbyfvkwzESIANRTOLCDUGMPHBYFVKWZ’ "
makes no sense either. What is this "bad word" they differ from? I assumed TRY was a set of codes in the .aff file that drive replacement, it was only after re-re-reading that I understood it's a set of letters that can be wrong. You need to say "In this example, the TRY option lists the letters (and apostrophe). If a misspelled word differs from a word in the dictionary file by one of these letters, then Hunspell can suggest that dictionary word." Please give an example where TRY succeeds and where it fails, explain why the English list is almost every letter but not all (why not 'j' and 'q'?), and why the letters are in that strange order (does it first look up misspellings of 'e', then of 's'...?).
"There are two affix classes in the dictionary. Class A defines ...". One has to be reading very carefully to know that this continues to talk about the example above and not about Hunspell in general. That's why I recommend having a subsection for each example, and say "The example dictionary above defines two affix classes..."
Does "personal dictionary" differ from the regular .dic dictionary? Must it have the same extension?
"AF definitions in the affix file: SET ... TRY ... AF ..." the example includes SET and TRY lines, but they don't seem to be relevant here. Either be explicit when you're giving a complete .aff file vs. a portion of one, or only list what's relevant to the example.
etc., etc. Hunspell is an amazing effort, but very hard to get into.
Thanks for your comments and fixes, better documentation is crucial for the dictionary development.