1Doc(3) User Contributed Perl Documentation Doc(3)
2
6 PDL::Doc - support for PDL online documentation
7
9 use PDL::Doc;
10 $onlinedc = PDL::Doc->new($docfile);
11 @match = $onlinedc->search('m/slice|clump/');
12
14 An implementation of online docs for PDL.
15
17 PDL::Doc's main use is in the "help" (synonym "?") and "apropos"
18 (synonym "??") commands in the perldl shell. PDL::Doc provides the
19 infrastrucure to index and access PDL's documentation through these
20 commands. There is also an API for direct access to the documentation
21 database (see below).
22 The PDL doc system is built on Perl's pod (Plain Old Documentation),
24 included inline with each module. The PDL core modules are
25 automatically indexed when PDL is built and installed, and there is
26 provision for indexing external modules as well.
27 To include your module's pod into the Perl::Doc index, you should
29 follow the documentation conventions below.
30
32 For a package like PDL that has a lot of functions it is very desirable
33 to have some form of online help to make it easy for users to remind
34 themselves of names, calling conventions and typical usage of the
35 multitude of functions at their disposal. To make it straightforward to
36 extract the relevant information from the POD documentation in source
37 files that make up the PDL distribution certain conventions have been
38 adopted in formatting this documentation.
39 The first convention says that all documentation for PDL functions
41 appears in the POD section introduced by one of the following:
42 =head1 FUNCTIONS
44 =head1 OPERATORS
45 =head1 METHODS
46 =head1 CONSTRUCTORS
47 If you're documenting an object-oriented interface to a class that your
49 module defines, you should use METHODS and CONSTRUCTORS as appropriate.
50 If you are simply adding functions to PDL, use FUNCTIONS and OPERATORS
51 as appropriate.
52 Individual functions or methods in these section are introduced by
54 =head2 funcname
56 where signature is the argumentlist for a PP defined function as
58 explained in PDL::PP. Generally, PDL documentation is in valid POD
59 format (see perlpod) but uses the "=for" directive in a special way.
60 The "=for" directive is used to flag to the PDL Pod parser that
61 information is following that will be used to generate online help.
62 The PDL Pod parser recognises the following "=for" directives:
64 Ref indicates that the one line reference for this function follows,
66 e.g.,
67 =for ref
69 Returns an ndarray of lags to parent.
71 Sig the signature for the current function follows, e.g.,
73 =for sig
75 Signature: (a(n), [o]b(), [t]tmp(n))
77 Usage
79 an indication of the possible calling conventions for the current
80 function, e.g.,
81 =for usage
83 wpic($pdl,$filename[,{ options... }])
85 Opt lists options for the current function, e.g.,
87 =for options
89 CONVERTER => 'ppmtogif', # explicitly specify pbm converter
91 FLAGS => '-interlaced -transparent 0', # flags for converter
92 IFORM => 'PGM', # explicitly specify intermediate format
93 XTRAFLAGS => '-imagename iris', # additional flags to defaultflags
94 FORMAT => 'PCX', # explicitly specify output image format
95 COLOR => 'bw', # specify color conversion
96 LUT => $lut, # use color table information
97 Example
99 gives examples of typical usage for the current function:
100 =for example
102 wpic $pdl, $file;
104 $im->wpic('web.gif',{LUT => $lut});
105 for (@images) {
106 $_->wpic($name[0],{CONVERTER => 'ppmtogif'})
107 }
108 Bad provides information on how the function handles bad values. The
110 documentation under this directive should indicate if this
111 function accepts ndarrays with bad values and under what
112 circumstances this function might return ndarrays with bad values.
113 The PDL podparser is implemented as a simple state machine. Any of the
115 above "=for" statements switches the podparser into a state where the
116 following paragraph is accepted as information for the respective field
117 ("Ref", "Usage", "Opt", "Example" or "Bad"). Only the text up to the
118 end of the current paragraph is accepted, for example:
119 =for example
121 ($x,$y) = $z->func(1,3); # this is part of the accepted info
123 $x = func($z,0,1); # this as well
124 $x = func($c,$d); # but this isn't
126 To make the resulting pod documentation also easily digestible for the
128 existing pod filters (pod2man, pod2text, pod2html, etc) the actual
129 textblock of information must be separated from the "=for" directive by
130 at least one blank line. Otherwise, the textblock will be lost in the
131 translation process when the "normal" podformatters are used. The
132 general idea behind this format is that it should be easy to extract
133 the information for online documentation, automatic generation of a
134 reference card, etc but at the same time the documentation should be
135 translated by the standard podformatters without loss of contents (and
136 without requiring any changes in the existing POD format).
137 The preceding explanations should be further explained by the following
139 example (extracted from PDL/IO/Misc/misc.pd):
140 =head2 rcols()
142 =for ref
144 Read ASCII whitespaced cols from file into ndarrays efficiently.
146 If no columns are specified all are assumed
148 Will optionally only process lines matching a pattern.
149 Can take file name or *HANDLE.
150 =for usage
152 Usage: ($x,$y,...) = rcols(*HANDLE|"filename", ["/pattern/",$col1, $col2,] ...)
154 e.g.,
156 =for example
158 ($x,$y) = rcols 'file1'
160 ($x,$y,$z) = rcols 'file2', "/foo/",3,4
161 $x = PDL->rcols 'file1';
162 Note: currently quotes are required on the pattern.
164 which is translated by, e.g, the standard "pod2text" converter into:
166 rcols()
168 Read ASCII whitespaced cols from file into ndarrays efficiently.
170 If no columns are specified all are assumed Will optionally only
172 process lines matching a pattern. Can take file name or *HANDLE.
173 Usage: ($x,$y,...) = rcols(*HANDLE|"filename", ["/pattern/",$col1, $col2,] ...)
175 e.g.,
177 ($x,$y) = rcols 'file1'
179 ($x,$y,$z) = rcols 'file2', "/foo/",3,4
180 $x = PDL->rcols 'file1';
181 Note: currently quotes are required on the pattern.
183 It should be clear from the preceding example that readable output can
185 be obtained from this format using the standard converters and the
186 reader will hopefully get a feeling how they can easily intersperse the
187 special "=for" directives with the normal POD documentation.
188 Which directives should be contained in the documentation
190 The module documentation should start with the
191 =head1 NAME
193 PDL::Modulename -- do something with ndarrays
195 section (as anyway required by "pod2man") since the PDL podparser
197 extracts the name of the module this function belongs to from that
198 section.
199 Each function that is not only for internal use by the module should be
201 documented, introduced with the "=head2" directive in the "=head1
202 FUNCTIONS" section. The only field that every function documented along
203 these lines should have is the Ref field preceding a one line
204 description of its intended functionality (suitable for inclusion in a
205 concise reference card). PP defined functions (see PDL::PP) should have
206 a Sig field stating their signature. To facilitate maintenance of this
207 documentation for such functions the 'Doc' field has been introduced
208 into the definition of "pp_def" (see again PDL::PP) which will take
209 care that name and signature of the so defined function are documented
210 in this way (for examples of this usage see, for example, the
211 PDL::Slices module, especially slices.pd and the resulting Slices.pm).
212 Similarly, the 'BadDoc' field provides a means of specifying
213 information on how the routine handles the presence of bad values: this
214 will be automatically created if "BadDoc" is not supplied, or set to
215 "undef".
216 Furthermore, the documentation for each function should contain at
218 least one of the Usage or Examples fields. Depending on the calling
219 conventions for the function under consideration presence of both
220 fields may be warranted.
221 If a function has options that should be given as a hash reference in
223 the form
224 {Option => Value, ...}
226 then the possible options (and aproppriate values) should be explained
228 in the textblock following the "=for Opt" directive (see example above
229 and, e.g., PDL::IO::Pic).
230 It is well possible that some of these conventions appear to be clumsy
232 at times and the author is keen to hear of any suggestions for better
233 alternatives.
234
236 new
237 $onlinedc = PDL::Doc->new('file.pdl',[more files]);
238 addfiles
240 add another file to the online database associated with this object.
241 outfile
243 set the name of the output file for this online db
244 ensuredb
246 Make sure that the database is slurped in
247 savedb
249 save the database (i.e., the hash of PDL symbols) to the file
250 associated with this object.
251 gethash
253 Return the PDL symhash (e.g. for custom search operations). To see what
254 it has stored in it in JSON format:
255 perl -MPDL::Doc -MJSON::PP -e \
257 'print encode_json +PDL::Doc->new(PDL::Doc::_find_inc([qw(PDL pdldoc.db)]))->gethash' |
258 json_pp -json_opt pretty,canonical
259 The symhash is a multiply nested hash ref with the following structure:
261 $symhash = {
263 function_name => {
264 module::name => {
265 Module => 'module::name',
266 Sig => 'signature string',
267 Bad => 'bad documentation string',
268 ...
269 },
270 },
271 function_name => {
272 module::name => {
273 Module => 'module::name',
274 Sig => 'signature string',
275 Bad => 'bad documentation string',
276 ...
277 },
278 },
279 }
280 The three-layer structure is designed to allow the symhash (and the
282 underlying database) to handle functions that have the same name but
283 reside in different module namespaces.
284 The possible keys for each function/module entry include:
286 Module - module name
288 Sig - signature
289 Crossref - the function name for the documentation, if it has multiple
290 names (ex: the documentation for zeros is under zeroes)
291 Names - a comma-separated string of all the function's names
292 Example - example text (optional)
293 Ref - one-line reference string
294 Opt - options
295 Usage - short usage explanation
296 Bad - explanation of behavior when it encounters bad values
297 search
299 Search a PDL symhash
300 $onldc->search($regex, $fields [, $sort])
302 Searching is by default case insensitive. Other flags can be given by
304 specifying the regexp in the form "m/regex/ismx" where "/" can be
305 replaced with any other non-alphanumeric character. $fields is an array
306 reference for all hash fields (or simply a string if you only want to
307 search one field) that should be matched against the regex. Valid
308 fields are
309 Name, # name of the function
311 Module, # module the function belongs to
312 Ref, # the one-line reference description
313 Example, # the example for this function
314 Opt, # options
315 File, # the path to the source file these docs have been extracted from
316 If you wish to have your results sorted by function name, pass a true
318 value for $sort.
319 The results will be returned as an array of triplets in the form
321 @results = (
323 [funcname, module, {SYMHASH_ENTRY}],
324 [funcname, module, {SYMHASH_ENTRY}],
325 ...
326 );
327 See the example at the end of the documentation to see how you might
329 use this.
330 scan
332 Scan a source file using the PDL podparser to extract information for
333 online documentation
334 scantree
336 Scan whole directory trees for online documentation in ".pm" (module
337 definition) and "*.pod" (general documentation) files (using the
338 File::Find module).
339 funcdocs
341 extract the complete documentation about a function from its source
342 file using the PDL::PodParser filter.
343
345 add_module
346 use PDL::Doc;
347 PDL::Doc::add_module("PDL::Stats"); # add PDL::Stats, PDL::Stats::GLM, ...
348 The "add_module" function allows you to add POD from a particular Perl
350 module (and as of PDL 2.083, in fact all modules starting with that as
351 a prefix) that you've installed somewhere in @INC. It searches for the
352 active PDL document database and the module's .pod and .pm files, and
353 scans and indexes the module(s) into the database.
354 "add_module" is meant to be added to your module's Makefile as part of
356 the installation script. This is done automatically by
357 "pdlpp_postamble" in PDL::Core::Dev, but if the top level of your
358 distribution is Perl modules (like PDL::LinearAlgebra), then add a
359 "postamble" manually in the Makefile.PL:
360 use PDL::Core::Dev;
362 sub MY::postamble {
363 my $oneliner = PDL::Core::Dev::_oneliner(qq{exit if \$ENV{DESTDIR}; use PDL::Doc; eval { PDL::Doc::add_module(shift); }});
364 qq|\ninstall :: pure_install\n\t$oneliner \$(NAME)\n|;
365 }
366
368 Here's an example of how you might use the PDL Doc database in your own
369 code.
370 use PDL::Doc;
372 # Find the pdl documentation
373 my ($file) = _find_inc([qw(PDL pdldoc.db)], 0);
374 die "Unable to find docs database!\n" unless defined $file;
375 print "Found docs database $file\n";
376 my $pdldoc = PDL::Doc->new($file);
377 # Print the reference line for zeroes:
378 print map{$_->{Ref}} values %{$pdldoc->gethash->{zeroes}};
379 # Or, if you remember that zeroes is in PDL::Core:
380 print $pdldoc->gethash->{zeroes}->{PDL::Core}->{Ref};
381 # Get info for all the functions whose examples use zeroes
383 my @entries = $pdldoc->search('zeroes','Example',1);
384 # All the functions that use zeroes in their example:
386 print "Functions that use 'zeroes' in their examples include:\n";
387 foreach my $entry (@entries) {
388 # Unpack the entry
389 my ($func_name, $module, $sym_hash) = @$entry;
390 print "$func_name\n";
391 }
392 print "\n";
393 #Or, more concisely:
395 print map "$_->[0]\n", @entries;
396 # Let's look at the function 'mpdl'
398 @entries = $pdldoc->search('mpdl', 'Name');
399 # I know there's only one:
400 my $entry = $entries[0];
401 my ($func_name, undef, $sym_hash) = @$entry;
402 print "mpdl info:\n";
403 foreach my $key (sort keys %$sym_hash) {
404 # Unpack the entry
405 print "---$key---\n$sym_hash->{$key}\n";
406 }
407 Finding Modules
409 How can you tell if you've gotten a module for one of your entries?
410 The Ref entry will begin with 'Module:' if it's a module. In code:
411 # Prints:
413 # Module: fundamental PDL functionality and vectorization/broadcasting
414 print $pdldoc->gethash->{'PDL::Core'}->{'PDL::Core'}->{Ref}, "\n"
415
417 Quite a few shortcomings which will hopefully be fixed following
418 discussions on the pdl-devel mailing list.
419
421 Copyright 1997 Christian Soeller <c.soeller@auckland.ac.nz> and Karl
422 Glazebrook <kgb@aaoepp.aao.gov.au>
423 Further contributions copyright 2010 David Mertens
425 <dcmertens.perl@gmail.com>
426 Documentation database restructuring 2019 Derek Lamb
428 All rights reserved. There is no warranty. You are allowed to
430 redistribute this software / documentation under certain conditions.
431 For details, see the file COPYING in the PDL distribution. If this file
432 is separated from the PDL distribution, the copyright notice should be
433 included in the file.
434perl v5.38.0 2023-07-21 Doc(3)