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) = $a->func(1,3);  # this is part of the accepted info
124                $x = func($a,0,1);        # this as well
125
126                $x = func($a,$b);         # 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 with the following structure:
257
258        $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
273       The possible keys for each function include:
274
275        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
286   search
287       Search a PDL symhash
288
289         $onldc->search($regex, $fields [, $sort])
290
291       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
298         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
305       If you wish to have your results sorted by function name, pass a true
306       value for $sort.
307
308       The results will be returned as an array of pairs in the form
309
310        @results = (
311         [funcname, {SYMHASH_ENTRY}],
312         [funcname, {SYMHASH_ENTRY}],
313         ...
314        );
315
316       See the example at the end of the documentation to see how you might
317       use this.
318
319   scan
320       Scan a source file using the PDL podparser to extract information for
321       online documentation
322
323   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
328   funcdocs
329       extract the complete documentation about a function from its
330         source file using the PDL::Pod::Parser filter.
331

FUNCTIONS

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

PDL::DOC EXAMPLE

345       Here's an example of how you might use the PDL Doc database in your own
346       code.
347
348        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
360        die ("Unable to find docs database!\n") unless $pdldoc;
361
362        # Print the reference line for zeroes:
363        print $pdldoc->gethash->{zeroes}->{Ref};
364
365        # See which examples use zeroes
366        $pdldoc->search('zeroes', 'Example', 1);
367
368        # 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
377        print "\n";
378
379        # 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
390   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
394        # Prints:
395        #  Module: fundamental PDL functionality
396        my $sym_hash = $pdldoc->gethash;
397        print $pdldoc->gethash->{'PDL::Core'}->{Ref}, "\n"
398

BUGS

400       Quite a few shortcomings which will hopefully be fixed following
401       discussions on the pdl-devel mailing list.
402

AUTHOR

404       Copyright 1997 Christian Soeller <c.soeller@auckland.ac.nz> and Karl
405       Glazebrook <kgb@aaoepp.aao.gov.au>
406
407       Further contributions copyright 2010 David Mertens
408       <dcmertens.perl@gmail.com>
409
410       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.
415
416
417
418perl v5.28.0                      2018-05-05                            Doc(3)
Impressum