1Test::Spelling(3)     User Contributed Perl Documentation    Test::Spelling(3)
2
3
4

NAME

6       Test::Spelling - check for spelling errors in POD files
7

SYNOPSIS

9       "Test::Spelling" lets you check the spelling of a POD file, and report
10       its results in standard "Test::Simple" fashion. This module requires
11       the spell program.
12
13           use Test::More;
14           use Test::Spelling;
15           plan tests => $num_tests;
16           pod_file_spelling_ok( $file, "POD file spelling OK" );
17
18       Module authors can include the following in a t/pod_spell.t file and
19       have "Test::Spelling" automatically find and check all POD files in a
20       module distribution:
21
22           use Test::More;
23           use Test::Spelling;
24           all_pod_files_spelling_ok();
25
26       Note, however that it is not really recommended to include this test
27       with a CPAN distribution, or a package that will run in an uncontrolled
28       environment, because there's no way of predicting if spell will be
29       available or the word list used will give the same results (what if
30       it's in a different language, for example?). You can have the test, but
31       don't add it to MANIFEST (or add it to MANIFEST.SKIP to make sure you
32       don't add it by accident). Anyway, your users don't really need to run
33       this test, as it is unlikely that the documentation will acquire typos
34       while in transit. :-)
35
36       You can add your own stopwords (words that should be ignored by the
37       spell check):
38
39           add_stopwords(qw(asdf thiswordiscorrect));
40
41       These stopwords are global for the test. See Pod::Spell for a variety
42       of ways to add per-file stopwords to each .pm file.
43

DESCRIPTION

45       Check POD files for spelling mistakes, using Pod::Spell and spell to do
46       the heavy lifting.
47

FUNCTIONS

49       pod_file_spelling_ok( FILENAME[, TESTNAME ] )
50
51       "pod_file_spelling_ok()" will okay the test if the POD has no spelling
52       errors.
53
54       When it fails, "pod_file_spelling_ok()" will show any spelling errors
55       as diagnostics.
56
57       The optional second argument TESTNAME is the name of the test.  If it
58       is omitted, "pod_file_spelling_ok()" chooses a default test name "POD
59       spelling for FILENAME".
60
61       all_pod_files_spelling_ok( [@files/@directories] )
62
63       Checks all the files in @files for POD spelling.  It runs
64       all_pod_files() on each file/directory, and calls the "plan()" function
65       for you (one test for each function), so you can't have already called
66       "plan".
67
68       If @files is empty or not passed, the function finds all POD files in
69       the blib directory if it exists, or the lib directory if not.  A POD
70       file is one that ends with .pod, .pl and .pm, or any file where the
71       first line looks like a shebang line.
72
73       If you're testing a module, just make a t/spell.t:
74
75           use Test::More;
76           use Test::Spelling;
77           all_pod_files_spelling_ok();
78
79       Returns true if all pod files are ok, or false if any fail.
80
81       all_pod_files( [@dirs] )
82
83       Returns a list of all the Perl files in $dir and in directories below.
84       If no directories are passed, it defaults to blib if blib exists, or
85       else lib if not.  Skips any files in CVS or .svn directories.
86
87       A Perl file is:
88
89       * Any file that ends in .PL, .pl, .pm, .pod or .t.
90       * Any file that has a first line with a shebang and "perl" on it.
91
92       The order of the files returned is machine-dependent.  If you want them
93       sorted, you'll have to sort them yourself.
94
95       add_stopwords(@words)
96
97       Add words that should be skipped by the spell check. A suggested use is
98       to list these words, one per line, in the __DATA__ section of your test
99       file, and just call
100
101           add_stopwords(<DATA>);
102
103       As a convenience, "add_stopwords" will automatically ignore a comment
104       mark and one or more spaces from the beginning of the line, and it will
105       ignore lines that say '# Error:' or '# Looks like' or /Failed test/.
106       The reason? Let's say you run a test and get this result:
107
108           1..1
109           not ok 1 - POD spelling for lib/Test/Spelling.pm
110           #     Failed test (lib/Test/Spelling.pm at line 70)
111           # Errors:
112           #     stopwords
113           # Looks like you failed 1 tests of 1.
114
115       Let's say you decide that all the words that were marked as errors are
116       really correct. The diagnostic lines are printed to STDERR; that means
117       that, if you have a decent shell, you can type something like
118
119           perl t/spell.t 2>> t/spell.t
120
121       which will append the diagnostic lines to the end of your test file.
122       Assuming you already have a __DATA__ line in your test file, that
123       should be enough to ensure that the test passes the next time.
124
125       Also note that Pod::Spell skips words believed to be code, such as
126       words in verbatim blocks and code labeled with C<>.
127
128       set_spell_cmd($command)
129
130       If the spell program has a different name or is not in your path, you
131       can specify an alternative with "set_spell_cmd". Any command that takes
132       text from standard input and prints a list of misspelled words, one per
133       line, to standard output will do. For example, you can use "aspell -l".
134

SEE ALSO

136       Pod::Spell
137

VERSION

139       0.11
140

AUTHOR

142       Ivan Tubert-Brohman "<itub@cpan.org>"
143
144       Heavily based on Test::Pod by Andy Lester and brian d foy.
145

COPYRIGHT

147       Copyright 2005, Ivan Tubert-Brohman, All Rights Reserved.
148
149       You may use, modify, and distribute this package under the same terms
150       as Perl itself.
151
152
153
154perl v5.8.8                       2005-11-15                 Test::Spelling(3)