Improve the speling for you moduels documention

We all know that perl documentation is often full of typos. I know, certainly, that my modules are. :-) I usually didn't spell check my modules because it was a relatively painful process: first, convert the POD to plain text; then, check it with a spell checker; finally, make sure that the real typos don't get lost among the many false positives.

Today I noticed that a module that simplifies this task has been available for years: Pod::Spell. It comes with a program called "podspell" that extracts the POD, converts it to text, and removes everything that should be code, such as verbatim blocks and words tagged with C<>. It also removes many common words related to Perl and programming, so that they don't get flagged as errors by your spell checker. The whole process gets reduced to something like

podspell My/Module.pm | spell
[download]

(assuming you have the "spell" program).

But even that is not enough. I know that this kind of thing won't get done unless it's automated. I would like to include a spelling check in my test suite. To do that, I just wrote Test::Spelling. Now I just need to add a small test file, call it something like "t/spell.t", and

make test
[download]

will complain if there are any typos. Of course, the stopword list in the test file has to be kept up to date so that the test doesn't report failures.

Test::Spelling is my first testing module, and is heavily based in Test::Pod. For more information, see the documentation for Test::Spelling.

Comment on Improve the speling for you moduels documention Select or Download Code

Replies are listed 'Best First'.
Re: Improve the speling for you moduels documention by xdg (Monsignor) on Aug 03, 2005 at 14:02 UTC
Kudos. That is a really great idea for eliminating annoying typos in POD -- somehow, I always seem to catch a typo after I've released to CPAN (something to do with the really nice POD2HTML formatter they have, I guess). However... at the risk of reopening the Test::Pod/Test::Pod::Coverage flamewar, I'm also really glad that you caution in your docs about including a test like this in a distribution because of the the new dependency chain it adds: Pod::Spell and Test::Spelling have to be installed (or downloaded and installed) or tests will fail (though smart use of `eval "require ..."` can address that) The Pod::Spell version with stopwords needs to be the same as what you tested before release to not let something unexpected through (though it's not been updated since 2001, so that may not be much of an issue) It relies upon an external spell checker program, which may or may not exist or exist by the hardcoded name provided The way I see it, unless one is only writing for internal use or for someone with exactly the same system setup that one has, there are going to be a lot of spurious failures and frustrated downloaders. If someone wants to check spelling with a .t file, I'd recommend not including it in the MANIFEST (and adding it to MANIFEST.SKIP) so it stays internal for one's own development purposes. For your "todo" list -- I suggest having it skip gracefully instead of failing if it can't find the external spell checker. -xdg Code written by xdg and posted on PerlMonks is public domain. It is provided as is with no warranties, express or implied, of any kind. Posted code may not have been tested. Use of posted code is at your own risk.	[reply] [d/l]
Re^2: Improve the speling for you moduels documention by BUU (Prior) on Aug 03, 2005 at 14:06 UTC
In the same vein as the above ideas, what about just adding it as another target in the Makefile? I confess I have no idea how hard this would actually be, but it seems to make more sense to have the ability to do 'make spell', for example, seperately from the tests.	[reply]
Re^3: Improve the speling for you moduels documention by itub (Priest) on Aug 03, 2005 at 14:22 UTC
It's not too hard, but I prefer to add it as a test, while excluding it from the MANIFEST. That way I don't need to remember to run yet another make target when I prepare my distribution for upload.	[reply]
Re^4: Improve the speling for you moduels documention by xdg (Monsignor) on Aug 03, 2005 at 15:17 UTC
Re: Improve the speling for you moduels documention by adrianh (Chancellor) on Aug 03, 2005 at 12:33 UTC
Nice idea. ++	[reply]
Re: Improve the speeling for you moduels documention by Anonymous Monk on Aug 03, 2005 at 18:15 UTC
Aoccdrnig to a rscheearch at Cmabrigde Uinervtisy, it deosn't mttaer in waht oredr the ltteers in a wrod are, the olny iprmoetnt tihng is taht the frist and lsat ltteer be at the rghit pclae. The rset can be a toatl mses and you can sitll raed it wouthit porbelm. Tihs is bcuseae the huamn mnid deos not raed ervey lteter by istlef, but the wrod as a wlohe.	[reply]
Re^2: Improve the speeling for you moduels documention by kutsu (Priest) on Aug 03, 2005 at 19:06 UTC
Unless you're dyslexic or English isn't your first language or you're tired or .... I happen to fall in the first category and can't understand your post. Update: Fixed grammar, thanks jdporter "Cogito cogito ergo cogito sum - I think that I think, therefore I think that I am." Ambrose Bierce	[reply]


Syntactic Confectionery Delight
	PerlMonks