[Pdx-pm] Two peas in a perlpod
jeff at vpservices.com
Wed Feb 9 10:49:23 PST 2005
Keith Lofstrom wrote:
>I like the idea of embedding pod documentation
>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.
More information about the Pdx-pm-list