local-lib5/man/man3/Pod::Simple::Search.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Pod::Simple::Search 3"
 132 .TH Pod::Simple::Search 3 "2008-06-03" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Pod::Simple::Search \- find POD documents in directory trees
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 4
 138 \&  use Pod::Simple::Search;
 139 \&  my $name2path = Pod::Simple::Search\->new\->limit_glob('LWP::*')\->survey;
 140 \&  print "Looky see what I found: ",
 141 \&    join(' ', sort keys %$name2path), "\en";
 142 .Ve
 143 .PP
 144 .Vb 3
 145 \&  print "LWPUA docs = ",
 146 \&    Pod::Simple::Search\->new\->find('LWP::UserAgent') || "?",
 147 \&    "\en";
 148 .Ve
 149 .SH "DESCRIPTION"
 150 .IX Header "DESCRIPTION"
 151 \&\fBPod::Simple::Search\fR is a class that you use for running searches
 152 for Pod files.  An object of this class has several attributes
 153 (mostly options for controlling search options), and some methods
 154 for searching based on those attributes.
 155 .PP
 156 The way to use this class is to make a new object of this class,
 157 set any options, and then call one of the search options
 158 (probably \f(CW\*(C`survey\*(C'\fR or \f(CW\*(C`find\*(C'\fR).  The sections below discuss the
 159 syntaxes for doing all that.
 160 .SH "CONSTRUCTOR"
 161 .IX Header "CONSTRUCTOR"
 162 This class provides the one constructor, called \f(CW\*(C`new\*(C'\fR.
 163 It takes no parameters:
 164 .PP
 165 .Vb 2
 166 \&  use Pod::Simple::Search;
 167 \&  my $search = Pod::Simple::Search\->new;
 168 .Ve
 169 .SH "ACCESSORS"
 170 .IX Header "ACCESSORS"
 171 This class defines several methods for setting (and, occasionally,
 172 reading) the contents of an object. With two exceptions (discussed at
 173 the end of this section), these attributes are just for controlling the
 174 way searches are carried out.
 175 .PP
 176 Note that each of these return \f(CW$self\fR when you call them as
 177 \&\f(CW\*(C`$self\->\f(CIwhatever(value)\f(CW\*(C'\fR.  That's so that you can chain
 178 together set-attribute calls like this:
 179 .PP
 180 .Vb 4
 181 \&  my $name2path =
 182 \&    Pod::Simple::Search\->new
 183 \&    \-> inc(0) \-> verbose(1) \-> callback(\e&blab)
 184 \&    \->survey(@there);
 185 .Ve
 186 .PP
 187 \&...which works exactly as if you'd done this:
 188 .PP
 189 .Vb 5
 190 \&  my $search = Pod::Simple::Search\->new;
 191 \&  $search\->inc(0);
 192 \&  $search\->verbose(1);
 193 \&  $search\->callback(\e&blab);
 194 \&  my $name2path = $search\->survey(@there);
 195 .Ve
 196 .IP "$search\->inc( \fItrue-or-false\fR );" 4
 197 .IX Item "$search->inc( true-or-false );"
 198 This attribute, if set to a true value, means that searches should
 199 implicitly add perl's \fI@INC\fR paths. This
 200 automatically considers paths specified in the \f(CW\*(C`PERL5LIB\*(C'\fR environment
 201 as this is prepended to \fI@INC\fR by the Perl interpreter itself.
 202 This attribute's default value is \fB\s-1TRUE\s0\fR.  If you want to search
 203 only specific directories, set \f(CW$self\fR\->\fIinc\fR\|(0) before calling
 204 \&\f(CW$inc\fR\->survey or \f(CW$inc\fR\->find.
 205 .IP "$search\->verbose( \fInonnegative-number\fR );" 4
 206 .IX Item "$search->verbose( nonnegative-number );"
 207 This attribute, if set to a nonzero positive value, will make searches output
 208 (via \f(CW\*(C`warn\*(C'\fR) notes about what they're doing as they do it.
 209 This option may be useful for debugging a pod-related module.
 210 This attribute's default value is zero, meaning that no \f(CW\*(C`warn\*(C'\fR messages
 211 are produced.  (Setting verbose to 1 turns on some messages, and setting
 212 it to 2 turns on even more messages, i.e., makes the following search(es)
 213 even more verbose than 1 would make them.)
 214 .IP "$search\->limit_glob( \fIsome-glob-string\fR );" 4
 215 .IX Item "$search->limit_glob( some-glob-string );"
 216 This option means that you want to limit the results just to items whose
 217 podnames match the given glob/wildcard expression. For example, you
 218 might limit your search to just \*(L"LWP::*\*(R", to search only for modules
 219 starting with \*(L"LWP::*\*(R" (but not including the module \*(L"\s-1LWP\s0\*(R" itself); or
 220 you might limit your search to \*(L"LW*\*(R" to see only modules whose (full)
 221 names begin with \*(L"\s-1LW\s0\*(R"; or you might search for \*(L"*Find*\*(R" to search for
 222 all modules with \*(L"Find\*(R" somewhere in their full name. (You can also use
 223 \&\*(L"?\*(R" in a glob expression; so \*(L"\s-1DB\s0?\*(R" will match \*(L"\s-1DBI\s0\*(R" and \*(L"\s-1DBD\s0\*(R".)
 224 .IP "$search\->callback( \fI\e&some_routine\fR );" 4
 225 .IX Item "$search->callback( &some_routine );"
 226 This attribute means that every time this search sees a matching
 227 Pod file, it should call this callback routine.  The routine is called
 228 with two parameters: the current file's filespec, and its pod name.
 229 (For example: \f(CW\*(C`("/etc/perljunk/File/Crunk.pm", "File::Crunk")\*(C'\fR would
 230 be in \f(CW@_\fR.)
 231 .Sp
 232 The callback routine's return value is not used for anything.
 233 .Sp
 234 This attribute's default value is false, meaning that no callback
 235 is called.
 236 .IP "$search\->laborious( \fItrue-or-false\fR );" 4
 237 .IX Item "$search->laborious( true-or-false );"
 238 Unless you set this attribute to a true value, Pod::Search will
 239 apply Perl-specific heuristics to find the correct module PODs quickly.
 240 This attribute's default value is false.  You won't normally need
 241 to set this to true.
 242 .Sp
 243 Specifically: Turning on this option will disable the heuristics for
 244 seeing only files with Perl-like extensions, omitting subdirectories
 245 that are numeric but do \fInot\fR match the current Perl interpreter's
 246 version \s-1ID\s0, suppressing \fIsite_perl\fR as a module hierarchy name, etc.
 247 .IP "$search\->shadows( \fItrue-or-false\fR );" 4
 248 .IX Item "$search->shadows( true-or-false );"
 249 Unless you set this attribute to a true value, Pod::Simple::Search will
 250 consider only the first file of a given modulename as it looks thru the
 251 specified directories; that is, with this option off, if
 252 Pod::Simple::Search has seen a \f(CW\*(C`somepathdir/Foo/Bar.pm\*(C'\fR already in this
 253 search, then it won't bother looking at a \f(CW\*(C`somelaterpathdir/Foo/Bar.pm\*(C'\fR
 254 later on in that search, because that file is merely a \*(L"shadow\*(R". But if
 255 you turn on \f(CW\*(C`$self\->shadows(1)\*(C'\fR, then these \*(L"shadow\*(R" files are
 256 inspected too, and are noted in the pathname2podname return hash.
 257 .Sp
 258 This attribute's default value is false; and normally you won't
 259 need to turn it on.
 260 .IP "$search\->limit_re( \fIsome-regxp\fR );" 4
 261 .IX Item "$search->limit_re( some-regxp );"
 262 Setting this attribute (to a value that's a regexp) means that you want
 263 to limit the results just to items whose podnames match the given
 264 regexp. Normally this option is not needed, and the more efficient
 265 \&\f(CW\*(C`limit_glob\*(C'\fR attribute is used instead.
 266 .IP "$search\->dir_prefix( \fIsome-string-value\fR );" 4
 267 .IX Item "$search->dir_prefix( some-string-value );"
 268 Setting this attribute to a string value means that the searches should
 269 begin in the specified subdirectory name (like \*(L"Pod\*(R" or \*(L"File::Find\*(R",
 270 also expressable as \*(L"File/Find\*(R"). For example, the search option
 271 \&\f(CW\*(C`$search\->limit_glob("File::Find::R*")\*(C'\fR
 272 is the same as the combination of the search options
 273 \&\f(CW\*(C`$search\->limit_re("^File::Find::R") \-> dir_prefix("File::Find")\*(C'\fR.
 274 .Sp
 275 Normally you don't need to know about the \f(CW\*(C`dir_prefix\*(C'\fR option, but I
 276 include it in case it might prove useful for someone somewhere.
 277 .Sp
 278 (Implementationally, searching with limit_glob ends up setting limit_re
 279 and usually dir_prefix.)
 280 .IP "$search\->progress( \fIsome-progress-object\fR );" 4
 281 .IX Item "$search->progress( some-progress-object );"
 282 If you set a value for this attribute, the value is expected
 283 to be an object (probably of a class that you define) that has a
 284 \&\f(CW\*(C`reach\*(C'\fR method and a \f(CW\*(C`done\*(C'\fR method.  This is meant for reporting
 285 progress during the search, if you don't want to use a simple
 286 callback.
 287 .Sp
 288 Normally you don't need to know about the \f(CW\*(C`progress\*(C'\fR option, but I
 289 include it in case it might prove useful for someone somewhere.
 290 .Sp
 291 While a search is in progress, the progress object's \f(CW\*(C`reach\*(C'\fR and
 292 \&\f(CW\*(C`done\*(C'\fR methods are called like this:
 293 .Sp
 294 .Vb 2
 295 \&  # Every time a file is being scanned for pod:
 296 \&  $progress\->reach($count, "Scanning $file");   ++$count;
 297 .Ve
 298 .Sp
 299 .Vb 2
 300 \&  # And then at the end of the search:
 301 \&  $progress\->done("Noted $count Pod files total");
 302 .Ve
 303 .Sp
 304 Internally, we often set this to an object of class
 305 Pod::Simple::Progress.  That class is probably undocumented,
 306 but you may wish to look at its source.
 307 .ie n .IP "$name2path = $self\->name2path;" 4
 308 .el .IP "$name2path = \f(CW$self\fR\->name2path;" 4
 309 .IX Item "$name2path = $self->name2path;"
 310 This attribute is not a search parameter, but is used to report the
 311 result of \f(CW\*(C`survey\*(C'\fR method, as discussed in the next section.
 312 .ie n .IP "$path2name = $self\->path2name;" 4
 313 .el .IP "$path2name = \f(CW$self\fR\->path2name;" 4
 314 .IX Item "$path2name = $self->path2name;"
 315 This attribute is not a search parameter, but is used to report the
 316 result of \f(CW\*(C`survey\*(C'\fR method, as discussed in the next section.
 317 .SH "MAIN SEARCH METHODS"
 318 .IX Header "MAIN SEARCH METHODS"
 319 Once you've actually set any options you want (if any), you can go
 320 ahead and use the following methods to search for Pod files
 321 in particular ways.
 322 .ie n .Sh """$search\->survey( @directories )"""
 323 .el .Sh "\f(CW$search\->survey( @directories )\fP"
 324 .IX Subsection "$search->survey( @directories )"
 325 The method \f(CW\*(C`survey\*(C'\fR searches for \s-1POD\s0 documents in a given set of
 326 files and/or directories.  This runs the search according to the various
 327 options set by the accessors above.  (For example, if the \f(CW\*(C`inc\*(C'\fR attribute
 328 is on, as it is by default, then the perl \f(CW@INC\fR directories are implicitly
 329 added to the list of directories (if any) that you specify.)
 330 .PP
 331 The return value of \f(CW\*(C`survey\*(C'\fR is two hashes:
 332 .ie n .IP """name2path""" 4
 333 .el .IP "\f(CWname2path\fR" 4
 334 .IX Item "name2path"
 335 A hash that maps from each pod-name to the filespec (like
 336 \&\*(L"Stuff::Thing\*(R" => \*(L"/whatever/plib/Stuff/Thing.pm\*(R")
 337 .ie n .IP """path2name""" 4
 338 .el .IP "\f(CWpath2name\fR" 4
 339 .IX Item "path2name"
 340 A hash that maps from each Pod filespec to its pod-name (like
 341 \&\*(L"/whatever/plib/Stuff/Thing.pm\*(R" => \*(L"Stuff::Thing\*(R")
 342 .PP
 343 Besides saving these hashes as the hashref attributes
 344 \&\f(CW\*(C`name2path\*(C'\fR and \f(CW\*(C`path2name\*(C'\fR, calling this function also returns
 345 these hashrefs.  In list context, the return value of
 346 \&\f(CW\*(C`$search\->survey\*(C'\fR is the list \f(CW\*(C`(\e%name2path, \e%path2name)\*(C'\fR.
 347 In scalar context, the return value is \f(CW\*(C`\e%name2path\*(C'\fR.
 348 Or you can just call this in void context.
 349 .PP
 350 Regardless of calling context, calling \f(CW\*(C`survey\*(C'\fR saves
 351 its results in its \f(CW\*(C`name2path\*(C'\fR and \f(CW\*(C`path2name\*(C'\fR attributes.
 352 .PP
 353 E.g., when searching in \fI$HOME/perl5lib\fR, the file
 354 \&\fI$HOME/perl5lib/MyModule.pm\fR would get the \s-1POD\s0 name \fIMyModule\fR,
 355 whereas \fI$HOME/perl5lib/Myclass/Subclass.pm\fR would be
 356 \&\fIMyclass::Subclass\fR. The name information can be used for \s-1POD\s0
 357 translators.
 358 .PP
 359 Only text files containing at least one valid \s-1POD\s0 command are found.
 360 .PP
 361 In verbose mode, a warning is printed if shadows are found (i.e., more
 362 than one \s-1POD\s0 file with the same \s-1POD\s0 name is found, e.g. \fI\s-1CPAN\s0.pm\fR in
 363 different directories).  This usually indicates duplicate occurrences of
 364 modules in the \fI@INC\fR search path, which is occasionally inadvertent
 365 (but is often simply a case of a user's path dir having a more recent
 366 version than the system's general path dirs in general.)
 367 .PP
 368 The options to this argument is a list of either directories that are
 369 searched recursively, or files.  (Usually you wouldn't specify files,
 370 but just dirs.)  Or you can just specify an empty\-list, as in
 371 \&\f(CW$name2path\fR; with the
 372 \&\f(CW\*(C`inc\*(C'\fR option on, as it is by default, teh
 373 .PP
 374 The \s-1POD\s0 names of files are the plain basenames with any Perl-like
 375 extension (.pm, .pl, .pod) stripped, and path separators replaced by
 376 \&\f(CW\*(C`::\*(C'\fR's.
 377 .PP
 378 Calling Pod::Simple::Search\->search(...) is short for
 379 Pod::Simple::Search\->new\->search(...).  That is, a throwaway object
 380 with default attribute values is used.
 381 .ie n .Sh """$search\->simplify_name( $str )"""
 382 .el .Sh "\f(CW$search\->simplify_name( $str )\fP"
 383 .IX Subsection "$search->simplify_name( $str )"
 384 The method \fBsimplify_name\fR is equivalent to \fBbasename\fR, but also
 385 strips Perl-like extensions (.pm, .pl, .pod) and extensions like
 386 \&\fI.bat\fR, \fI.cmd\fR on Win32 and \s-1OS/2\s0, or \fI.com\fR on \s-1VMS\s0, respectively.
 387 .ie n .Sh """$search\->find( $pod )"""
 388 .el .Sh "\f(CW$search\->find( $pod )\fP"
 389 .IX Subsection "$search->find( $pod )"
 390 .ie n .Sh """$search\->find( $pod, @search_dirs )"""
 391 .el .Sh "\f(CW$search\->find( $pod, @search_dirs )\fP"
 392 .IX Subsection "$search->find( $pod, @search_dirs )"
 393 Returns the location of a Pod file, given a Pod/module/script name
 394 (like \*(L"Foo::Bar\*(R" or \*(L"perlvar\*(R" or \*(L"perldoc\*(R"), and an idea of
 395 what files/directories to look in.
 396 It searches according to the various options set by the accessors above.
 397 (For example, if the \f(CW\*(C`inc\*(C'\fR attribute is on, as it is by default, then
 398 the perl \f(CW@INC\fR directories are implicitly added to the list of
 399 directories (if any) that you specify.)
 400 .PP
 401 This returns the full path of the first occurrence to the file.
 402 Package names (eg 'A::B') are automatically converted to directory
 403 names in the selected directory.  Additionally, '.pm', '.pl' and '.pod'
 404 are automatically appended to the search as required.
 405 (So, for example, under Unix, \*(L"A::B\*(R" is converted to \*(L"somedir/A/B.pm\*(R",
 406 \&\*(L"somedir/A/B.pod\*(R", or \*(L"somedir/A/B.pl\*(R", as appropriate.)
 407 .PP
 408 If no such Pod file is found, this method returns undef.
 409 .PP
 410 If any of the given search directories contains a \fIpod/\fR subdirectory,
 411 then it is searched.  (That's how we manage to find \fIperlfunc\fR,
 412 for example, which is usually in \fIpod/perlfunc\fR in most Perl dists.)
 413 .PP
 414 The \f(CW\*(C`verbose\*(C'\fR and \f(CW\*(C`inc\*(C'\fR attributes influence the behavior of this
 415 search; notably, \f(CW\*(C`inc\*(C'\fR, if true, adds \f(CW@INC\fR \fIand also
 416 \&\f(CI$Config::Config\fI{'scriptdir'}\fR to the list of directories to search.
 417 .PP
 418 It is common to simply say \f(CW\*(C`$filename = Pod::Simple::Search\-> new
 419 \&\->find("perlvar")\*(C'\fR so that just the \f(CW@INC\fR (well, and scriptdir)
 420 directories are searched.  (This happens because the \f(CW\*(C`inc\*(C'\fR
 421 attribute is true by default.)
 422 .PP
 423 Calling Pod::Simple::Search\->find(...) is short for
 424 Pod::Simple::Search\->new\->find(...).  That is, a throwaway object
 425 with default attribute values is used.
 426 .ie n .Sh """$self\->contains_pod( $file )"""
 427 .el .Sh "\f(CW$self\->contains_pod( $file )\fP"
 428 .IX Subsection "$self->contains_pod( $file )"
 429 Returns true if the supplied filename (not \s-1POD\s0 module) contains some Pod
 430 documentation.
 431 .SH "AUTHOR"
 432 .IX Header "AUTHOR"
 433 Sean M. Burke <sburke@cpan.org>
 434 borrowed code from
 435 Marek Rouchal's Pod::Find, which in turn
 436 heavily borrowed code from Nick Ing\-Simmons' PodToHtml.
 437 .PP
 438 Tim Jenness <t.jenness@jach.hawaii.edu> provided
 439 \&\f(CW\*(C`find\*(C'\fR and \f(CW\*(C`contains_pod\*(C'\fR to Pod::Find.
 440 .SH "SEE ALSO"
 441 .IX Header "SEE ALSO"
 442 Pod::Simple, Pod::Perldoc