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) = $a->func(1,3); # this is part of the accepted info
124 $x = func($a,0,1); # this as well
125 $x = func($a,$b); # 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 with the following structure:
257 $symhash = {
259 function_name => {
260 Module => 'module::name',
261 Sig => 'signature string',
262 Bad => 'bad documentation string',
263 ...
264 },
265 function_name => {
266 Module => 'module::name',
267 Sig => 'signature string',
268 Bad => 'bad documentation string',
269 ...
270 },
271 };
272 The possible keys for each function include:
274 Module - module name
276 Sig - signature
277 Crossref - the function name for the documentation, if it has multiple
278 names (ex: the documentation for zeros is under zeroes)
279 Names - a comma-separated string of the all the function's names
280 Example - example text (optional)
281 Ref - one-line reference string
282 Opt - options
283 Usage - short usage explanation
284 Bad - explanation of behavior when it encounters bad values
285 search
287 Search a PDL symhash
288 $onldc->search($regex, $fields [, $sort])
290 Searching is by default case insensitive. Other flags can be given by
292 specifying the regexp in the form "m/regex/ismx" where "/" can be
293 replaced with any other non-alphanumeric character. $fields is an array
294 reference for all hash fields (or simply a string if you only want to
295 search one field) that should be matched against the regex. Valid
296 fields are
297 Name, # name of the function
299 Module, # module the function belongs to
300 Ref, # the one-line reference description
301 Example, # the example for this function
302 Opt, # options
303 File, # the path to the source file these docs have been extracted from
304 If you wish to have your results sorted by function name, pass a true
306 value for $sort.
307 The results will be returned as an array of pairs in the form
309 @results = (
311 [funcname, {SYMHASH_ENTRY}],
312 [funcname, {SYMHASH_ENTRY}],
313 ...
314 );
315 See the example at the end of the documentation to see how you might
317 use this.
318 scan
320 Scan a source file using the PDL podparser to extract information for
321 online documentation
322 scantree
324 Scan whole directory trees for online documentation in ".pm" (module
325 definition) and "*.pod" (general documentation) files (using the
326 File::Find module).
327 funcdocs
329 extract the complete documentation about a function from its
330 source file using the PDL::Pod::Parser filter.
331
333 add_module
334 use PDL::Doc; PDL::Doc::add_module("my::module");
335 The "add_module" function allows you to add POD from a particular Perl
337 module that you've installed somewhere in @INC. It searches for the
338 active PDL document database and the module's .pod and .pm files, and
339 scans and indexes the module into the database.
340 "add_module" is meant to be added to your module's Makefile as part of
342 the installation script.
343
345 Here's an example of how you might use the PDL Doc database in your own
346 code.
347 use PDL::Doc;
349 # Find the pdl documentation
350 my ($dir,$file,$pdldoc);
351 DIRECTORY: for $dir (@INC) {
352 $file = $dir."/PDL/pdldoc.db";
353 if (-f $file) {
354 print "Found docs database $file\n";
355 $pdldoc = new PDL::Doc ($file);
356 last DIRECTORY;
357 }
358 }
359 die ("Unable to find docs database!\n") unless $pdldoc;
361 # Print the reference line for zeroes:
363 print $pdldoc->gethash->{zeroes}->{Ref};
364 # See which examples use zeroes
366 $pdldoc->search('zeroes', 'Example', 1);
367 # All the functions that use zeroes in their example:
369 my @entries = $pdldoc->search('zeroes', 'Example', 1);
370 print "Functions that use 'zeroes' in their examples include:\n";
371 foreach my $entry (@entries) {
372 # Unpack the entry
373 my ($func_name, $sym_hash) = @$entry;
374 print "$func_name\n";
375 }
376 print "\n";
378 # Let's look at the function 'mpdl'
380 @entries = $pdldoc->search('mpdl', 'Name');
381 # I know there's only one:
382 my $entry = $entries[0];
383 my ($func_name, $sym_hash) = @$entry;
384 print "mpdl info:\n";
385 foreach my $key (keys %$sym_hash) {
386 # Unpack the entry
387 print "---$key---\n$sym_hash->{$key}\n";
388 }
389 Finding Modules
391 How can you tell if you've gotten a module for one of your entries?
392 The Ref entry will begin with 'Module:' if it's a module. In code:
393 # Prints:
395 # Module: fundamental PDL functionality
396 my $sym_hash = $pdldoc->gethash;
397 print $pdldoc->gethash->{'PDL::Core'}->{Ref}, "\n"
398
400 Quite a few shortcomings which will hopefully be fixed following
401 discussions on the pdl-devel mailing list.
402
404 Copyright 1997 Christian Soeller <c.soeller@auckland.ac.nz> and Karl
405 Glazebrook <kgb@aaoepp.aao.gov.au>
406 Further contributions copyright 2010 David Mertens
408 <dcmertens.perl@gmail.com>
409 All rights reserved. There is no warranty. You are allowed to
411 redistribute this software / documentation under certain conditions.
412 For details, see the file COPYING in the PDL distribution. If this file
413 is separated from the PDL distribution, the copyright notice should be
414 included in the file.
415perl v5.30.0 2019-09-05 Doc(3)