Commit | Line | Data |
3fea05b9 |
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 |