I wanted to add a way to specify extra type name mappings for
documentation; the solution exposed some deficiencies in the
ExtUtils::Depends module required by all gtk2-perl modules for
building. I figured it was important to ask for comments before
commiting this change, since it will touch all gtk2-perl modules, and
the rewrite of ExtUtils::Depends discards some esoteric features that
someone may be using. If so, please speak up!
-=-=-
The documentation generation scheme for gtk2-perl converts C type names
to Perl package names through a two stage mapping process:
1. see if there is a type mapping registered with the bindings
2. if not, look in %Glib::GenPod::basic_types for a mapping
3. failing that, pass the name through unaltered.
This fails for many things we use in the bindings, and there's no easy
way to fix it, short of adding their names to %basic_types in
Glib/GenPod.pm.
I have a patch with code to fix this situation properly, but it will
require a completely new version of ExtUtils::Depends to use it.
First, the scheme: we allow each module to specify extra type mappings
to add with Glib::GenPod::add_types(). This is the cleanest and most
robust way to do this, because it gives us full extensibility and keeps
higher-level mappings out of lower-level code.
To achieve this, however, we must have a way to install and retrieve the
extra type mappings. ExtUtils::Depends provides a mechanism for
installing data files.
However, the existing implementation of ExtUtils::Depends falls short in
a few areas: its code relies heavily on autoloading and other
hard-to-maintain magic confounded by the fact that it is almost
completely undocumented, and it doesn't store an actual list of the
modules on which a given module depends.
Intent on resolving these issues, i rewrote ExtUtils::Depends from the
ground up in December, giving it completely new innards but keeping what
i think is valid backward compatibility (it can read files created by
the old version, and creates files that contain what the old version
want to find). It also stores dependencies in a way that allows deep
chaining. That is, if Gtk2 depends on Glib, and Gnome2::Canvas depends
on Gtk2, Gnome2::Canvas should pick up Glib through Gtk2. The existing
implementation does not do this, but the new one does.
The new implementation is in cvs, as the branch tag "rewrite" on the
file gtk2-perl-xs/ExtUtils-Depends/lib/ExtUtils/Depends.pm .
With this new implementation, i was able to come up with some patches to
Glib::MakeHelper and Glib::GenPod that allow the various Makefile.PLs to
bring in all the right extra doc type mappings with little to no effort.
I changed Glib::MakeHelper->postamble_docs() to accept an
ExtUtils::Depends reference and an optional list of doctype filenames.
postamble_docs can get the list of xs files from the depends object, and
can also ask the depends object for the list of parent modules, in which
it can look for more doctype mappings. These are then passed to
Glib::GenPod::add_types before calling xsdoc2pod().
The attached files are a patch that implements the new stuff in the
Makefile.PLs and a few doctypes files. In the process of attaching them
i realize they all have the same names ("doctypes"), but one goes in
Glib, one in Gtk2, one in Gnome2::VFS, and one in Gnome2; by looking at
the contents you should be able to figure out which one is which. These
patches require the aforementioned experimental version of
ExtUtils::Depends, which is in CVS and thus not attached.
Attachment:
doctypes.patch
Description: Text Data
Attachment:
doctypes
Description: Text document
Attachment:
doctypes
Description: Text document
Attachment:
doctypes
Description: Text document
Attachment:
doctypes
Description: Text document