1
This is a first try to get something like online help for PDL.
2
Building proceeds as usual:
7
Then there are a few things you should try:
9
1) Scan the current PDL distribution (PDL-1.94_05 + PATCHES)
12
perl -Mblib scantree.pl
14
and specify the location of your *installed* PDL distribution
15
(either the default or YOUR_PDL_DIR/blib/lib/PDL if you haven't
16
installed it) when asked to do so.
18
2) Try the online doc support from within perldl (in the root
19
directory of the PDL-Doc distribution):
23
and at the perldl prompt, type 'help':
27
and proceed from there.
28
For details check the supplied file 'local.perldlrc'.
30
3) If you want to see which info has been picked from your POD documentation
33
perl -Mblib docscan <filename>
35
in the root directory of the PDL-Doc distribution.
37
4) Once you have built the online info database (see step 1)
38
try the example that builds a 'pdlfunc' manpage by saying:
40
perl -Mblib mkpdlfuncpod >pdlfunc.pod
42
This is just a demonstration of what should become possible once the
43
online docs work correctly.
45
5) If you prefer the itemised listing of PDL functions in
46
the manpage version, try
48
perl -Mblib pdlhead2item <filename.pm> > <tmpname.pod>
49
pod2man <tmpname.pod> | nroff -man | more
51
that translates the <=head2> directives into an itemised list. This
52
is again just a demo what can be done.
54
For info about the POD format conventions used by the PDL podparser
55
to identify the online documentation check the docs in Doc.pm.
57
There are still quite a few shortcomings in the implementation:
59
1) the podparser code is currently a bit messy
61
2) scanning is done very naively. No real checks are made if a function
62
is documented in several files, etc. Needs to be done once integerated
65
3) Scanning and database updating should be integerated with the
66
build process. An updating policy should be developed.
68
4) The PP changes to support the new doc style are poorly documented,
69
for the moment refer to the examples supplied in the patches to
70
PDL-1.94_05. Briefly, the 'Doc' key has been introduced and PP will
79
entries automatically. No docs are generated if you say
85
pp_addpm has been changed to optionally accept an option hash ref
86
to specify if the pm text should be inserted at the top, in the middle
87
or at the bottom. I'm not sure of this is necessary/a good solution yet.
89
6) If the symhash should grow beyond the point where it is practical
90
to hold it all in memory the implementation should use some kind
91
of cached AnyDBM inplementation.
93
7) and probably lots of other things...
95
Christian Soeller <c.soeller@auckland.ac.nz>
98
Changes for intergration in to PDL distribution
100
- changed scantree.pl to take args for directory, database.
101
- moved local.perldlrc into PDL::Doc::Perldl module
102
- Made "borrowed" Pod:: stuff into PDL::Pod:: for now.
104
Karl Glazebrook <kgb@aaoepp.aao.gov.au>
added
removed
Doc/README
