Unix/Linux Go Back    

RedHat 9 (Linux i386) - man page for pdl::doc (redhat section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)

Doc(3)			       User Contributed Perl Documentation			   Doc(3)

       PDL::Doc - support for PDL online documentation

	 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 conven-
       tions 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 format-
       ting this documentation.

       The first convention says that all documentation for PDL functions appears in the POD sec-
       tion 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 distribu-
       tion 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))

	    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

	    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_BAD-
	    VAL} is set to 1). The intention is to have this information automatically created
	    for pp-compiled functions, although it can be over-ridden.

       The PDL podparser is implemented as a simple state machine. Any of the above "=for" state-
       ments switches the podparser into a state where the following paragraph is accepted as
       information for the respective field ("Ref", "Usage", "Opt", "Example" or "Bad").  Only
       the text up to the end of the current paragraph is accepted, for example:

	 =for example

		($x,$y) = $a->func(1,3);  # this is part of the accepted info
		$x = func($a,0,1);	  # this as well

		$x = func($a,$b);	  # but this isn't

       To make the resulting pod documentation also easily digestible for the existing pod fil-
       ters (pod2man, pod2text, pod2html, etc) the actual textblock of information must be sepa-
       rated from the "=for" directive by at least one blank line. Otherwise, the textblock will
       be lost in the translation process when the "normal" podformatters are used. The general
       idea behind this format is that it should be easy to extract the information for online
       documentation, automatic generation of a reference card, etc but at the same time the doc-
       umentation should be translated by the standard podformatters without loss of contents
       (and without requiring any changes in the existing POD format).

       The preceding explanations should be further explained by the following example (extracted
       from PDL/IO/Misc/misc.pd):

	  =head2 rcols()

	  =for ref

	  Read ASCII whitespaced cols from file into piddles efficiently.

	  If no columns are specified all are assumed
	  Will optionally only process lines matching a pattern.
	  Can take file name or *HANDLE.

	  =for usage

	   Usage: ($x,$y,...) = rcols(*HANDLE|"filename", ["/pattern/",$col1, $col2,] ...)


	  =for example

	    ($x,$y)    = rcols 'file1'
	    ($x,$y,$z) = rcols 'file2', "/foo/",3,4
	    $x = PDL->rcols 'file1';

	  Note: currently quotes are required on the pattern.

       which is translated by, e.g, the standard "pod2text" converter into:


	   Read ASCII whitespaced cols from file into piddles efficiently.

	   If no columns are specified all are assumed Will optionally only
	   process lines matching a pattern. Can take file name or *HANDLE.

	     Usage: ($x,$y,...) = rcols(*HANDLE|"filename", ["/pattern/",$col1, $col2,] ...)


	     ($x,$y)	= rcols 'file1'
	     ($x,$y,$z) = rcols 'file2', "/foo/",3,4
	     $x = PDL->rcols 'file1';

	   Note: currently quotes are required on the pattern.

       It should be clear from the preceding example that readable output can be obtained from
       this format using the standard converters and the reader will hopefully get a feeling how
       he can easily intersperse the special "=for" directives with the normal POD documentation.

       Which directives should be contained in the documentation

       The module documentation should start with the

	 =head1 NAME

	 PDL::Modulename -- do something with piddles

       section (as anyway required by "pod2man") since the PDL podparser extracts the name of the
       module this function belongs to from that section.

       Each function that is not only for internal use by the module should be documented, intro-
       duced with the "=head2" directive in the "=head1 FUNCTIONS" section. The only field that
       every function documented along these lines should have is the Ref field preceding a one
       line description of its intended functionality (suitable for inclusion in a concise refer-
       ence card). PP defined functions (see PDL::PP) should have a Sig field stating their sig-
       nature. To facilitate maintainance of this documentation for such functions the 'Doc'
       field has been introduced into the definition of "pp_def" (see again PDL::PP) which will
       take care that name and signature of the so defined function are documented in this way
       (for examples of this usage see, for example, the PDL::Slices module, especially slices.pd
       and the resulting Slices.pm). Similarly, the 'BadDoc' field provides a means of specifying
       information on how the routine handles the presence of bad values: this will be autpmati-
       cally created if "BadDoc" is not supplied, or set to "undef".

       Furthermore, the documentation for each function should contain at least one of the Usage
       or Examples fields. Depending on the calling conventions for the function under considera-
       tion presence of both fields may be warranted.

       If a function has options that should be given as a hash reference in the form

	  {Option => Value, ...}

       then the possible options (and aproppriate values) should be explained in the textblock
       following the "=for Opt" directive (see example above and, e.g., PDL::IO::Pic).

       It is well possible that some of these conventions appear to be clumsy at times and the
       author is keen to hear of any suggestions for better alternatives.


	 $onlinedc = new PDL::Doc ('file.pdl',[more files]);


       add another file to the online database associated with this object.


       set the name of the output file for this online db


       Make sure that the database is slurped in


       save the database (i.e., the hash of PDL symbols) to the file associated with this object.


       Return the PDL symhash (e.g. for custom search operations)


       Search a PDL symhash

	 $onldc->search($regex, $fields [, $sort])

       Searching is by default case insensitive. Other flags can be given by specifying the reg-
       exp in the form "m/regex/ismx" where "/" can be replaced with any other non-alphanumeric
       character. $fields is an array reference for all hash fields that should be matched
       against the regex. Valid fields are

	 Name,	  # name of the function
	 Module,  # module the function belongs to
	 Ref,	  # the one-line reference description
	 Example, # the example for this function
	 Opt,	  # options
	 File,	  # the path to the source file this docs have been extracted from


       Scan a source file using the PDL podparser to extract information for online documentation


       Scan whole directory trees for online documentation in ".pm" (module definition) and
       "*.pod" (general documentation) files (using the File::Find module).


       extract the complete documentation about a function from its
	 source file using the PDL::Pod::Parser filter.

       Quite a few shortcomings which will hopefully be fixed following discussions on the pdl-
       porters mailing list.

       Copyright 1997 Christian Soeller <c.soeller@auckland.ac.nz> and Karl Glazebrook
       <kgb@aaoepp.aao.gov.au> All rights reserved. There is no warranty. You are allowed to
       redistribute this software / documentation under certain conditions. For details, see the
       file COPYING in the PDL distribution. If this file is separated from the PDL distribution,
       the copyright notice should be included in the file.

perl v5.8.0				    2001-06-16					   Doc(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums

All times are GMT -4. The time now is 08:20 PM.