1Pod::Spell(3)         User Contributed Perl Documentation        Pod::Spell(3)
2
3
4

NAME

6       Pod::Spell - a formatter for spellchecking Pod
7

VERSION

9       version 1.20
10

SYNOPSIS

12               use Pod::Spell;
13               Pod::Spell->new->parse_from_file( 'File.pm' );
14
15               Pod::Spell->new->parse_from_filehandle( $infile, $outfile );
16
17       Also look at podspell
18
19               % perl -MPod::Spell -e "Pod::Spell->new->parse_from_file(shift)" Thing.pm |spell |fmt
20
21       ...or instead of piping to spell or "ispell", use ">temp.txt", and open
22       temp.txt in your word processor for spell-checking.
23

DESCRIPTION

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
32       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
38       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

METHODS

47   new
48   stopwords
49               $self->stopwords->isa('Pod::WordList'); # true
50
51   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
57       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
62   parse_from_file($filename,$outfile)
63       This method takes a filename and does the following:
64
65       • opens the input and output files for reading (creating the
66         appropriate filehandles)
67
68       • invokes the parse_from_filehandle() method passing it the
69         corresponding input and output filehandles.
70
71       • closes the input and output files.
72
73       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
80       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

ENCODINGS

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
97       You should instead use "parse_from_filehandle" and manage the input and
98       output layers yourself.
99
100               binmode($_, ":utf8") for ($infile, $outfile);
101               $my ps = Pod::Spell->new;
102               $ps->parse_from_filehandle( $infile, $outfile );
103
104       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
108               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

ADDING STOPWORDS

114       You can add stopwords on a per-document basis with "=for stopwords" /
115       "=for :stopwords" regions, like so:
116
117         =for stopwords  plok Pringe zorch   snik !qux
118         foo bar baz quux quuux
119
120       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
136         =for stopwords !perl Perl
137
138       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
143       You can have several "=for stopwords" regions in your document.  You
144       can even express them like so:
145
146         =begin stopwords
147
148         plok Pringe zorch
149
150         snik !qux
151
152         foo bar
153         baz quux quuux
154
155         =end stopwords
156
157       If you want to use E<...> sequences in a "stopwords" region, you have
158       to use ":stopwords", as here:
159
160         =for :stopwords
161         virtE<ugrave>
162
163       ...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

BUGS AND LIMITATIONS

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
175   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

HINT

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

SEE ALSO

191       Pod::Wordlist
192
193       Pod::Parser
194
195       podchecker also known as Pod::Checker
196
197       perlpod, perlpodspec
198

CONTRIBUTORS

200       •   David Golden <dagolden@cpan.org>
201
202       •   Kent Fredric <kentfredric@gmail.com>
203
204       •   Mohammad S Anwar <mohammad.anwar@yahoo.com>
205
206       •   Olivier Mengué <dolmen@cpan.org>
207
208       •   Paulo Custodio <pauloscustodio@gmail.com>
209

AUTHORS

211       •   Sean M. Burke <sburke@cpan.org>
212
213       •   Caleb Cushing <xenoterracide@gmail.com>
214
216       This software is Copyright (c) 2016 by Olivier Mengué.
217
218       This is free software, licensed under:
219
220         The Artistic License 2.0 (GPL Compatible)
221
222
223
224perl v5.34.0                      2022-01-21                     Pod::Spell(3)
Impressum