All,
As part of building the recent release candidates I have had to have a
look at the documentation, and it's a bit of a mess. I propose to tidy
it up.
So that the source distribution results in good PPMs with all the
documentation enclosed it is important that it is possible to run
pod2html on the blib directory tree to generate the html pages. As I
understand it this is exactly what make_ppm (see PPM::Make package from
CPAN) does.
So, I am proposing:
(1) to throw away docs/dodoc and docs/dohtml, replacing them with a
single tool in a new directory 'build_tools' called doPodDocs.pl that will
- parse the XS/PM/CPP files extracting the documentation, and building
the per-package POD documentation, and putting it in the correct
location under blib.
- copy any static POD content from the docs directory to the correct
location under blib
(2) to re-work the static content in the docs directory, as there is a
lot of duplicated content currently, as well as a lot of content that
really needs to be generated dynamically, but is not - more details below.
(3) re-work the format of every page to be more pod2html friendly, and
to get a better look with the ActiveState Perl CSS style sheet.
(3) add a target to Makefile.PL that will result in building the POD
documentation as part of the standard build process (nmake or nmake all).
(4) adding a target to the makefile to allow the html to be generated
(using pd2html)
(5) adding a target to the makefile to build a PPM distribution
I propose the following structure for the documentation:
Win32/GUI.pod - introductory page, very similar to current one.
Win32/GUI/*.pod - dynamically built documentation for each package
(except Win32::GUI)
Win32/GUI/UserGuide/Introduction.pod - introduction page
Win32/GUI/UserGuide/Concepts.pod - general concepts page
Win32/GUI/UserGuide/FAQ.pod - FAQ
Win32/GUI/Tutorial.pod - contents page for the
tutorials
Win32/GUI/Tutorial/PartN - page for each part of
the tutorial
Win32/GUI/Reference/Packages.pod - dynamically generated list of
packages
Win32/GUI/Reference/Methods.pod - common methods - dynamic
(documentation for Win32::GUI package)
Win32/GUI/Reference/Events.pod - common events - dynamic: all
events marked as APPLIES_TO:*
Win32/GUI/Reference/Options.pod - static documentation of the
common options
In the longer term even the static POD documents need some type of
simple templating to allow dates and version numbers to be updated
automatically.
I am starting work on this imminently, and would welcome feedback.
Regards,
Rob.
