OK, I have just committed a large set of changes to the documentation.
Hope it looks good to you all. I don't think that I've lost any of the
original content, but I think it is now a little better organised. I
also added some targets to the makefile (and some related scripts) to
generate all the docs for you:
make - (or make all) now generates the POD documentation in the blib/lib
directories, as well as performing the build.
make poddocs - makes the POD documentation in the blib/lib directories
make htmldocs - converts the pod to html in the blib/html directories
make ppm - does a make all, make htmldocs and make ppd, wrapping the
whole lot up in a PPM.zip ready for distribution.
CHANGELOG:
+ [Robert May] : Documentation re-work
- new documentation structure
- new build_tools directory with scripts for building the documentation
- additions to makefiles to build docs as part of a standard build
- removal of old, superceeded scripts
- addition of ppm target to makefiles, including building of HTML docs
- auto generation of Readme and Readme.html from
Win32::GUI::UserGuide::Readme POD
- upped version to 1.01_02
- tidied up MANIFEST.SKIP
- new MANIFEST to reflect changes
- added $Id$ ident to documentation files
There is more documentation about how it all works in
'docs/Documentation.txt'
Regards,
Rob.
Robert May wrote:
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.
-------------------------------------------------------
SF.Net email is sponsored by: Discover Easy Linux Migration Strategies
from IBM. Find simple to follow Roadmaps, straightforward articles,
informative Webcasts and more! Get everything you need to get up to
speed, fast. http://ads.osdn.com/?ad_id=7477&alloc_id=16492&op=click
_______________________________________________
Perl-Win32-GUI-Hackers mailing list
Perl-Win32-GUI-Hackers@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/perl-win32-gui-hackers
