This is a first try to get something like online help for PDL.
Building proceeds as usual:

  perl Makefile.PL
  make

Then there are a few things you should try:

1) Scan the current PDL distribution (PDL-1.94_05 + PATCHES)
   for online help info:

  perl -Mblib scantree.pl

and specify the location of your *installed* PDL distribution
(either the default or YOUR_PDL_DIR/blib/lib/PDL if you haven't
installed it) when asked to do so.

2) Try the online doc support from within perldl (in the root
directory of the PDL-Doc distribution):

   perldl

and at the perldl prompt, type 'help':

   perldl> help

and proceed from there.
For details check the supplied file 'local.perldlrc'.

3) If you want to see which info has been picked from your POD documentation
try

   perl -Mblib docscan <filename>

in the root directory of the PDL-Doc distribution.

4) Once you have built the online info database (see step 1)
try the example that builds a 'pdlfunc' manpage by saying:

   perl -Mblib mkpdlfuncpod >pdlfunc.pod

This is just a demonstration of what should become possible once the
online docs work correctly.

5) If you prefer the itemised listing of PDL functions in
the manpage version, try

   perl -Mblib pdlhead2item <filename.pm> > <tmpname.pod>
   pod2man <tmpname.pod> | nroff -man | more

that translates the <=head2> directives into an itemised list. This
is again just a demo what can be done.

For info about the POD format conventions used by the PDL podparser
to identify the online documentation check the docs in Doc.pm.

There are still quite a few shortcomings in the implementation:

1) the podparser code is currently a bit messy

2) scanning is done very naively. No real checks are made if a function
is documented in several files, etc. Needs to be done once integerated
with the PDL distrib.

3) Scanning and database updating should be integerated with the
build process. An updating policy should be developed.

4) The PP changes to support the new doc style are poorly documented,
for the moment refer to the examples supplied in the patches to
PDL-1.94_05. Briefly, the 'Doc' key has been introduced and PP will
generate the

  =head2 funcname

  =for sig

    Signature: (...)

entries automatically. No docs are generated if you say

   pp_def('XXXXfunc',
	  Doc => 'internal',...
   );

pp_addpm has been changed to optionally accept an option hash ref
to specify if the pm text should be inserted at the top, in the middle
or at the bottom. I'm not sure of this is necessary/a good solution yet.

6) If the symhash should grow beyond the point where it is practical
to hold it all in memory the implementation should use some kind
of cached AnyDBM inplementation.

7) and probably lots of other things...

  Christian Soeller <c.soeller@auckland.ac.nz>


Changes for intergration in to PDL distribution

- changed scantree.pl to take args for directory, database.
- moved local.perldlrc into PDL::Doc::Perldl module
- Made "borrowed" Pod:: stuff into PDL::Pod:: for now.

  Karl Glazebrook <kgb@aaoepp.aao.gov.au>