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 = PDL::Doc->new($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 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
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 they 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 automatically 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 = PDL::Doc->new('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). To see what
254       it has stored in it in JSON format:
255
256         perl -MPDL::Doc -MJSON::PP -e \
257           'print encode_json +PDL::Doc->new(PDL::Doc::_find_inc([qw(PDL pdldoc.db)]))->gethash' |
258           json_pp -json_opt pretty,canonical
259
260       The symhash is a multiply nested hash ref with the following structure:
261
262        $symhash = {
263            function_name => {
264                    module::name => {
265                         Module => 'module::name',
266                         Sig    => 'signature string',
267                         Bad    => 'bad documentation string',
268                         ...
269                         },
270                    },
271            function_name => {
272                    module::name => {
273                         Module => 'module::name',
274                         Sig    => 'signature string',
275                         Bad    => 'bad documentation string',
276                         ...
277                         },
278                    },
279        }
280
281       The three-layer structure is designed to allow the symhash (and the
282       underlying database) to handle functions that have the same name but
283       reside in different module namespaces.
284
285       The possible keys for each function/module entry include:
286
287        Module   - module name
288        Sig      - signature
289        Crossref - the function name for the documentation, if it has multiple
290                   names (ex: the documentation for zeros is under zeroes)
291        Names    - a comma-separated string of all the function's names
292        Example  - example text (optional)
293        Ref      - one-line reference string
294        Opt      - options
295        Usage    - short usage explanation
296        Bad      - explanation of behavior when it encounters bad values
297
298   search
299       Search a PDL symhash
300
301         $onldc->search($regex, $fields [, $sort])
302
303       Searching is by default case insensitive. Other flags can be given by
304       specifying the regexp in the form "m/regex/ismx" where "/" can be
305       replaced with any other non-alphanumeric character. $fields is an array
306       reference for all hash fields (or simply a string if you only want to
307       search one field) that should be matched against the regex. Valid
308       fields are
309
310         Name,    # name of the function
311         Module,  # module the function belongs to
312         Ref,     # the one-line reference description
313         Example, # the example for this function
314         Opt,     # options
315         File,    # the path to the source file these docs have been extracted from
316
317       If you wish to have your results sorted by function name, pass a true
318       value for $sort.
319
320       The results will be returned as an array of triplets in the form
321
322        @results = (
323         [funcname, module, {SYMHASH_ENTRY}],
324         [funcname, module, {SYMHASH_ENTRY}],
325         ...
326        );
327
328       See the example at the end of the documentation to see how you might
329       use this.
330
331   scan
332       Scan a source file using the PDL podparser to extract information for
333       online documentation
334
335   scantree
336       Scan whole directory trees for online documentation in ".pm" (module
337       definition) and "*.pod" (general documentation) files (using the
338       File::Find module).
339
340   funcdocs
341       extract the complete documentation about a function from its source
342       file using the PDL::PodParser filter.
343

FUNCTIONS

345   add_module
346        use PDL::Doc;
347        PDL::Doc::add_module("PDL::Stats"); # add PDL::Stats, PDL::Stats::GLM, ...
348
349       The "add_module" function allows you to add POD from a particular Perl
350       module (and as of PDL 2.083, in fact all modules starting with that as
351       a prefix) that you've installed somewhere in @INC. It searches for the
352       active PDL document database and the module's .pod and .pm files, and
353       scans and indexes the module(s) into the database.
354
355       "add_module" is meant to be added to your module's Makefile as part of
356       the installation script. This is done automatically by
357       "pdlpp_postamble" in PDL::Core::Dev, but if the top level of your
358       distribution is Perl modules (like PDL::LinearAlgebra), then add a
359       "postamble" manually in the Makefile.PL:
360
361         use PDL::Core::Dev;
362         sub MY::postamble {
363           my $oneliner = PDL::Core::Dev::_oneliner(qq{exit if \$ENV{DESTDIR}; use PDL::Doc; eval { PDL::Doc::add_module(shift); }});
364           qq|\ninstall :: pure_install\n\t$oneliner \$(NAME)\n|;
365         }
366

PDL::DOC EXAMPLE

368       Here's an example of how you might use the PDL Doc database in your own
369       code.
370
371        use PDL::Doc;
372        # Find the pdl documentation
373        my ($file) = _find_inc([qw(PDL pdldoc.db)], 0);
374        die "Unable to find docs database!\n" unless defined $file;
375        print "Found docs database $file\n";
376        my $pdldoc = PDL::Doc->new($file);
377        # Print the reference line for zeroes:
378        print map{$_->{Ref}} values %{$pdldoc->gethash->{zeroes}};
379        # Or, if you remember that zeroes is in PDL::Core:
380        print $pdldoc->gethash->{zeroes}->{PDL::Core}->{Ref};
381
382        # Get info for all the functions whose examples use zeroes
383        my @entries = $pdldoc->search('zeroes','Example',1);
384
385        # All the functions that use zeroes in their example:
386        print "Functions that use 'zeroes' in their examples include:\n";
387        foreach my $entry (@entries) {
388            # Unpack the entry
389            my ($func_name, $module, $sym_hash) = @$entry;
390            print "$func_name\n";
391        }
392        print "\n";
393
394        #Or, more concisely:
395        print map "$_->[0]\n", @entries;
396
397        # Let's look at the function 'mpdl'
398        @entries = $pdldoc->search('mpdl', 'Name');
399        # I know there's only one:
400        my $entry = $entries[0];
401        my ($func_name, undef, $sym_hash) = @$entry;
402        print "mpdl info:\n";
403        foreach my $key (sort keys %$sym_hash) {
404            # Unpack the entry
405            print "---$key---\n$sym_hash->{$key}\n";
406        }
407
408   Finding Modules
409       How can you tell if you've gotten a module for one of your entries?
410       The Ref entry will begin with 'Module:' if it's a module. In code:
411
412        # Prints:
413        #  Module: fundamental PDL functionality and vectorization/broadcasting
414        print $pdldoc->gethash->{'PDL::Core'}->{'PDL::Core'}->{Ref}, "\n"
415

BUGS

417       Quite a few shortcomings which will hopefully be fixed following
418       discussions on the pdl-devel mailing list.
419

AUTHOR

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