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 stop‐
50 word list, effective for the rest of the document. In such a list,
51 words are whitespace-separated. (The amount of whitespace doesn't mat‐
52 ter, as long as there's no blank lines in the middle of the paragraph.)
53 Words beginning with "!" are deleted from the stopword list -- so
54 "!qux" deletes "qux" from the stopword list, if it was in there in the
55 first place. Note that if a stopword is all-lowercase, then it means
56 that it's okay in any case; but if the word has any capital letters,
57 then it means that it's okay only with that case. So a wordlist entry
58 of "perl" would permit "perl", "Perl", and (less interestingly) "PERL",
59 "pERL", "PerL", et cetera. However, a wordlist entry of "Perl" catches
60 only "Perl", not "perl". So if you wanted to make sure you said only
61 "Perl", never "perl", you could add this to the top of your document:
62 =for stopwords !perl Perl
64 Then all instances of the word "Perl" would be weeded out of the
66 Pod::Spell-formatted version of your document, but any instances of the
67 word "perl" would be left in (unless they were in a C<...> or F<...>
68 style).
69 You can have several "=for stopwords" regions in your document. You
71 can even express them like so:
72 =begin stopwords
74 plok Pringe zorch
76 snik !qux
78 foo bar
80 baz quux quuux
81 =end stopwords
83 If you want to use E<...> sequences in a "stopwords" region, you have
85 to use ":stopwords", as here:
86 =for :stopwords
88 virtE<ugrave>
89 ...meaning that you're adding a stopword of "virtu". If you left the
91 ":" out, that'd mean you were adding a stopword of "virtE<ugrave>"
92 (with a literal E, a literal <, etc), which will have no effect, since
93 any occurrences of virtE<ugrave> don't look like a normal human-lan‐
94 guage word anyway, and so would be screened out before the stopword
95 list is consulted anyway.
96
98 My personal advice:
99 · Write your documentation in Pod. Pod is described in perlpod. And
101 perlmodstyle has some advice on content. This is the stage where
102 you want to make sure you say everything you should, have good and
103 working examples, and have coherent grammar.
104 · Run it through podchecker. This will report all sorts of problems
106 with your Pod; you may choose to ignore some of these problems.
107 Some, like "*** WARNING: Unknown entity E<qacute>...", you should
108 pay attention to.
109 · Once podchecker errors have been tended to, spellcheck the pod by
111 running it through podspell / Pod::Spell. For any misspellings
112 that are reported in the Pod::Spell-formatted text, fix them in the
113 original. Repeat until there's no complaints.
114 · Run it through podchecker again just for good measure.
116
118 Pod::Wordlist
119 Pod::Parser
121 podchecker also known as Pod::Checker
123 perlpod, perlpodspec
125
127 If you feed output of Pod::Spell into your word processor and run a
128 spell-check, make sure you're not also running a grammar-check --
129 because Pod::Spell drops words that it thinks are Perl symbols, jargon,
130 or stopwords, this means you'll have ungrammatical sentences, what with
131 words being missing and all. And you don't need a grammar checker to
132 tell you that.
133
135 Copyright (c) 2001 Sean M. Burke. All rights reserved.
136 This library is free software; you can redistribute it and/or modify it
138 under the same terms as Perl itself.
139 The programs and documentation in this dist are distributed in the hope
141 that they will be useful, but without any warranty; without even the
142 implied warranty of merchantability or fitness for a particular pur‐
143 pose.
144
146 Sean M. Burke "sburke@cpan.org"
147perl v5.8.8 2001-10-27 Spell(3)