Re^3: Extracting/embedding sample files in POD

hmm, some clarifications:

Pod structure:

How it works

perldoc Module will display pod for Module.pod if found.
only perldoc Module.pm will show pod for Module.pm
in my system Module.pod is meant for the general API seen e.g. CPAN! (YMMV)
Module.pm still contains valid pod! It's showing more detailed developer documentation

So if your collaborators open Module.pm they'll find what they need to see, plus maybe a disclaimer/link pointing to Module.pod

Workflow:

You seem to have the idea to automatically modify your Module.pm with test results.

I'm not a friend of such self modifying magic (at least outside my IDE and w/o human monitoring).

I prefer a strict separation between

Model: e.g. Module.pm, test scripts
View: Module.tpl.pod
Controller: the "podcreator.pl" defining the logic
Product: Module.pod, Readme(.pod),...

Known modules

I can't comment much on the CPAN modules you mentioned cause creating Pod from tests or vice versa wasn't on my task list yet.

I can imagine at least two cases where such a DRY workflow is beneficial:

a) sample code in POD (like in tutorials) which needs to be tested before publication

b) simple (unit) tests which are self documenting (e.g. showing use cases, function signature, and so on)

In any case I'd prefer to have a generic test script for such cases (the controller ) in my t/ directory which extracts the necessary data from the module's pod (the model ), to do the testing and create test reports and new POD (the product ).

Like this I can always resort to more complicated plain test scripts if embedding the logic within POD starts to over complicate things.

differences

I'm realizing now that your use case seems to be different or more fuzzy, so take my 2¢ as a meditation.

Thanks anyway this helped me improving my concept.

HTH =)

Cheers Rolf

PS: Je suis Charlie!

Comment on Re^3: Extracting/embedding sample files in POD Select or Download Code

Replies are listed 'Best First'.
Re^4: Extracting/embedding sample files in POD by Yary (Pilgrim) on Feb 19, 2015 at 19:47 UTC
We're "on the same page," or close to it. I'm creating supplementary tests from in-source-POD, and pure-POD from that same in-source-POD. The main difference between your workflow idea and my current practice is that I haven't separated the POD template out into its own file, à chacun son goût... My sample code is in POD inside of `Module.pm` POD::Tested provides a controller script `pod_tested.pl` that can generate both (or either of) `Module.pod` and `Module.t` as products of `Module.pm`'s POD There's no magic re-writing of the original `Module.pm`. I now have some tests asserting that my examples are correct, and pure-POD files alongside the modules. There's a little more to it than that "in real life" but that's the basics.	[reply]
Re^5: Extracting/embedding sample files in POD by LanX (Saint) on Feb 19, 2015 at 22:29 UTC
OK thanks , I'll give it a try. :) `push @todo, POD::tested` (pity the keyword tag system in the monastery can't be searched) Cheers Rolf PS: Je suis Charlie!	[reply] [d/l]