On Fri, May 10, 2013 at 10:21 AM, Chris Marshall <[email protected]>wrote:
> How about adding some functionality to support making > PDL baseddistributions that extracts the pod from the .pd > files into appropriatelynamed .pod files with the original > pod content replaced by links tothe now separate pod > file content? > > If we wanted to be cute, they mightbe formatted such that > if a search site were to index the .pd file, it could be a link > to the generated pod file section. > > That avoids duplication of text in the distribution and > allows theoriginal .pd file to be regenerated from the > processed file afterextracting from the tar file. > > --Chris > Ah, I finally remember why I don't like this idea. CPAN.org separates "Modules" from "Documentation". Check it out here: http://search.cpan.org/~chm/PDL-2.006/ So, sure, we could preprocess the .pd files to generate pod. Both CPAN.org and MetaCPAN.org will list such pod files as "Documentation" instead of "Modules". MetaCPAN doesn't even provide links to .pd files from the release's page at the moment, so that is a win. However, in that case we would need to make sure that CPAN.org doese *not* pick up *the partial pod contained in the .pd files*, which would require touching up all of .pd files, and that is a huge PITA. Given the recent modifications to pp_def, it would be much easier to just reformat the stuff so that it renders nicely, and figure out how to coax CPAN and MetaCPAN into properly associating the pod in the .pd files with the correct module names. This issue was raised a while back on MetaCPAN's bug tracker<https://github.com/CPAN-API/metacpan-web/issues/679>. I just looked at it again today (after reading this discussion) and discovered that the solution may be simpler than we had thought. We simply need to add a "provides" key<http://search.cpan.org/%7Edagolden/CPAN-Meta-2.131560/lib/CPAN/Meta/Spec.pm#provides>to the META_ADD<http://search.cpan.org/%7Ebingos/ExtUtils-MakeMaker-6.66/lib/ExtUtils/MakeMaker.pm#META_ADD>section of our Makefile.PL. Basically, we need to make sure that whatever ends up producing the META.yml file indicates each and every Module that the PDL distribution knows how to produce. With a little bit of File::Find trickery in the Makefile.PL file and the META_ADD for this key, we should have this working without much fuss. Then, the issue simply becomes a matter of properly formatting our .pd files (or whatever we want to call them) so that their pod can be cleanly extracted. An example of an old way of doing this is contained in slices.pd; an example of the new way is contained in bad.pd. David
_______________________________________________ Perldl mailing list [email protected] http://mailman.jach.hawaii.edu/mailman/listinfo/perldl
