PDL::Doc 2.3.2

PDL::Doc provides support for PDL online documentation.

SYNOPSIS

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

An implementation of online docs for PDL.

PDL documentation conventions

For a package like PDL that has a lot of functions it is very desirable to have some form of online help to make it easy for the user to remind himself of names, calling conventions and typical usage of the multitude of functions at his disposal. To make it straightforward to extract the relevant information from the POD documentation in source files that make up the PDL distribution certain conventions have been adopted in formatting this documentation.

The first convention says that all documentation for PDL functions appears in the POD section introduced by

=head1 FUNCTIONS

Individual functions in this section are introduced by

=head2 funcname

where signature is the argumentlist for a PP defined function as explained in PDL::PP. Generally, PDL documentation is in valid POD format (see perlpod) but uses the =for directive in a special way. The =for directive is used to flag to the PDL Pod parser that information is following that will be used to generate online help.

The PDL podparser is derived from the PDL::Pod::Parser class that had to be patched in a few places, partly to fix minor bugs, partly to enhance functionality for perusal by PDL::Doc. Since the PDL::Doc module is still experimental the patched Pod-Parser distribution is included with the current PDL-Doc distribution. Note that PDL::Doc will not work correctly with the released Pod-Parser distribution.

The PDL Pod parser recognises the following =for directives:

Ref

indicates that the one line reference for this function follows, e.g.,

=for ref

Returns a piddle of lags to parent.

Sig

the signature for the current function follows, e.g.,

=for sig

Signature: (a(n), [o]b(), [t]tmp(n))

Usage:

an indication of the possible calling conventions for the current function, e.g.,

=for usage

wpic($pdl,$filename[,{ options... }])

Opt

lists options for the current function, e.g.,

=for options

CONVERTER => 'ppmtogif', # explicitly specify pbm converter
FLAGS => '-interlaced -transparent 0', # flags for converter
IFORM => 'PGM', # explicitly specify intermediate format
XTRAFLAGS => '-imagename iris', # additional flags to defaultflags
FORMAT => 'PCX', # explicitly specify output image format
COLOR => 'bw', # specify color conversion
LUT => $lut, # use color table information

Example:

gives examples of typical usage for the current function:

=for example

wpic $pdl, $file;
$im->wpic('web.gif',{LUT => $lut});
for (@images) {
$_->wpic($name[0],{CONVERTER => 'ppmtogif'})
}

Bad

provides information on how the function handles bad values (if $PDL:Config{WITH_BADVAL} is set to 1). The intention is to have this information automatically created for pp-compiled functions, although it can be over-ridden.

Requirements:

�· Perl



Product's homepage