Spell-checking

The right or wrong spelling of terms in technical documents is very important. Thus, it's always important to carefully spell-check your manuals, making sure that both technical and general terms are correctly spelt.

Unfortunately, spell-checking a mdoc document is fairly difficult, as the spell-checker must have some knowledge of the language structure to discern text from macros. Consider spell-checking checking the following snippet.

By now we understand that Fl and Ar are macros. But it's unreasonable to expect a spell-checker to do so. Thus, spell-checking manuals often raise many false-positives.

spell

The spell utility is distributed with many BSD UNIX operating systems as a simplistic spell-checker. In fact, it was first distributed with Version 6 AT&T UNIX. spell preprocesses its input with deroff, another historic utility with some functionality of stripping roff instructions from files.

To print a list of all unknown words, you can explicitly invoke deroff and spell as follows:

A utility distributed with mandoc, demandoc, is significantly stronger than deroff. If available, it should be used instead. It has the same calling syntax of deroff.

You can also maintain a per-manual list of technical terms by using additional word lists. In the case of file.1, consider a sorted list of words file.1.words we're maintaining with special words (such as names). We could then augment a make rule to automatically make sure additions are spell-checked.

This snippet first makes the build of file.1 depend upon its local word file, file.1.words, a sorted list of words to ignore. When file.in.1 or file.1.words is updated, the rule is executed. It first makes sure that file.in.1 is well-formed, then spell-checks it against the ignored-words file.

The same can be accomplished on systems without mandoc.

ispell, aspell

Another common spell-checker is ispell and its GNU replacement aspell. I do not suggest using these utilities because of their poor internal support for mdoc. It's possible, however, to send stripped files for checking in a manner similar to spell:

Or with deroff:

Both ispell and aspell also have a pipe mode for more meaningful output:

Last edited by $Author: kristaps $ on $Date: 2011/11/04 01:06:28 $. Copyright © 2011, Kristaps Dzonsons. CC BY-SA.