1Spell(3) User Contributed Perl Documentation Spell(3)
2
6 Pod::Spell -- a formatter for spellchecking Pod
7
9 % podspell Thing.pm | ispell
10 or if you don't have a podspell:
11 % perl -MPod::Spell -e "Pod::Spell->new->parse_from_file(shift)" Thing.pm |spell |fmt
12 or:
14 % perl -MPod::Spell -e "Pod::Spell->new->parse_from_filehandle"
15 ...which takes POD on STDIN and sends formatted text to STDOUT
16 ...or instead of piping to spell or ispell, use ">temp.txt", and open
18 temp.txt in your word processor for spell-checking.
19
21 Pod::Spell is a Pod formatter whose output is good for spellchecking.
22 Pod::Spell rather like Pod::Text, except that it doesn't put much
23 effort into actual formatting, and it suppresses things that look like
24 Perl symbols or Perl jargon (so that your spellchecking program won't
25 complain about mystery words like "$thing" or ""Foo::Bar"" or
26 "hashref").
27 This class provides no new public methods. All methods of interest are
29 inherited from Pod::Parser (which see). The especially interesting
30 ones are "parse_from_filehandle" (which without arguments takes from
31 STDIN and sends to STDOUT) and "parse_from_file". But you can probably
32 just make do with the examples in the synopsis though.
33 This class works by filtering out words that look like Perl or any form
35 of computerese (like "$thing" or ""N>7"" or ""@{$foo}{'bar','baz'}"",
36 anything in C<...> or F<...> codes, anything in verbatim paragraphs
37 (codeblocks), and anything in the stopword list. The default stopword
38 list for a document starts out from the stopword list defined by
39 Pod::Wordlist, and can be supplemented (on a per-document basis) by
40 having "=for stopwords" / "=for :stopwords" region(s) in a document.
41
43 You can add stopwords on a per-document basis with "=for stopwords" /
44 "=for :stopwords" regions, like so:
45 =for stopwords plok Pringe zorch snik !qux
47 foo bar baz quux quuux
48 This adds every word in that paragraph after "stopwords" to the
50 stopword list, effective for the rest of the document. In such a list,
51 words are whitespace-separated. (The amount of whitespace doesn't
52 matter, as long as there's no blank lines in the middle of the
53 paragraph.) Words beginning with "!" are deleted from the stopword
54 list -- so "!qux" deletes "qux" from the stopword list, if it was in
55 there in the first place. Note that if a stopword is all-lowercase,
56 then it means that it's okay in any case; but if the word has any
57 capital letters, then it means that it's okay only with that case. So
58 a wordlist entry of "perl" would permit "perl", "Perl", and (less
59 interestingly) "PERL", "pERL", "PerL", et cetera. However, a wordlist
60 entry of "Perl" catches only "Perl", not "perl". So if you wanted to
61 make sure you said only "Perl", never "perl", you could add this to the
62 top of your document:
63 =for stopwords !perl Perl
65 Then all instances of the word "Perl" would be weeded out of the
67 Pod::Spell-formatted version of your document, but any instances of the
68 word "perl" would be left in (unless they were in a C<...> or F<...>
69 style).
70 You can have several "=for stopwords" regions in your document. You
72 can even express them like so:
73 =begin stopwords
75 plok Pringe zorch
77 snik !qux
79 foo bar
81 baz quux quuux
82 =end stopwords
84 If you want to use E<...> sequences in a "stopwords" region, you have
86 to use ":stopwords", as here:
87 =for :stopwords
89 virtE<ugrave>
90 ...meaning that you're adding a stopword of "virtu". If you left the
92 ":" out, that'd mean you were adding a stopword of "virtE<ugrave>"
93 (with a literal E, a literal <, etc), which will have no effect, since
94 any occurrences of virtE<ugrave> don't look like a normal human-
95 language word anyway, and so would be screened out before the stopword
96 list is consulted anyway.
97
99 My personal advice:
100 · Write your documentation in Pod. Pod is described in perlpod. And
102 perlmodstyle has some advice on content. This is the stage where
103 you want to make sure you say everything you should, have good and
104 working examples, and have coherent grammar.
105 · Run it through podchecker. This will report all sorts of problems
107 with your Pod; you may choose to ignore some of these problems.
108 Some, like "*** WARNING: Unknown entity E<qacute>...", you should
109 pay attention to.
110 · Once podchecker errors have been tended to, spellcheck the pod by
112 running it through podspell / Pod::Spell. For any misspellings
113 that are reported in the Pod::Spell-formatted text, fix them in the
114 original. Repeat until there's no complaints.
115 · Run it through podchecker again just for good measure.
117
119 Pod::Wordlist
120 Pod::Parser
122 podchecker also known as Pod::Checker
124 perlpod, perlpodspec
126
128 If you feed output of Pod::Spell into your word processor and run a
129 spell-check, make sure you're not also running a grammar-check --
130 because Pod::Spell drops words that it thinks are Perl symbols, jargon,
131 or stopwords, this means you'll have ungrammatical sentences, what with
132 words being missing and all. And you don't need a grammar checker to
133 tell you that.
134
136 Copyright (c) 2001 Sean M. Burke. All rights reserved.
137 This library is free software; you can redistribute it and/or modify it
139 under the same terms as Perl itself.
140 The programs and documentation in this dist are distributed in the hope
142 that they will be useful, but without any warranty; without even the
143 implied warranty of merchantability or fitness for a particular
144 purpose.
145
147 Sean M. Burke "sburke@cpan.org"
148perl v5.12.0 2001-10-27 Spell(3)