1Doc(3) User Contributed Perl Documentation Doc(3)
2
6 PDL::Doc - support for PDL online documentation
7
9 use PDL::Doc;
10 $onlinedc = new PDL::Doc ($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 the user to remind
34 himself of names, calling conventions and typical usage of the
35 multitude of functions at his 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 a piddle 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 (if
110 $PDL:Config{WITH_BADVAL} is set to 1). The documentation under
111 this directive should indicate if this function accepts piddles
112 with bad values and under what circumstances this function might
113 return piddles with bad values.
114 The PDL podparser is implemented as a simple state machine. Any of the
116 above "=for" statements switches the podparser into a state where the
117 following paragraph is accepted as information for the respective field
118 ("Ref", "Usage", "Opt", "Example" or "Bad"). Only the text up to the
119 end of the current paragraph is accepted, for example:
120 =for example
122 ($x,$y) = $z->func(1,3); # this is part of the accepted info
124 $x = func($z,0,1); # this as well
125 $x = func($c,$d); # but this isn't
127 To make the resulting pod documentation also easily digestible for the
129 existing pod filters (pod2man, pod2text, pod2html, etc) the actual
130 textblock of information must be separated from the "=for" directive by
131 at least one blank line. Otherwise, the textblock will be lost in the
132 translation process when the "normal" podformatters are used. The
133 general idea behind this format is that it should be easy to extract
134 the information for online documentation, automatic generation of a
135 reference card, etc but at the same time the documentation should be
136 translated by the standard podformatters without loss of contents (and
137 without requiring any changes in the existing POD format).
138 The preceding explanations should be further explained by the following
140 example (extracted from PDL/IO/Misc/misc.pd):
141 =head2 rcols()
143 =for ref
145 Read ASCII whitespaced cols from file into piddles efficiently.
147 If no columns are specified all are assumed
149 Will optionally only process lines matching a pattern.
150 Can take file name or *HANDLE.
151 =for usage
153 Usage: ($x,$y,...) = rcols(*HANDLE|"filename", ["/pattern/",$col1, $col2,] ...)
155 e.g.,
157 =for example
159 ($x,$y) = rcols 'file1'
161 ($x,$y,$z) = rcols 'file2', "/foo/",3,4
162 $x = PDL->rcols 'file1';
163 Note: currently quotes are required on the pattern.
165 which is translated by, e.g, the standard "pod2text" converter into:
167 rcols()
169 Read ASCII whitespaced cols from file into piddles efficiently.
171 If no columns are specified all are assumed Will optionally only
173 process lines matching a pattern. Can take file name or *HANDLE.
174 Usage: ($x,$y,...) = rcols(*HANDLE|"filename", ["/pattern/",$col1, $col2,] ...)
176 e.g.,
178 ($x,$y) = rcols 'file1'
180 ($x,$y,$z) = rcols 'file2', "/foo/",3,4
181 $x = PDL->rcols 'file1';
182 Note: currently quotes are required on the pattern.
184 It should be clear from the preceding example that readable output can
186 be obtained from this format using the standard converters and the
187 reader will hopefully get a feeling how he can easily intersperse the
188 special "=for" directives with the normal POD documentation.
189 Which directives should be contained in the documentation
191 The module documentation should start with the
192 =head1 NAME
194 PDL::Modulename -- do something with piddles
196 section (as anyway required by "pod2man") since the PDL podparser
198 extracts the name of the module this function belongs to from that
199 section.
200 Each function that is not only for internal use by the module should be
202 documented, introduced with the "=head2" directive in the "=head1
203 FUNCTIONS" section. The only field that every function documented along
204 these lines should have is the Ref field preceding a one line
205 description of its intended functionality (suitable for inclusion in a
206 concise reference card). PP defined functions (see PDL::PP) should have
207 a Sig field stating their signature. To facilitate maintenance of this
208 documentation for such functions the 'Doc' field has been introduced
209 into the definition of "pp_def" (see again PDL::PP) which will take
210 care that name and signature of the so defined function are documented
211 in this way (for examples of this usage see, for example, the
212 PDL::Slices module, especially slices.pd and the resulting Slices.pm).
213 Similarly, the 'BadDoc' field provides a means of specifying
214 information on how the routine handles the presence of bad values: this
215 will be autpmatically created if "BadDoc" is not supplied, or set to
216 "undef".
217 Furthermore, the documentation for each function should contain at
219 least one of the Usage or Examples fields. Depending on the calling
220 conventions for the function under consideration presence of both
221 fields may be warranted.
222 If a function has options that should be given as a hash reference in
224 the form
225 {Option => Value, ...}
227 then the possible options (and aproppriate values) should be explained
229 in the textblock following the "=for Opt" directive (see example above
230 and, e.g., PDL::IO::Pic).
231 It is well possible that some of these conventions appear to be clumsy
233 at times and the author is keen to hear of any suggestions for better
234 alternatives.
235
237 new
238 $onlinedc = new PDL::Doc ('file.pdl',[more files]);
239 addfiles
241 add another file to the online database associated with this object.
242 outfile
244 set the name of the output file for this online db
245 ensuredb
247 Make sure that the database is slurped in
248 savedb
250 save the database (i.e., the hash of PDL symbols) to the file
251 associated with this object.
252 gethash
254 Return the PDL symhash (e.g. for custom search operations)
255 The symhash is a multiply nested hash ref with the following structure:
257 $symhash = {
259 function_name => {
260 module::name => {
261 Module => 'module::name',
262 Sig => 'signature string',
263 Bad => 'bad documentation string',
264 ...
265 },
266 },
267 function_name => {
268 module::name => {
269 Module => 'module::name',
270 Sig => 'signature string',
271 Bad => 'bad documentation string',
272 ...
273 },
274 },
275 }
276 The three-layer structure is designed to allow the symhash (and the
278 underlying database) to handle functions that have the same name but
279 reside in different module namespaces.
280 The possible keys for each function/module entry include:
282 Module - module name
284 Sig - signature
285 Crossref - the function name for the documentation, if it has multiple
286 names (ex: the documentation for zeros is under zeroes)
287 Names - a comma-separated string of all the function's names
288 Example - example text (optional)
289 Ref - one-line reference string
290 Opt - options
291 Usage - short usage explanation
292 Bad - explanation of behavior when it encounters bad values
293 search
295 Search a PDL symhash
296 $onldc->search($regex, $fields [, $sort])
298 Searching is by default case insensitive. Other flags can be given by
300 specifying the regexp in the form "m/regex/ismx" where "/" can be
301 replaced with any other non-alphanumeric character. $fields is an array
302 reference for all hash fields (or simply a string if you only want to
303 search one field) that should be matched against the regex. Valid
304 fields are
305 Name, # name of the function
307 Module, # module the function belongs to
308 Ref, # the one-line reference description
309 Example, # the example for this function
310 Opt, # options
311 File, # the path to the source file these docs have been extracted from
312 If you wish to have your results sorted by function name, pass a true
314 value for $sort.
315 The results will be returned as an array of triplets in the form
317 @results = (
319 [funcname, module, {SYMHASH_ENTRY}],
320 [funcname, module, {SYMHASH_ENTRY}],
321 ...
322 );
323 See the example at the end of the documentation to see how you might
325 use this.
326 scan
328 Scan a source file using the PDL podparser to extract information for
329 online documentation
330 scantree
332 Scan whole directory trees for online documentation in ".pm" (module
333 definition) and "*.pod" (general documentation) files (using the
334 File::Find module).
335 funcdocs
337 extract the complete documentation about a function from its
338 source file using the PDL::Pod::Parser filter.
339
341 add_module
342 use PDL::Doc; PDL::Doc::add_module("my::module");
343 The "add_module" function allows you to add POD from a particular Perl
345 module that you've installed somewhere in @INC. It searches for the
346 active PDL document database and the module's .pod and .pm files, and
347 scans and indexes the module into the database.
348 "add_module" is meant to be added to your module's Makefile as part of
350 the installation script.
351
353 Here's an example of how you might use the PDL Doc database in your own
354 code.
355 use PDL::Doc;
357 # Find the pdl documentation
358 my ($dir,$file,$pdldoc);
359 DIRECTORY: for $dir (@INC) {
360 $file = $dir."/PDL/pdldoc.db";
361 if (-f $file) {
362 print "Found docs database $file\n";
363 $pdldoc = new PDL::Doc ($file);
364 last DIRECTORY;
365 }
366 }
367 die ("Unable to find docs database!\n") unless $pdldoc;
369 # Print the reference line for zeroes:
371 print map{$_->{Ref}} values %{$pdldoc->gethash->{zeroes}};
372 # Or, if you remember that zeroes is in PDL::Core:
373 print $pdldoc->gethash->{zeroes}->{PDL::Core}->{Ref};
374 # Get info for all the functions whose examples use zeroes
376 my @entries = $pdldoc->search('zeroes','Example',1);
377 # All the functions that use zeroes in their example:
379 print "Functions that use 'zeroes' in their examples include:\n";
380 foreach my $entry (@entries) {
381 # Unpack the entry
382 my ($func_name, $module, $sym_hash) = @$entry;
383 print "$func_name\n";
384 }
385 print "\n";
386 #Or, more concisely:
388 print join("\n",map{$_->[0]}@entries);
389 # Let's look at the function 'mpdl'
392 @entries = $pdldoc->search('mpdl', 'Name');
393 # I know there's only one:
394 my $entry = $entries[0];
395 my ($func_name, undef, $sym_hash) = @$entry;
396 print "mpdl info:\n";
397 foreach my $key (keys %$sym_hash) {
398 # Unpack the entry
399 print "---$key---\n$sym_hash->{$key}\n";
400 }
401 Finding Modules
403 How can you tell if you've gotten a module for one of your entries?
404 The Ref entry will begin with 'Module:' if it's a module. In code:
405 # Prints:
407 # Module: fundamental PDL functionality and vectorization/threading
408 print $pdldoc->gethash->{'PDL::Core'}->{'PDL::Core'}->{Ref}, "\n"
409
411 Quite a few shortcomings which will hopefully be fixed following
412 discussions on the pdl-devel mailing list.
413
415 Copyright 1997 Christian Soeller <c.soeller@auckland.ac.nz> and Karl
416 Glazebrook <kgb@aaoepp.aao.gov.au>
417 Further contributions copyright 2010 David Mertens
419 <dcmertens.perl@gmail.com>
420 Documentation database restructuring 2019 Derek Lamb
422 All rights reserved. There is no warranty. You are allowed to
424 redistribute this software / documentation under certain conditions.
425 For details, see the file COPYING in the PDL distribution. If this file
426 is separated from the PDL distribution, the copyright notice should be
427 included in the file.
428perl v5.32.0 2020-09-17 Doc(3)