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