On Fri, Apr 15, 2005 at 08:10:37AM -0400 muppet wrote:

> On Apr 14, 2005, at 2:10 PM, Tassilo von Parseval wrote:
> 
> >Not really XS-related: I probably wouldn't generate the PODs 
> >dynamically
> >at install-time. The problem is that people can't get an idea of the 
> >API
> >of the module when by around search.cpan.org. For me, the module's
> >documentation is the main criterion for trying out or not trying out a
> >new module.
> 
> What he was doing here was just using the infrastructure we invented 
> for gtk2-perl, where there are simply too many xsubs for 
> hand-maintained documentation to be practical.  The tools in 
> Glib::ParseXSDoc and Glib::GenDoc parse your xs files for xsub 
> signatures and match them up with a special dialect of pod comments, so 
> that your xsubs get mentioned in the docs whether you wrote something 
> about them or not.  Also, a fair amount of information (inheritance 
> hierarchy, object property types, signal signatures, enumeration 
> values) is gleaned through introspection, so you actually have to build 
> and run the bindings in order to create the docs.
> 
> And, yes, it does irk me that although we put all that work into 
> documentation generation, which creates over 200 manpages for the Gtk2 
> extension alone, the gtk2-perl extensions look almost completely 
> undocumented on CPAN.  As a workaround, we have the docs online at 
> http://gtk2-perl.sourceforge.net/doc/pod/ .

Of that I wasn't aware. I suppose I never took into account that the
PODs might in fact be auto-generated. At least not until I skimmed
through Mozilla::POD's sources yesterday.

> The obvious solution is to pregenerate the pod and include the 
> generated files in the dist tarball, but a) there's the chicken and egg 
> problem of having to build before you can build the dist, and b) 

I'd probably write a script for it that first builds the distribution
(including the PODs) and from that creates a distribution that should be
uploaded to the CPAN (with a modified Makefile.PL that has the
POD-autogeneration sections removed).

> where 
> in the tarball do you put the *.pod files such that CPAN will see them?

As far as I know, search.cpan.org takes .pod files into account, too. So
it should be possible to have a scheme such as

    lib/Module.pm
    lib/Module.pod

This is also very perldoc-friendly since perldoc prefers .pod files over
.pm files of the same name.

Tassilo
-- 
use bigint;
$n=71423350343770280161397026330337371139054411854220053437565440;
$m=-8,;;$_=$n&(0xff)<<$m,,$_>>=$m,,print+chr,,while(($m+=8)<=200);

Reply via email to