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 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 autpmatically 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 = new PDL::Doc ('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)
254 The symhash is a multiply nested hash ref with the following structure:
256 $symhash = {
258 function_name => {
259 module::name => {
260 Module => 'module::name',
261 Sig => 'signature string',
262 Bad => 'bad documentation string',
263 ...
264 },
265 },
266 function_name => {
267 module::name => {
268 Module => 'module::name',
269 Sig => 'signature string',
270 Bad => 'bad documentation string',
271 ...
272 },
273 },
274 }
275 The three-layer structure is designed to allow the symhash (and the
277 underlying database) to handle functions that have the same name but
278 reside in different module namespaces.
279 The possible keys for each function/module entry include:
281 Module - module name
283 Sig - signature
284 Crossref - the function name for the documentation, if it has multiple
285 names (ex: the documentation for zeros is under zeroes)
286 Names - a comma-separated string of all the function's names
287 Example - example text (optional)
288 Ref - one-line reference string
289 Opt - options
290 Usage - short usage explanation
291 Bad - explanation of behavior when it encounters bad values
292 search
294 Search a PDL symhash
295 $onldc->search($regex, $fields [, $sort])
297 Searching is by default case insensitive. Other flags can be given by
299 specifying the regexp in the form "m/regex/ismx" where "/" can be
300 replaced with any other non-alphanumeric character. $fields is an array
301 reference for all hash fields (or simply a string if you only want to
302 search one field) that should be matched against the regex. Valid
303 fields are
304 Name, # name of the function
306 Module, # module the function belongs to
307 Ref, # the one-line reference description
308 Example, # the example for this function
309 Opt, # options
310 File, # the path to the source file these docs have been extracted from
311 If you wish to have your results sorted by function name, pass a true
313 value for $sort.
314 The results will be returned as an array of triplets in the form
316 @results = (
318 [funcname, module, {SYMHASH_ENTRY}],
319 [funcname, module, {SYMHASH_ENTRY}],
320 ...
321 );
322 See the example at the end of the documentation to see how you might
324 use this.
325 scan
327 Scan a source file using the PDL podparser to extract information for
328 online documentation
329 scantree
331 Scan whole directory trees for online documentation in ".pm" (module
332 definition) and "*.pod" (general documentation) files (using the
333 File::Find module).
334 funcdocs
336 extract the complete documentation about a function from its source
337 file using the PDL::PodParser filter.
338
340 add_module
341 use PDL::Doc; PDL::Doc::add_module("my::module");
342 The "add_module" function allows you to add POD from a particular Perl
344 module that you've installed somewhere in @INC. It searches for the
345 active PDL document database and the module's .pod and .pm files, and
346 scans and indexes the module into the database.
347 "add_module" is meant to be added to your module's Makefile as part of
349 the installation script.
350
352 Here's an example of how you might use the PDL Doc database in your own
353 code.
354 use PDL::Doc;
356 # Find the pdl documentation
357 my ($dir,$file,$pdldoc);
358 DIRECTORY: for $dir (@INC) {
359 $file = $dir."/PDL/pdldoc.db";
360 if (-f $file) {
361 print "Found docs database $file\n";
362 $pdldoc = new PDL::Doc ($file);
363 last DIRECTORY;
364 }
365 }
366 die ("Unable to find docs database!\n") unless $pdldoc;
368 # Print the reference line for zeroes:
370 print map{$_->{Ref}} values %{$pdldoc->gethash->{zeroes}};
371 # Or, if you remember that zeroes is in PDL::Core:
372 print $pdldoc->gethash->{zeroes}->{PDL::Core}->{Ref};
373 # Get info for all the functions whose examples use zeroes
375 my @entries = $pdldoc->search('zeroes','Example',1);
376 # All the functions that use zeroes in their example:
378 print "Functions that use 'zeroes' in their examples include:\n";
379 foreach my $entry (@entries) {
380 # Unpack the entry
381 my ($func_name, $module, $sym_hash) = @$entry;
382 print "$func_name\n";
383 }
384 print "\n";
385 #Or, more concisely:
387 print join("\n",map{$_->[0]}@entries);
388 # Let's look at the function 'mpdl'
390 @entries = $pdldoc->search('mpdl', 'Name');
391 # I know there's only one:
392 my $entry = $entries[0];
393 my ($func_name, undef, $sym_hash) = @$entry;
394 print "mpdl info:\n";
395 foreach my $key (sort keys %$sym_hash) {
396 # Unpack the entry
397 print "---$key---\n$sym_hash->{$key}\n";
398 }
399 Finding Modules
401 How can you tell if you've gotten a module for one of your entries?
402 The Ref entry will begin with 'Module:' if it's a module. In code:
403 # Prints:
405 # Module: fundamental PDL functionality and vectorization/broadcasting
406 print $pdldoc->gethash->{'PDL::Core'}->{'PDL::Core'}->{Ref}, "\n"
407
409 Quite a few shortcomings which will hopefully be fixed following
410 discussions on the pdl-devel mailing list.
411
413 Copyright 1997 Christian Soeller <c.soeller@auckland.ac.nz> and Karl
414 Glazebrook <kgb@aaoepp.aao.gov.au>
415 Further contributions copyright 2010 David Mertens
417 <dcmertens.perl@gmail.com>
418 Documentation database restructuring 2019 Derek Lamb
420 All rights reserved. There is no warranty. You are allowed to
422 redistribute this software / documentation under certain conditions.
423 For details, see the file COPYING in the PDL distribution. If this file
424 is separated from the PDL distribution, the copyright notice should be
425 included in the file.
426perl v5.36.0 2023-01-20 Doc(3)