mingw/html/lib/Pod/Find.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>Pod::Find - find POD documents in directory trees</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;Pod::Find - find POD documents in directory trees</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <ul>
  26
  27                 <li><a href="#pod_find_____opts______directories__"><code>pod_find( { %opts } , @directories )</code></a></li>
  28                 <li><a href="#simplify_name___str__"><code>simplify_name( $str )</code></a></li>
  29                 <li><a href="#pod_where_____opts_____pod__"><code>pod_where( { %opts }, $pod )</code></a></li>
  30                 <li><a href="#contains_pod___file____verbose__"><code>contains_pod( $file , $verbose )</code></a></li>
  31         </ul>
  32
  33         <li><a href="#author">AUTHOR</a></li>
  34         <li><a href="#see_also">SEE ALSO</a></li>
  35 </ul>
  36 <!-- INDEX END -->
  37
  38 <hr />
  39 <p>
  40 </p>
  41 <h1><a name="name">NAME</a></h1>
  42 <p>Pod::Find - find POD documents in directory trees</p>
  43 <p>
  44 </p>
  45 <hr />
  46 <h1><a name="synopsis">SYNOPSIS</a></h1>
  47 <pre>
  48   use Pod::Find qw(pod_find simplify_name);
  49   my %pods = pod_find({ -verbose =&gt; 1, -inc =&gt; 1 });
  50   foreach(keys %pods) {
  51      print &quot;found library POD `$pods{$_}' in $_\n&quot;;
  52   }</pre>
  53 <pre>
  54   print &quot;podname=&quot;,simplify_name('a/b/c/mymodule.pod'),&quot;\n&quot;;</pre>
  55 <pre>
  56   $location = pod_where( { -inc =&gt; 1 }, &quot;Pod::Find&quot; );</pre>
  57 <p>
  58 </p>
  59 <hr />
  60 <h1><a name="description">DESCRIPTION</a></h1>
  61 <p><strong>Pod::Find</strong> provides a set of functions to locate POD files.  Note that
  62 no function is exported by default to avoid pollution of your namespace,
  63 so be sure to specify them in the <strong>use</strong> statement if you need them:</p>
  64 <pre>
  65   use Pod::Find qw(pod_find);</pre>
  66 <p>From this version on the typical SCM (software configuration management)
  67 files/directories like RCS, CVS, SCCS, .svn are ignored.</p>
  68 <p>
  69 </p>
  70 <h2><a name="pod_find_____opts______directories__"><code>pod_find( { %opts } , @directories )</code></a></h2>
  71 <p>The function <strong>pod_find</strong> searches for POD documents in a given set of
  72 files and/or directories. It returns a hash with the file names as keys
  73 and the POD name as value. The POD name is derived from the file name
  74 and its position in the directory tree.</p>
  75 <p>E.g. when searching in <em>$HOME/perl5lib</em>, the file
  76 <em>$HOME/perl5lib/MyModule.pm</em> would get the POD name <em>MyModule</em>,
  77 whereas <em>$HOME/perl5lib/Myclass/Subclass.pm</em> would be
  78 <em>Myclass::Subclass</em>. The name information can be used for POD
  79 translators.</p>
  80 <p>Only text files containing at least one valid POD command are found.</p>
  81 <p>A warning is printed if more than one POD file with the same POD name
  82 is found, e.g. <em>CPAN.pm</em> in different directories. This usually
  83 indicates duplicate occurrences of modules in the <em>@INC</em> search path.</p>
  84 <p><strong>OPTIONS</strong> The first argument for <strong>pod_find</strong> may be a hash reference
  85 with options. The rest are either directories that are searched
  86 recursively or files.  The POD names of files are the plain basenames
  87 with any Perl-like extension (.pm, .pl, .pod) stripped.</p>
  88 <dl>
  89 <dt><strong><a name="item__2dverbose__3d_3e_1"><code>-verbose =&gt; 1</code></a></strong>
  90
  91 <dd>
  92 <p>Print progress information while scanning.</p>
  93 </dd>
  94 </li>
  95 <dt><strong><a name="item__2dperl__3d_3e_1"><code>-perl =&gt; 1</code></a></strong>
  96
  97 <dd>
  98 <p>Apply Perl-specific heuristics to find the correct PODs. This includes
  99 stripping Perl-like extensions, omitting subdirectories that are numeric
 100 but do <em>not</em> match the current Perl interpreter's version id, suppressing
 101 <em>site_perl</em> as a module hierarchy name etc.</p>
 102 </dd>
 103 </li>
 104 <dt><strong><a name="item__2dscript__3d_3e_1"><code>-script =&gt; 1</code></a></strong>
 105
 106 <dd>
 107 <p>Search for PODs in the current Perl interpreter's installation
 108 <strong>scriptdir</strong>. This is taken from the local <a href="file://C|\msysgit\mingw\html/lib/Config.html">Config</a> module.</p>
 109 </dd>
 110 </li>
 111 <dt><strong><a name="item__2dinc__3d_3e_1"><code>-inc =&gt; 1</code></a></strong>
 112
 113 <dd>
 114 <p>Search for PODs in the current Perl interpreter's <em>@INC</em> paths. This
 115 automatically considers paths specified in the <code>PERL5LIB</code> environment
 116 as this is prepended to <em>@INC</em> by the Perl interpreter itself.</p>
 117 </dd>
 118 </li>
 119 </dl>
 120 <p>
 121 </p>
 122 <h2><a name="simplify_name___str__"><code>simplify_name( $str )</code></a></h2>
 123 <p>The function <strong>simplify_name</strong> is equivalent to <strong>basename</strong>, but also
 124 strips Perl-like extensions (.pm, .pl, .pod) and extensions like
 125 <em>.bat</em>, <em>.cmd</em> on Win32 and OS/2, or <em>.com</em> on VMS, respectively.</p>
 126 <p>
 127 </p>
 128 <h2><a name="pod_where_____opts_____pod__"><code>pod_where( { %opts }, $pod )</code></a></h2>
 129 <p>Returns the location of a pod document given a search directory
 130 and a module (e.g. <code>File::Find</code>) or script (e.g. <code>perldoc</code>) name.</p>
 131 <p>Options:</p>
 132 <dl>
 133 <dt><strong><code>-inc =&gt; 1</code></strong>
 134
 135 <dd>
 136 <p>Search @INC for the pod and also the <code>scriptdir</code> defined in the
 137 <a href="file://C|\msysgit\mingw\html/lib/Config.html">Config</a> module.</p>
 138 </dd>
 139 </li>
 140 <dt><strong><a name="item__2ddirs__3d_3e__5b__24dir1_2c__24dir2_2c__2e_2e_2e"><code>-dirs =&gt; [ $dir1, $dir2, ... ]</code></a></strong>
 141
 142 <dd>
 143 <p>Reference to an array of search directories. These are searched in order
 144 before looking in <a href="file://C|\msysgit\mingw\html/pod/perlvar.html#item__inc"><code>@INC</code></a> (if <strong>-inc</strong>). Current directory is used if
 145 none are specified.</p>
 146 </dd>
 147 </li>
 148 <dt><strong><code>-verbose =&gt; 1</code></strong>
 149
 150 <dd>
 151 <p>List directories as they are searched</p>
 152 </dd>
 153 </li>
 154 </dl>
 155 <p>Returns the full path of the first occurrence to the file.
 156 Package names (eg 'A::B') are automatically converted to directory
 157 names in the selected directory. (eg on unix 'A::B' is converted to
 158 'A/B'). Additionally, '.pm', '.pl' and '.pod' are appended to the
 159 search automatically if required.</p>
 160 <p>A subdirectory <em>pod/</em> is also checked if it exists in any of the given
 161 search directories. This ensures that e.g. <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html">perlfunc</a> is
 162 found.</p>
 163 <p>It is assumed that if a module name is supplied, that that name
 164 matches the file name. Pods are not opened to check for the 'NAME'
 165 entry.</p>
 166 <p>A check is made to make sure that the file that is found does
 167 contain some pod documentation.</p>
 168 <p>
 169 </p>
 170 <h2><a name="contains_pod___file____verbose__"><code>contains_pod( $file , $verbose )</code></a></h2>
 171 <p>Returns true if the supplied filename (not POD module) contains some pod
 172 information.</p>
 173 <p>
 174 </p>
 175 <hr />
 176 <h1><a name="author">AUTHOR</a></h1>
 177 <p>Please report bugs using <a href="http://rt.cpan.org">http://rt.cpan.org</a>.</p>
 178 <p>Marek Rouchal &lt;<a href="mailto:marekr@cpan.org">marekr@cpan.org</a>&gt;,
 179 heavily borrowing code from Nick Ing-Simmons' PodToHtml.</p>
 180 <p>Tim Jenness &lt;<a href="mailto:t.jenness@jach.hawaii.edu">t.jenness@jach.hawaii.edu</a>&gt; provided
 181 <code>pod_where</code> and <code>contains_pod</code>.</p>
 182 <p>
 183 </p>
 184 <hr />
 185 <h1><a name="see_also">SEE ALSO</a></h1>
 186 <p><a href="file://C|\msysgit\mingw\html/lib/Pod/Parser.html">the Pod::Parser manpage</a>, <a href="file://C|\msysgit\mingw\html/lib/Pod/Checker.html">the Pod::Checker manpage</a>, <a href="file://C|\msysgit\mingw\html/pod/perldoc.html">the perldoc manpage</a></p>
 187 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 188 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 189 <big><strong><span class="block">&nbsp;Pod::Find - find POD documents in directory trees</span></strong></big>
 190 </td></tr>
 191 </table>
 192
 193 </body>
 194
 195 </html>