igor: Checking FreeBSD documents
wblock at wonkity.com
Tue Dec 20 23:23:02 UTC 2011
The many rules for man pages and DocBook are a bit much to remember when
months can pass between working on the various types. My mentors Glen
Barber and Benedict Reuschling have been very good at catching this kind
of thing, but repetitive tasks are what computers are supposed to do for
After not finding much to do automated checking, I slapped together a
Perl program called "igor" that does some of this. At present it checks
all types of files for repeated words ("is is"), common spelling
mistakes collected from FreeBSD documents, FreeBSD obsolete features
(just "cvsup" so far), bad phrases ("the to"), and bad whitespace (blank
lines with whitespace or lines with trailing whitespace). Oh, and
there's a separate style check that makes some subjective suggestions.
mdoc(7) documents are also tested for document date, sentences starting
on a new line, and document structure (Dd, Dt, Os, Sh NAME, Nm, Nd,
Sh SYNOPSIS, Sh DESCRIPTION occurring in the right order and with
DocBook SGML documents are also tested for correct indentation (a
terrible hack even when compared to the surrounding code), indentation
whitespace, title capitalization, matching open and close tags,
straggling tags, and long lines.
Default is to run all tests, but specifying an individual test runs just
Output is in plain ASCII, or better yet, marked with ANSI color
sequences that help to identify errors visually (usable with 'less -R').
igor handles compressed man pages, and shows filenames when run on
multiple files. It also accepts input on stdin.
igor -R -D ifconfig.8.gz | less -RS
igor -R -D /usr/share/man/man1/*.gz | less -RS
igor -R chapter.sgml | less -RS
igor is really more of a proof-of-concept than a finished program.
There are more tests that could be done, and existing tests could be
Still, it's useful as-is. Maybe presenting it will spur someone to
point out a smarter, better, or faster way of doing these tests. Or
rewrite it entirely.
The current version of igor is here:
Perl 5.10 minimum, no dependencies, no port, no warranty. Please
upgrade if you have an earlier version, many changes and improvements
have happened in the last few days.
My thanks to Glen Barber and Benedict Reuschling for their tremendous
patience and help.
More information about the freebsd-doc