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);
