Generated POD and CPAN/MetaCPAN

wanna_code_perl has asked for the wisdom of the Perl Monks concerning the following question:

Fellow Monks,

I'm working on framework mobule that will be used by a small suite of commandline utilities, each with their own respective (perldoc) manual pages.

Rather than coding the POD for all of the commandline switches by hand (and keeping the switches up-to-date with what I accept with Getopt::Long, I'd really like to generate the POD dynamically, and have that apply to the manual page as output by perldoc. However—and here's the rub—when these utilities are released to CPAN, I want the generated POD to appear there as well (otherwise someone will have to download and install the utilities just to see their documentation, which would not be acceptable).

Here's what I already know:

Getopt::Long and Pod::Usage are great together, but they only solve half the problem—the --help text (which could easily be generated dynamically).
Actually generating the POD is trivial.
Solving the problem for installed scripts (Makefile.PL) is relatively easy: just generate the POD during the build cycle.

The part I don't have a good solution for is getting the generated POD on CPAN/MetaCPAN. The best I've come up with is this: I could augment the utilities' release process to generate the POD so it's zipped up in the distribution tarball as if it was hand-coded, but (a) that effort would negate some of the savings of auto-generated POD, and (b) I don't want to impose that effort on others who may want to use my framework module for their own utilities. I'd like it to just work.

I'm hoping there's a simple solution, here—or something already inherent in how CPAN unpacks distributions that might help—but I haven't been able to find anything.

Comment on Generated POD and CPAN/MetaCPAN Select or Download Code

Replies are listed 'Best First'.
Re: Generated POD and CPAN/MetaCPAN by RonW (Parson) on Sep 05, 2014 at 17:10 UTC
Sorry, you will have to generate your final POD docs before it gets tar'ed. One thing I'm not sure about (nor do I know if of interest to you) is whether CPAN will look at module.pod, if present, instead of module.pm I am already generating POD using a filter I coded in Perl (and plan to share very soon). For my setup, my module.pm (or program.pl) files look like: `#!perl -w =begin DoxPod # Perl and DoxPod source go here =end DoxPod _END_` [download] Then I can either `doxpod myModule.pm \| perldoc` to view, `doxpod myModule.pm >myModule.pod` to make a separate POD file, or `doxpod myModule.pm \| after_END_ myModule.pm` to put or update the (re-) generated POD after the `_END_` By using =begin and =end, "normal" POD parsers (hopefully including CPAN's information extractor) will skip the Dox-enhanced POD markup and use the generated POD	[reply] [d/l] [select]
Re^2: Generated POD and CPAN/MetaCPAN by tobyink (Canon) on Sep 05, 2014 at 19:41 UTC
search.cpan.org, MetaCPAN, and the command-line pod tools will all choose Foo.pod over Foo.pm when both exist. Take a look at almost any distribution by Ingy for an example. toby döt ink	[reply]
Re: Generated POD and CPAN/MetaCPAN by LanX (Saint) on Sep 05, 2014 at 22:05 UTC
I'm generating pod in one of my projects. The documentation for `Module.pm` is written into `Module.pod` and calling `perldoc Module` shows the generated content in `Module.pod` (see `perldoc` )ł. To keep it synchronized I've integrated the call to my `podbuilder.pl` script into my test suite as “pseudo test“. Since I never release˛ without testingą, my documentation is always up to date and if `podbuilder.pl` fails then my test suite fails too. (actually I still have to teach git-commit to stop telling that `Module.pod` has changed, don't wanna be told anymore about the obvious ;) Works for me! :) HTH! Cheers Rolf _{(addicted to the Perl Programming Language and ☆☆☆☆ :)} ą) Using the modulino principle to run the test suite facilitate things a lot. ˛) even hardly ever commit w/o testing... ł) `perldoc Module.pm` for my internal developer documentation	[reply] [d/l] [select]
Re: Generated POD and CPAN/MetaCPAN by tobyink (Canon) on Sep 05, 2014 at 19:52 UTC
You say that you don't want to impose the effort of pre-generating pod at tarball-building time on other people, however it doesn't need to be a lot of work for them. Create plugins for popular distribution packaging tools (ExtUtils::MakeMaker, Module::Build, Dist::Zilla), then they just need to add one line to their Makefile.PL/Build.PL/dist.ini. toby döt ink	[reply]


good chemistry is complicated, and a little bit messy -LW
	PerlMonks