1Doc(3)                User Contributed Perl Documentation               Doc(3)
2
3
4

NAME

6       PDL::Doc - support for PDL online documentation
7

SYNOPSIS

9         use PDL::Doc;
10         $onlinedc = new PDL::Doc ($docfile);
11         @match = $onlinedc->search('m/slice|clump/');
12

DESCRIPTION

14       An implementation of online docs for PDL.
15

Using PDL documentation

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
23       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
28       To include your module's pod into the Perl::Doc index, you should
29       follow the documentation conventions below.
30

PDL documentation conventions

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
40       The first convention says that all documentation for PDL functions
41       appears in the POD section introduced by one of the following:
42
43         =head1 FUNCTIONS
44         =head1 OPERATORS
45         =head1 METHODS
46         =head1 CONSTRUCTORS
47
48       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
53       Individual functions or methods in these section are introduced by
54
55         =head2 funcname
56
57       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
63       The PDL Pod parser recognises the following "=for" directives:
64
65       Ref  indicates that the one line reference for this function follows,
66            e.g.,
67
68               =for ref
69
70               Returns a piddle of lags to parent.
71
72       Sig  the signature for the current function follows, e.g.,
73
74               =for sig
75
76                  Signature: (a(n), [o]b(), [t]tmp(n))
77
78       Usage
79            an indication of the possible calling conventions for the current
80            function, e.g.,
81
82               =for usage
83
84                  wpic($pdl,$filename[,{ options... }])
85
86       Opt  lists options for the current function, e.g.,
87
88               =for options
89
90                  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
98       Example
99            gives examples of typical usage for the current function:
100
101               =for example
102
103                   wpic $pdl, $file;
104                   $im->wpic('web.gif',{LUT => $lut});
105                   for (@images) {
106                     $_->wpic($name[0],{CONVERTER => 'ppmtogif'})
107                   }
108
109       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
115       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
121         =for example
122
123                ($x,$y) = $z->func(1,3);  # this is part of the accepted info
124                $x = func($z,0,1);        # this as well
125
126                $x = func($c,$d);         # but this isn't
127
128       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
139       The preceding explanations should be further explained by the following
140       example (extracted from PDL/IO/Misc/misc.pd):
141
142          =head2 rcols()
143
144          =for ref
145
146          Read ASCII whitespaced cols from file into piddles efficiently.
147
148          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
152          =for usage
153
154           Usage: ($x,$y,...) = rcols(*HANDLE|"filename", ["/pattern/",$col1, $col2,] ...)
155
156          e.g.,
157
158          =for example
159
160            ($x,$y)    = rcols 'file1'
161            ($x,$y,$z) = rcols 'file2', "/foo/",3,4
162            $x = PDL->rcols 'file1';
163
164          Note: currently quotes are required on the pattern.
165
166       which is translated by, e.g, the standard "pod2text" converter into:
167
168         rcols()
169
170           Read ASCII whitespaced cols from file into piddles efficiently.
171
172           If no columns are specified all are assumed Will optionally only
173           process lines matching a pattern. Can take file name or *HANDLE.
174
175             Usage: ($x,$y,...) = rcols(*HANDLE|"filename", ["/pattern/",$col1, $col2,] ...)
176
177           e.g.,
178
179             ($x,$y)    = rcols 'file1'
180             ($x,$y,$z) = rcols 'file2', "/foo/",3,4
181             $x = PDL->rcols 'file1';
182
183           Note: currently quotes are required on the pattern.
184
185       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
190   Which directives should be contained in the documentation
191       The module documentation should start with the
192
193         =head1 NAME
194
195         PDL::Modulename -- do something with piddles
196
197       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
201       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
218       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
223       If a function has options that should be given as a hash reference in
224       the form
225
226          {Option => Value, ...}
227
228       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
232       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

INSTANCE METHODS

237   new
238         $onlinedc = new PDL::Doc ('file.pdl',[more files]);
239
240   addfiles
241       add another file to the online database associated with this object.
242
243   outfile
244       set the name of the output file for this online db
245
246   ensuredb
247       Make sure that the database is slurped in
248
249   savedb
250       save the database (i.e., the hash of PDL symbols) to the file
251       associated with this object.
252
253   gethash
254       Return the PDL symhash (e.g. for custom search operations)
255
256       The symhash is a multiply nested hash ref with the following structure:
257
258        $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
277       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
281       The possible keys for each function/module entry include:
282
283        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
294   search
295       Search a PDL symhash
296
297         $onldc->search($regex, $fields [, $sort])
298
299       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
306         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
313       If you wish to have your results sorted by function name, pass a true
314       value for $sort.
315
316       The results will be returned as an array of triplets in the form
317
318        @results = (
319         [funcname, module, {SYMHASH_ENTRY}],
320         [funcname, module, {SYMHASH_ENTRY}],
321         ...
322        );
323
324       See the example at the end of the documentation to see how you might
325       use this.
326
327   scan
328       Scan a source file using the PDL podparser to extract information for
329       online documentation
330
331   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
336   funcdocs
337       extract the complete documentation about a function from its
338         source file using the PDL::Pod::Parser filter.
339

FUNCTIONS

341   add_module
342        use PDL::Doc; PDL::Doc::add_module("my::module");
343
344       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
349       "add_module" is meant to be added to your module's Makefile as part of
350       the installation script.
351

PDL::DOC EXAMPLE

353       Here's an example of how you might use the PDL Doc database in your own
354       code.
355
356        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
368        die ("Unable to find docs database!\n") unless $pdldoc;
369
370        # 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
375        # Get info for all the functions whose examples use zeroes
376        my @entries = $pdldoc->search('zeroes','Example',1);
377
378        # 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
387        #Or, more concisely:
388        print join("\n",map{$_->[0]}@entries);
389
390
391        # 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
402   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
406        # Prints:
407        #  Module: fundamental PDL functionality and vectorization/threading
408        print $pdldoc->gethash->{'PDL::Core'}->{'PDL::Core'}->{Ref}, "\n"
409

BUGS

411       Quite a few shortcomings which will hopefully be fixed following
412       discussions on the pdl-devel mailing list.
413

AUTHOR

415       Copyright 1997 Christian Soeller <c.soeller@auckland.ac.nz> and Karl
416       Glazebrook <kgb@aaoepp.aao.gov.au>
417
418       Further contributions copyright 2010 David Mertens
419       <dcmertens.perl@gmail.com>
420
421       Documentation database restructuring 2019 Derek Lamb
422
423       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.
428
429
430
431perl v5.30.2                      2020-04-02                            Doc(3)
Impressum