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 an ndarray 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. 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
114       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
120         =for example
121
122                ($x,$y) = $z->func(1,3);  # this is part of the accepted info
123                $x = func($z,0,1);        # this as well
124
125                $x = func($c,$d);         # but this isn't
126
127       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
138       The preceding explanations should be further explained by the following
139       example (extracted from PDL/IO/Misc/misc.pd):
140
141          =head2 rcols()
142
143          =for ref
144
145          Read ASCII whitespaced cols from file into ndarrays efficiently.
146
147          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
151          =for usage
152
153           Usage: ($x,$y,...) = rcols(*HANDLE|"filename", ["/pattern/",$col1, $col2,] ...)
154
155          e.g.,
156
157          =for example
158
159            ($x,$y)    = rcols 'file1'
160            ($x,$y,$z) = rcols 'file2', "/foo/",3,4
161            $x = PDL->rcols 'file1';
162
163          Note: currently quotes are required on the pattern.
164
165       which is translated by, e.g, the standard "pod2text" converter into:
166
167         rcols()
168
169           Read ASCII whitespaced cols from file into ndarrays efficiently.
170
171           If no columns are specified all are assumed Will optionally only
172           process lines matching a pattern. Can take file name or *HANDLE.
173
174             Usage: ($x,$y,...) = rcols(*HANDLE|"filename", ["/pattern/",$col1, $col2,] ...)
175
176           e.g.,
177
178             ($x,$y)    = rcols 'file1'
179             ($x,$y,$z) = rcols 'file2', "/foo/",3,4
180             $x = PDL->rcols 'file1';
181
182           Note: currently quotes are required on the pattern.
183
184       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 he can easily intersperse the
187       special "=for" directives with the normal POD documentation.
188
189   Which directives should be contained in the documentation
190       The module documentation should start with the
191
192         =head1 NAME
193
194         PDL::Modulename -- do something with ndarrays
195
196       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
200       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
217       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
222       If a function has options that should be given as a hash reference in
223       the form
224
225          {Option => Value, ...}
226
227       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
231       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

INSTANCE METHODS

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

FUNCTIONS

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

PDL::DOC EXAMPLE

352       Here's an example of how you might use the PDL Doc database in your own
353       code.
354
355        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
367        die ("Unable to find docs database!\n") unless $pdldoc;
368
369        # 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
374        # Get info for all the functions whose examples use zeroes
375        my @entries = $pdldoc->search('zeroes','Example',1);
376
377        # 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
386        #Or, more concisely:
387        print join("\n",map{$_->[0]}@entries);
388
389
390        # Let's look at the function 'mpdl'
391        @entries = $pdldoc->search('mpdl', 'Name');
392        # I know there's only one:
393        my $entry = $entries[0];
394        my ($func_name, undef, $sym_hash) = @$entry;
395        print "mpdl info:\n";
396        foreach my $key (keys %$sym_hash) {
397            # Unpack the entry
398            print "---$key---\n$sym_hash->{$key}\n";
399        }
400
401   Finding Modules
402       How can you tell if you've gotten a module for one of your entries?
403       The Ref entry will begin with 'Module:' if it's a module. In code:
404
405        # Prints:
406        #  Module: fundamental PDL functionality and vectorization/threading
407        print $pdldoc->gethash->{'PDL::Core'}->{'PDL::Core'}->{Ref}, "\n"
408

BUGS

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

AUTHOR

414       Copyright 1997 Christian Soeller <c.soeller@auckland.ac.nz> and Karl
415       Glazebrook <kgb@aaoepp.aao.gov.au>
416
417       Further contributions copyright 2010 David Mertens
418       <dcmertens.perl@gmail.com>
419
420       Documentation database restructuring 2019 Derek Lamb
421
422       All rights reserved. There is no warranty. You are allowed to
423       redistribute this software / documentation under certain conditions.
424       For details, see the file COPYING in the PDL distribution. If this file
425       is separated from the PDL distribution, the copyright notice should be
426       included in the file.
427
428
429
430perl v5.34.0                      2021-08-16                            Doc(3)
Impressum