.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Pod 3"
.TH Pod 3 "2006-07-19" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Test::Pod \- check for POD errors in files
.SH "VERSION"
.IX Header "VERSION"
Version 1.26
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\f(CW\*(C`Test::Pod\*(C'\fR lets you check the validity of a \s-1POD\s0 file, and report
its results in standard \f(CW\*(C`Test::Simple\*(C'\fR fashion.
.PP
.Vb 2
\&    use Test::Pod tests => $num_tests;
\&    pod_file_ok( $file, "Valid POD file" );
.Ve
.PP
Module authors can include the following in a \fIt/pod.t\fR file and
have \f(CW\*(C`Test::Pod\*(C'\fR automatically find and check all \s-1POD\s0 files in a
module distribution:
.PP
.Vb 4
\&    use Test::More;
\&    eval "use Test::Pod 1.00";
\&    plan skip_all => "Test::Pod 1.00 required for testing POD" if $@;
\&    all_pod_files_ok();
.Ve
.PP
You can also specify a list of files to check, using the
\&\f(CW\*(C`all_pod_files()\*(C'\fR function supplied:
.PP
.Vb 6
\&    use strict;
\&    use Test::More;
\&    eval "use Test::Pod 1.00";
\&    plan skip_all => "Test::Pod 1.00 required for testing POD" if $@;
\&    my @poddirs = qw( blib script );
\&    all_pod_files_ok( all_pod_files( @poddirs ) );
.Ve
.PP
Or even (if you're running under Apache::Test):
.PP
.Vb 4
\&    use strict;
\&    use Test::More;
\&    eval "use Test::Pod 1.00";
\&    plan skip_all => "Test::Pod 1.00 required for testing POD" if $@;
.Ve
.PP
.Vb 5
\&    my @poddirs = qw( blib script );
\&    use File::Spec::Functions qw( catdir updir );
\&    all_pod_files_ok(
\&        all_pod_files( map { catdir updir, $_ } @poddirs )
\&    );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Check \s-1POD\s0 files for errors or warnings in a test file, using
\&\f(CW\*(C`Pod::Simple\*(C'\fR to do the heavy lifting.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.Sh "pod_file_ok( FILENAME[, \s-1TESTNAME\s0 ] )"
.IX Subsection "pod_file_ok( FILENAME[, TESTNAME ] )"
\&\f(CW\*(C`pod_file_ok()\*(C'\fR will okay the test if the \s-1POD\s0 parses correctly.  Certain
conditions are not reported yet, such as a file with no pod in it at all.
.PP
When it fails, \f(CW\*(C`pod_file_ok()\*(C'\fR will show any pod checking errors as
diagnostics.
.PP
The optional second argument \s-1TESTNAME\s0 is the name of the test.  If it
is omitted, \f(CW\*(C`pod_file_ok()\*(C'\fR chooses a default test name \*(L"\s-1POD\s0 test
for \s-1FILENAME\s0\*(R".
.Sh "all_pod_files_ok( [@files/@directories] )"
.IX Subsection "all_pod_files_ok( [@files/@directories] )"
Checks all the files in \f(CW@files\fR for valid \s-1POD\s0.  It runs
\&\fIall_pod_files()\fR on each file/directory, and calls the \f(CW\*(C`plan()\*(C'\fR function for you
(one test for each function), so you can't have already called \f(CW\*(C`plan\*(C'\fR.
.PP
If \f(CW@files\fR is empty or not passed, the function finds all \s-1POD\s0 files in
the \fIblib\fR directory if it exists, or the \fIlib\fR directory if not.
A \s-1POD\s0 file is one that ends with \fI.pod\fR, \fI.pl\fR and \fI.pm\fR, or any file
where the first line looks like a shebang line.
.PP
If you're testing a module, just make a \fIt/pod.t\fR:
.PP
.Vb 4
\&    use Test::More;
\&    eval "use Test::Pod 1.00";
\&    plan skip_all => "Test::Pod 1.00 required for testing POD" if $@;
\&    all_pod_files_ok();
.Ve
.PP
Returns true if all pod files are ok, or false if any fail.
.Sh "all_pod_files( [@dirs] )"
.IX Subsection "all_pod_files( [@dirs] )"
Returns a list of all the Perl files in \fI$dir\fR and in directories below.
If no directories are passed, it defaults to \fIblib\fR if \fIblib\fR exists,
or else \fIlib\fR if not.  Skips any files in \s-1CVS\s0 or .svn directories.
.PP
A Perl file is:
.IP "* Any file that ends in \fI.PL\fR, \fI.pl\fR, \fI.pm\fR, \fI.pod\fR or \fI.t\fR." 4
.IX Item "Any file that ends in .PL, .pl, .pm, .pod or .t."
.PD 0
.ie n .IP "* Any file that has a first line with a shebang and ""perl"" on it." 4
.el .IP "* Any file that has a first line with a shebang and ``perl'' on it." 4
.IX Item "Any file that has a first line with a shebang and perl on it."
.PD
.PP
The order of the files returned is machine\-dependent.  If you want them
sorted, you'll have to sort them yourself.
.SH "TODO"
.IX Header "TODO"
\&\s-1STUFF\s0 \s-1TO\s0 \s-1DO\s0
.PP
Note the changes that are being made.
.PP
Note that you no longer can test for \*(L"no pod\*(R".
.SH "AUTHOR"
.IX Header "AUTHOR"
Currently maintained by Andy Lester, \f(CW\*(C`<andy at petdance.com>\*(C'\fR.
.PP
Originally by brian d foy.
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
Thanks to
David Wheeler
and
Peter Edwards
for contributions and to \f(CW\*(C`brian d foy\*(C'\fR for the original code.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2006, Andy Lester, All Rights Reserved.
.PP
You may use, modify, and distribute this package under the
same terms as Perl itself.