home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _941ce0bb7942dd72281697ca73415810 < prev    next >
Encoding:
Text File  |  2000-03-23  |  4.9 KB  |  124 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>Pod::Find - find POD documents in directory trees</TITLE>
  5. <LINK REL="stylesheet" HREF="../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> Pod::Find - find POD documents in directory trees</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <LI><A HREF="#options">OPTIONS</A></LI>
  26.     <LI><A HREF="#author">AUTHOR</A></LI>
  27.     <LI><A HREF="#see also">SEE ALSO</A></LI>
  28. </UL>
  29. <!-- INDEX END -->
  30.  
  31. <HR>
  32. <P>
  33. <H1><A NAME="name">NAME</A></H1>
  34. <P>Pod::Find - find POD documents in directory trees</P>
  35. <P>
  36. <HR>
  37. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  38. <UL>
  39. <LI>Linux</LI>
  40. <LI>Solaris</LI>
  41. <LI>Windows</LI>
  42. </UL>
  43. <HR>
  44. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  45. <PRE>
  46.   use Pod::Find qw(pod_find simplify_name);
  47.   my %pods = pod_find({ -verbose => 1, -inc => 1 });
  48.   foreach(keys %pods) {
  49.      print "found library POD `$pods{$_}' in $_\n";
  50.   }</PRE>
  51. <PRE>
  52.   print "podname=",simplify_name('a/b/c/mymodule.pod'),"\n";</PRE>
  53. <P>
  54. <HR>
  55. <H1><A NAME="description">DESCRIPTION</A></H1>
  56. <P><STRONG>Pod::Find</STRONG> provides a function <STRONG>pod_find</STRONG> that searches for POD
  57. documents in a given set of files and directories. It returns a hash
  58. with the file names as keys and the POD name as value. The POD name
  59. is derived from the file name and its position in the directory tree.</P>
  60. <P>E.g. when searching in <EM>$HOME/perl5lib</EM>, the file
  61. <EM>$HOME/perl5lib/MyModule.pm</EM> would get the POD name <EM>MyModule</EM>,
  62. whereas <EM>$HOME/perl5lib/Myclass/Subclass.pm</EM> would be
  63. <EM>Myclass::Subclass</EM>. The name information can be used for POD
  64. translators.</P>
  65. <P>Only text files containing at least one valid POD command are found.</P>
  66. <P>A warning is printed if more than one POD file with the same POD name
  67. is found, e.g. <EM>CPAN.pm</EM> in different directories. This usually
  68. indicates duplicate occurrences of modules in the <EM>@INC</EM> search path.</P>
  69. <P>The function <STRONG>simplify_name</STRONG> is equivalent to <STRONG>basename</STRONG>, but also
  70. strips Perl-like extensions (.pm, .pl, .pod) and extensions like
  71. <EM>.bat</EM>, <EM>.cmd</EM> on Win32 and OS/2, respectively.</P>
  72. <P>Note that neither <STRONG>pod_find</STRONG> nor <STRONG>simplify_name</STRONG> are exported by
  73. default so be sure to specify them in the <STRONG>use</STRONG> statement if you need
  74. them:</P>
  75. <PRE>
  76.   use Pod::Find qw(pod_find simplify_name);</PRE>
  77. <P>
  78. <HR>
  79. <H1><A NAME="options">OPTIONS</A></H1>
  80. <P>The first argument for <STRONG>pod_find</STRONG> may be a hash reference with options.
  81. The rest are either directories that are searched recursively or files.
  82. The POD names of files are the plain basenames with any Perl-like extension
  83. (.pm, .pl, .pod) stripped.</P>
  84. <DL>
  85. <DT><STRONG><A NAME="item_%2Dverbose"><STRONG>-verbose</STRONG></A></STRONG><BR>
  86. <DD>
  87. Print progress information while scanning.
  88. <P></P>
  89. <DT><STRONG><A NAME="item_%2Dperl"><STRONG>-perl</STRONG></A></STRONG><BR>
  90. <DD>
  91. Apply Perl-specific heuristics to find the correct PODs. This includes
  92. stripping Perl-like extensions, omitting subdirectories that are numeric
  93. but do <EM>not</EM> match the current Perl interpreter's version id, suppressing
  94. <EM>site_perl</EM> as a module hierarchy name etc.
  95. <P></P>
  96. <DT><STRONG><A NAME="item_%2Dscript"><STRONG>-script</STRONG></A></STRONG><BR>
  97. <DD>
  98. Search for PODs in the current Perl interpreter's installation 
  99. <STRONG>scriptdir</STRONG>. This is taken from the local <A HREF="../../lib/Config.html">Config</A> module.
  100. <P></P>
  101. <DT><STRONG><A NAME="item_%2Dinc"><STRONG>-inc</STRONG></A></STRONG><BR>
  102. <DD>
  103. Search for PODs in the current Perl interpreter's <EM>@INC</EM> paths. This
  104. automatically considers paths specified in the <A HREF="../../lib/Pod/perlrun.html#item_PERL5LIB"><CODE>PERL5LIB</CODE></A> environment.
  105. <P></P></DL>
  106. <P>
  107. <HR>
  108. <H1><A NAME="author">AUTHOR</A></H1>
  109. <P>Marek Rouchal <<A HREF="mailto:marek@saftsack.fs.uni-bayreuth.de">marek@saftsack.fs.uni-bayreuth.de</A>>,
  110. heavily borrowing code from Nick Ing-Simmons' PodToHtml.</P>
  111. <P>
  112. <HR>
  113. <H1><A NAME="see also">SEE ALSO</A></H1>
  114. <P><A HREF="../../lib/Pod/Parser.html">the Pod::Parser manpage</A>, <A HREF="../../lib/Pod/Checker.html">the Pod::Checker manpage</A></P>
  115. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  116. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  117. <STRONG><P CLASS=block> Pod::Find - find POD documents in directory trees</P></STRONG>
  118. </TD></TR>
  119. </TABLE>
  120.  
  121. </BODY>
  122.  
  123. </HTML>
  124.