


Pod::Find(3p)    Perl Programmers Reference Guide   Pod::Find(3p)


NAME
       Pod::Find - find POD documents in directory trees

SYNOPSIS
         use Pod::Find qw(pod_find simplify_name);
         my %pods = pod_find({ -verbose => 1, -inc => 1 });
         foreach(keys %pods) {
            print "found library POD `$pods{$_}' in $_\n";
         }

         print "podname=",simplify_name('a/b/c/mymodule.pod'),"\n";


DESCRIPTION
       Pod::Find provides a function pod_find that searches for
       POD documents in a given set of files and directories. It
       returns a hash with the file names as keys and the POD
       name as value. The POD name is derived from the file name
       and its position in the directory tree.

       E.g. when searching in $HOME/perl5lib, the file
       $HOME/perl5lib/MyModule.pm would get the POD name MyMod-
       ule, whereas $HOME/perl5lib/Myclass/Subclass.pm would be
       Myclass::Subclass. The name information can be used for
       POD translators.

       Only text files containing at least one valid POD command
       are found.

       A warning is printed if more than one POD file with the
       same POD name is found, e.g. CPAN.pm in different directo-
       ries. This usually indicates duplicate occurrences of mod-
       ules in the @INC search path.

       The function simplify_name is equivalent to basename, but
       also strips Perl-like extensions (.pm, .pl, .pod) and
       extensions like .bat, .cmd on Win32 and OS/2, respec-
       tively.

       Note that neither pod_find nor simplify_name are exported
       by default so be sure to specify them in the use statement
       if you need them:

         use Pod::Find qw(pod_find simplify_name);


OPTIONS
       The first argument for pod_find may be a hash reference
       with options.  The rest are either directories that are
       searched recursively or files.  The POD names of files are
       the plain basenames with any Perl-like extension (.pm,
       .pl, .pod) stripped.





2000-04-06                 perl v5.6.0                          1





Pod::Find(3p)    Perl Programmers Reference Guide   Pod::Find(3p)


       -verbose
           Print progress information while scanning.

       -perl
           Apply Perl-specific heuristics to find the correct
           PODs. This includes stripping Perl-like extensions,
           omitting subdirectories that are numeric but do not
           match the current Perl interpreter's version id, sup-
           pressing site_perl as a module hierarchy name etc.

       -script
           Search for PODs in the current Perl interpreter's
           installation scriptdir. This is taken from the local
           Config module.

       -inc
           Search for PODs in the current Perl interpreter's @INC
           paths. This automatically considers paths specified in
           the `PERL5LIB' environment.

AUTHOR
       Marek Rouchal <marek@saftsack.fs.uni-bayreuth.de>, heavily
       borrowing code from Nick Ing-Simmons' PodToHtml.

SEE ALSO
       the Pod::Parser manpage, the Pod::Checker manpage































2000-04-06                 perl v5.6.0                          2


