[Pdx-pm] Two peas in a perlpod

[Jeff Zucker]

Keith Lofstrom wrote:

>I like the idea of embedding pod documentation
>
Pod rocks.

>Is possible to extract two pod documents from one Perl program,
>  
>
Well there are a number of Pod parsers and other ways of dealing with 
Pods on CPAN including Portland's own Allison's Pod::PseudoPod. 
Pod::Simple is the base for most of them.

>or extract one pod document from two Perl programs, perhaps by
>adding some special pod tags and running a special pod extractor? 
>For example, I want to generate both a user's and a designer's
>doc from the same perl script;  the designer's doc might be
>constructed out of multiple perl scripts.
>  
>
It sounds like the easiest thing to do would be to put the user's pod in 
the .pm file and distribute a designer.pod along with it. If you have a 
bunch of example scripts, each with its own pod, just let the users run 
perldoc on those scripts.

>For extra credit, is it possible to direct the same chunk of
>embedded pod to multiple pod docs, or to reorder the chunks
>of embedded pod documentation into the final pod doc?
>  
>
Yes, with one of the Pod::* modules, though just using the L<> tag to 
make links from one document to another is easier.

>Again, I assume enhanced pod extraction mojo will be needed,
>probably called by Makefile.PL .  
>
I don't think you want to distribute pod parsers with your distribution 
or require that the user has them. A better way would be for you to 
generate all the pods beforehand.

>There is no doubt something
>that does this in CPAN, but how would I find it?
>
In the Pod::** hierarchy.

-- 
Jeff