INTRODUCTION
============
This file describes the documentation for Win32::GUI. Please edit it and keep it up
to date as chages are made.
All documentation should originate as POD. The HTML documentation is then generated from
this using pod2html (see POD::Html).
The documentation is divided into packages, and the directory structure under the top
level 'docs' directory reflects this - this is required so that links to over documents
works correctly.
DOCUMENTATION PACKAGES
======================
* Win32::GUI docs/GUI.pod
Table of Contents
* Win32::GUI::pkg docs/GUI/pkgname.pod
Per Package docs, generated from embedded documentation in
the Source (XS, CPP and PM files). Depending on the package,
there may be documentation in sub-packages below this one.
(See doPodDocs script, later)
* Win32::GUI::UserGuide docs/GUI/UserGuide/
- Win32::GUI::UserGuide::Readme docs/GUI/UserGuide/Readme.pod
Win32::GUI Readme file. This is used to build Readme and
Readme.html that are put into the distribution files
(see doReadme script, later)
- Win32::GUI::UserGuide::Introduction docs/GUI/UserGuide/Introduction.pod
A brief introduction to Win32::GUI
- Win32::GUI::UserGuide::Concepts docs/GUI/UserGuide/Concepts.pod
A overview of the Win32::GUI concepts
- Win32::GUI::UserGuide::FAQ docs/GUI/UserGuide/FAQ.pod
A (currently outdated) FAQ.
* Win32::GUI::Reference docs/GUI/Reference/
- Win32::GUI::Reference::Packages docs/GUI/Reference/Packages.pod
A list of all the Win32::GUI packages, with links to the
per-package documentation. Package list is built automatically
(See doPodDocs script, later)
- Win32::GUI::Reference::Methods docs/GUI/Reference/Methods.pod
A list of the common methods - actually a list of all the
methods in the Win32::GUI package. Method list is built
automatically.
- Win32::GUI::Reference::Options docs/GUI/Reference/Options.pod
A list of the common options.
- Win32::GUI::Reference::Events docs/GUI/Reference/Events.pod
A list of common events - actually a list of all events found
with "APPLIES_TO:*". Event list is built automatically.
* Win32::GUI::Tutorial docs/GUI/Tutorial.pod
Table of contents for the tutorial
- Win32::GUI::Tutorial::Part1 docs/GUI/Tutorial/Part1.pod
Part 1 of the tutorial
- Win32::GUI::Tutorial::Part2 docs/GUI/Tutorial/Part2.pod
Part 2 of the tutorial
- Win32::GUI::Tutorial::Part3 docs/GUI/Tutorial/Part3.pod
Part 3 of the tutorial
- Win32::GUI::Tutorial::Part4 docs/GUI/Tutorial/Part4.pod
Part 4 of the tutorial
- Win32::GUI::Tutorial::Part5 docs/GUI/Tutorial/Part5.pod
Part 5 of the tutorial
- Win32::GUI::Tutorial::Part9 docs/GUI/Tutorial/Part9.pod
Part 9 of the tutorial
EMBEDED DOCUMENTATION
=====================
The Embedded documentation is turned into POD documentation
by the script 'build_tools/doPodDocs.pl'. This tool is
run by the make target 'all', and puts generated POD documentation
into the correct subdirectory of the blib directory tree, such that
it will be installed in the correct locations by 'make install'.
You may manually invoke this script from the commandline, using the make
target 'poddocs'.
When parsing the documentation, the script uses the package
'build_tools/SrcParser.pm' to parse out the documentation from the
source files.
* Packages
Introduced by a line containing the text:
(@)PACKAGE: Win32::GUI::PackageName
The first comment line, immediately following such a declaration is taken
as the package abstract, and should be a short title for the package
Any other comment lines following the package declaration are taken as
package description text.
* Methods
Introduced by a line containg the text:
(@)METHOD: MethodName(prototype)
This must happen AFTER a (@)PACKAGE declaration. Any comment lines
following such a declaration are taken as a description of the method,
with the exception of addiional (@)METHOD declarations, which are
assumed to be alternate calls for the same method. Alternate calls
my have no package declaration (DoStuff()) in which case they are
assumed to be in the sam epackage as is current, and will get a
'See method()' text, with a link to the current method; or they may
have a package declaration (Win32::GUI::SomePackage::doStuff()) in
which case they will be documented under the alternate package, including
the description, with an addition 'See OriginalPackage::OriginalMethod()'
line.
* Events
Intruduced by a line containg the text:
(@)EVENT: EventName(prototype)
Any following comment lines are assumed to be description, except lines
containing (@)APPLIES_TO: listOfPackages. Where listOfPAckages is either
* (applies to all packages) or non-qualified, comma seperated package names.
There must be at least one (@)APPLIES_TO line.
* DESCRIPTIONS
Decription blocks are continuous block of source comments following one of
the identifier lines described above. The descriptions amy contain POD
formatting commandes (e.g. B<...> C<...> etc.). Any line indented
by more than one space after the comment identifier (#, *) will be treated
as a POD 'verbatim' line. Continuous sets of such indented lines will be
treated as a POD verbatim block. Blank lines will be introduced either
side of verbatim blocks if not provided in the source.
Description blocks are also parsed for text that looks like:
See also method()
See new Win32::GUI:Package()
and various variations on this theme. Such text will be updated to have a link
to the referenced method on the appropriate package's page.
* LINKS
If you wish to provide a link to a page from within the text, please use the
form:
L<description|Win32::GUI::PackageName>
even if this means that your link looks like:
L<Win32::GUI::PackageName|Win32::GUI::PackageName>
as the form without the description generates text like
'See the Win32::GUI::PackageName manpage' when converted to HTML by pod2html.
MACROS and TEMPLATING
=====================
The 'build_tools/doPodDocs.pl' script applies a very basic macro expansion and templating scheme
to the documents that it processes. The following macros are applied to every
POD page as it is copied from the 'docs' directory tree to the 'blib' directory
tree (See 'build_tools/BuildTools.pm'):
__W32G_VERSION__ The Win32::GUI VERSION being built
__W32G_PERLVERSION__ The Major perl version being used (e.g. 5.6, 5.8)
__W32G_DATE__ Today's date (formatted as 12 Jun 2005)
__W32G_YEAR__ Today's year (4 digits)
__W32G_FILE__ The Win32::GUI VERSION being built
__W32G_WEB_HOMEPAGE__ The URL of the Win32::GUI homepage (http://sourceforge.net/projects/perl-win32-gui/)
__W32G_WEB_USERMAIL__ The URL of the users mailing list sign-up page
(http://lists.sourceforge.net/lists/listinfo/perl-win32-gui-users)
__W32G_WEB_MAILARCHIVE__ The URL of the mailing list archives (http://sourceforge.net/mail/?group_id=16572)
__W32G_WEB_FILES__ The URL of the Win32::GUI files download page
(http://sourceforge.net/project/showfiles.php?group_id=16572)
__W32G_POSTAMBLE__ Expands to include VERSION, SUPPORT and COPYRIGHT and LICENCE sections that
should be common to all POD pages (see 'docs/pod_postamble.tpl')
__W32G_EMAIL_USERLIST__ => 'perl-win32-gui-users@lists.sourceforge.net',
README FILE
===========
The script 'build_tools/doReadme.pl' is run as a dependent for any distribution generating
make target (dist, distdir, ppm), and updates the Readme and Reademe.html files in the
root of the distribution from the 'docs/GUI/UserGuide/Readme.pod' file.
It can be run manually as 'make readmedocs'.
HTML DOCUMENTATION
==================
The script 'docs/doHTMLDocs.pl' takes any POD dcumentation that exists in the blib/lib
directory tree, converts it to html and put it in the blib/html/site/lib directory tree.
It also copies any image files from the 'docs' directory tree (esp. See the tutorial).
This script is run as a part of the 'make ppm' target, and can be run from the command
line as 'make htmldocs'. It is dependent on the poddocs target, so POD documentation
is all automatically updated as part of this process. Conversion to HTML is performed
using pod2html (See POD::Html).