[perl-win32-gui-hackers] Re: Documentation changes

[Robert M. <rm...@po...>]

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
> Per...@li...
> https://lists.sourceforge.net/lists/listinfo/perl-win32-gui-hackers
>