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

NAME

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

SYNOPSIS

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
13        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
17       ...or instead of piping to spell or ispell, use ">temp.txt", and open
18       temp.txt in your word processor for spell-checking.
19

DESCRIPTION

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
28       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
34       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

ADDING STOPWORDS

43       You can add stopwords on a per-document basis with "=for stopwords" /
44       "=for :stopwords" regions, like so:
45
46         =for stopwords  plok Pringe zorch   snik !qux
47         foo bar baz quux quuux
48
49       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
64         =for stopwords !perl Perl
65
66       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
71       You can have several "=for stopwords" regions in your document.  You
72       can even express them like so:
73
74         =begin stopwords
75
76         plok Pringe zorch
77
78         snik !qux
79
80         foo bar
81         baz quux quuux
82
83         =end stopwords
84
85       If you want to use E<...> sequences in a "stopwords" region, you have
86       to use ":stopwords", as here:
87
88         =for :stopwords
89         virtE<ugrave>
90
91       ...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

USING Pod::Spell

99       My personal advice:
100
101       ·   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
106       ·   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
111       ·   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
116       ·   Run it through podchecker again just for good measure.
117

SEE ALSO

119       Pod::Wordlist
120
121       Pod::Parser
122
123       podchecker also known as Pod::Checker
124
125       perlpod, perlpodspec
126

HINT

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
138       This library is free software; you can redistribute it and/or modify it
139       under the same terms as Perl itself.
140
141       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

AUTHOR

147       Sean M. Burke "sburke@cpan.org"
148
149
150
151perl v5.12.0                      2001-10-27                          Spell(3)
Impressum