1Pod::Spell(3) User Contributed Perl Documentation Pod::Spell(3)
2
6 Pod::Spell - a formatter for spellchecking Pod
7
9 version 1.20
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 stopwords
49 $self->stopwords->isa('Pod::WordList'); # true
50 parse_from_filehandle($in_fh,$out_fh)
52 This method takes an input filehandle (which is assumed to already be
53 opened for reading) and reads the entire input stream looking for
54 blocks (paragraphs) of POD documentation to be processed. If no first
55 argument is given the default input filehandle "STDIN" is used.
56 The $in_fh parameter may be any object that provides a getline() method
58 to retrieve a single line of input text (hence, an appropriate wrapper
59 object could be used to parse PODs from a single string or an array of
60 strings).
61 parse_from_file($filename,$outfile)
63 This method takes a filename and does the following:
64 • opens the input and output files for reading (creating the
66 appropriate filehandles)
67 • invokes the parse_from_filehandle() method passing it the
69 corresponding input and output filehandles.
70 • closes the input and output files.
72 If the special input filename "", "-" or "<&STDIN" is given then the
74 STDIN filehandle is used for input (and no open or close is performed).
75 If no input filename is specified then "-" is implied. Filehandle
76 references, or objects that support the regular IO operations (like
77 "<$fh>" or "$fh-<Egt"getline>) are also accepted; the handles must
78 already be opened.
79 If a second argument is given then it should be the name of the desired
81 output file. If the special output filename "-" or ">&STDOUT" is given
82 then the STDOUT filehandle is used for output (and no open or close is
83 performed). If the special output filename ">&STDERR" is given then the
84 STDERR filehandle is used for output (and no open or close is
85 performed). If no output filehandle is currently in use and no output
86 filename is specified, then "-" is implied. Alternatively, filehandle
87 references or objects that support the regular IO operations (like
88 "print", e.g. IO::String) are also accepted; the object must already be
89 opened.
90
92 Pod::Parser, which Pod::Spell extends, is extremely naive about
93 character encodings. The "parse_from_file" method does not apply any
94 PerlIO encoding layer. If your Pod file is encoded in UTF-8, your data
95 will be read incorrectly.
96 You should instead use "parse_from_filehandle" and manage the input and
98 output layers yourself.
99 binmode($_, ":utf8") for ($infile, $outfile);
101 $my ps = Pod::Spell->new;
102 $ps->parse_from_filehandle( $infile, $outfile );
103 If your output destination cannot handle UTF-8, you should set your
105 output handle to Latin-1 and tell Pod::Spell to strip out words with
106 wide characters.
107 binmode($infile, ":utf8");
109 binmode($outfile, ":encoding(latin1)");
110 $my ps = Pod::Spell->new( no_wide_chars => 1 );
111 $ps->parse_from_filehandle( $infile, $outfile );
112
114 You can add stopwords on a per-document basis with "=for stopwords" /
115 "=for :stopwords" regions, like so:
116 =for stopwords plok Pringe zorch snik !qux
118 foo bar baz quux quuux
119 This adds every word in that paragraph after "stopwords" to the
121 stopword list, effective for the rest of the document. In such a list,
122 words are whitespace-separated. (The amount of whitespace doesn't
123 matter, as long as there's no blank lines in the middle of the
124 paragraph.) Plural forms are added automatically using
125 Lingua::EN::Inflect. Words beginning with "!" are deleted from the
126 stopword list -- so "!qux" deletes "qux" from the stopword list, if it
127 was in there in the first place. Note that if a stopword is all-
128 lowercase, then it means that it's okay in any case; but if the word
129 has any capital letters, then it means that it's okay only with that
130 case. So a Wordlist entry of "perl" would permit "perl", "Perl", and
131 (less interestingly) "PERL", "pERL", "PerL", et cetera. However, a
132 Wordlist entry of "Perl" catches only "Perl", not "perl". So if you
133 wanted to make sure you said only "Perl", never "perl", you could add
134 this to the top of your document:
135 =for stopwords !perl Perl
137 Then all instances of the word "Perl" would be weeded out of the
139 Pod::Spell-formatted version of your document, but any instances of the
140 word "perl" would be left in (unless they were in a C<...> or F<...>
141 style).
142 You can have several "=for stopwords" regions in your document. You
144 can even express them like so:
145 =begin stopwords
147 plok Pringe zorch
149 snik !qux
151 foo bar
153 baz quux quuux
154 =end stopwords
156 If you want to use E<...> sequences in a "stopwords" region, you have
158 to use ":stopwords", as here:
159 =for :stopwords
161 virtE<ugrave>
162 ...meaning that you're adding a stopword of "virtù". If you left the
164 ":" out, that would mean you were adding a stopword of "virtE<ugrave>"
165 (with a literal E, a literal <, etc), which will have no effect, since
166 any occurrences of virtE<ugrave> don't look like a normal human-
167 language word anyway, and so would be screened out before the stopword
168 list is consulted anyway.
169
171 finding stopwords defined with "=for"
172 Pod::Spell makes a single pass over the POD. Stopwords must be added
173 before they show up in the POD.
174 finding the wordlist
176 Pod::Spell uses File::ShareDir::ProjectDistDir if you're getting errors
177 about the wordlist being missing, chances are it's a problem with its
178 heuristics. Set "PATH_ISDEV_DEBUG=1" or "PATH_FINDDEV_DEBUG=1", or both
179 in your environment for debugging, and then file a bug with
180 File::ShareDir::ProjectDistDir if necessary.
181
183 If you feed output of Pod::Spell into your word processor and run a
184 spell-check, make sure you're not also running a grammar-check --
185 because Pod::Spell drops words that it thinks are Perl symbols, jargon,
186 or stopwords, this means you'll have ungrammatical sentences, what with
187 words being missing and all. And you don't need a grammar checker to
188 tell you that.
189
191 Pod::Wordlist
192 Pod::Parser
194 podchecker also known as Pod::Checker
196 perlpod, perlpodspec
198
200 • David Golden <dagolden@cpan.org>
201 • Kent Fredric <kentfredric@gmail.com>
203 • Mohammad S Anwar <mohammad.anwar@yahoo.com>
205 • Olivier Mengué <dolmen@cpan.org>
207 • Paulo Custodio <pauloscustodio@gmail.com>
209
211 • Sean M. Burke <sburke@cpan.org>
212 • Caleb Cushing <xenoterracide@gmail.com>
214
216 This software is Copyright (c) 2016 by Olivier Mengué.
217 This is free software, licensed under:
219 The Artistic License 2.0 (GPL Compatible)
221perl v5.34.0 2022-01-21 Pod::Spell(3)