1Pod::Spell(3) User Contributed Perl Documentation Pod::Spell(3)
2
6 Pod::Spell - a formatter for spellchecking Pod
7
9 version 1.04
10
12 use Pod::Spell;
13 Pod::Spell->new->parse_from_file( 'File.pm' );
14 Pod::Spell->new->parse_from_filehandle( $infile, $outfile );
16 Also look at podspell
18 % perl -MPod::Spell -e "Pod::Spell->new->parse_from_file(shift)" Thing.pm |spell |fmt
20 ...or instead of piping to spell or "ispell", use ">temp.txt", and open
22 temp.txt in your word processor for spell-checking.
23
25 Pod::Spell is a Pod formatter whose output is good for spellchecking.
26 Pod::Spell rather like Pod::Text, except that it doesn't put much
27 effort into actual formatting, and it suppresses things that look like
28 Perl symbols or Perl jargon (so that your spellchecking program won't
29 complain about mystery words like "$thing" or ""Foo::Bar"" or
30 "hashref").
31 This class provides no new public methods. All methods of interest are
33 inherited from Pod::Parser (which see). The especially interesting
34 ones are "parse_from_filehandle" (which without arguments takes from
35 STDIN and sends to STDOUT) and "parse_from_file". But you can probably
36 just make do with the examples in the synopsis though.
37 This class works by filtering out words that look like Perl or any form
39 of computerese (like "$thing" or ""N>7"" or ""@{$foo}{'bar','baz'}"",
40 anything in C<...> or F<...> codes, anything in verbatim paragraphs
41 (code blocks), and anything in the stopword list. The default stopword
42 list for a document starts out from the stopword list defined by
43 Pod::Wordlist, and can be supplemented (on a per-document basis) by
44 having "=for stopwords" / "=for :stopwords" region(s) in a document.
45
47 new
48 command
49 interior_sequence
50 textblock
51 verbatim
53 You can add stopwords on a per-document basis with "=for stopwords" /
54 "=for :stopwords" regions, like so:
55 =for stopwords plok Pringe zorch snik !qux
57 foo bar baz quux quuux
58 This adds every word in that paragraph after "stopwords" to the
60 stopword list, effective for the rest of the document. In such a list,
61 words are whitespace-separated. (The amount of whitespace doesn't
62 matter, as long as there's no blank lines in the middle of the
63 paragraph.) Words beginning with "!" are deleted from the stopword
64 list -- so "!qux" deletes "qux" from the stopword list, if it was in
65 there in the first place. Note that if a stopword is all-lowercase,
66 then it means that it's okay in any case; but if the word has any
67 capital letters, then it means that it's okay only with that case. So
68 a Wordlist entry of "perl" would permit "perl", "Perl", and (less
69 interestingly) "PERL", "pERL", "PerL", et cetera. However, a Wordlist
70 entry of "Perl" catches only "Perl", not "perl". So if you wanted to
71 make sure you said only "Perl", never "perl", you could add this to the
72 top of your document:
73 =for stopwords !perl Perl
75 Then all instances of the word "Perl" would be weeded out of the
77 Pod::Spell-formatted version of your document, but any instances of the
78 word "perl" would be left in (unless they were in a C<...> or F<...>
79 style).
80 You can have several "=for stopwords" regions in your document. You
82 can even express them like so:
83 =begin stopwords
85 plok Pringe zorch
87 snik !qux
89 foo bar
91 baz quux quuux
92 =end stopwords
94 If you want to use E<...> sequences in a "stopwords" region, you have
96 to use ":stopwords", as here:
97 =for :stopwords
99 virtE<ugrave>
100 ...meaning that you're adding a stopword of "virtu". If you left the
102 ":" out, that would mean you were adding a stopword of "virtE<ugrave>"
103 (with a literal E, a literal <, etc), which will have no effect, since
104 any occurrences of virtE<ugrave> don't look like a normal human-
105 language word anyway, and so would be screened out before the stopword
106 list is consulted anyway.
107
109 My personal advice:
110 · Write your documentation in Pod. Pod is described in perlpod. And
112 perlmodstyle has some advice on content. This is the stage where
113 you want to make sure you say everything you should, have good and
114 working examples, and have coherent grammar.
115 · Run it through podchecker. This will report all sorts of problems
117 with your Pod; you may choose to ignore some of these problems.
118 Some, like "*** WARNING: Unknown entity E<qacute>...", you should
119 pay attention to.
120 · Once podchecker errors have been tended to, spellcheck the pod by
122 running it through podspell / Pod::Spell. For any misspellings
123 that are reported in the Pod::Spell-formatted text, fix them in the
124 original. Repeat until there's no complaints.
125 · Run it through podchecker again just for good measure.
127
129 Pod::Wordlist
130 Pod::Parser
132 podchecker also known as Pod::Checker
134 perlpod, perlpodspec
136
138 If you feed output of Pod::Spell into your word processor and run a
139 spell-check, make sure you're not also running a grammar-check --
140 because Pod::Spell drops words that it thinks are Perl symbols, jargon,
141 or stopwords, this means you'll have ungrammatical sentences, what with
142 words being missing and all. And you don't need a grammar checker to
143 tell you that.
144
146 Please report any bugs or feature requests on the bugtracker website
147 https://github.com/xenoterracide/pod-spell/issues
148 When submitting a bug or request, please include a test-file or a patch
150 to an existing test-file that illustrates the bug or desired feature.
151
153 · Sean M. Burke <sburke@cpan.org>
154 · Caleb Cushing <xenoterracide@gmail.com>
156
158 This software is Copyright (c) 2013 by Caleb Cushing.
159 This is free software, licensed under:
161 The Artistic License 2.0 (GPL Compatible)
163perl v5.16.3 2013-05-09 Pod::Spell(3)