Re^2: Extracting/embedding sample files in POD

I love having documentation close to the source, my POD doubles as comments at the head of each subroutine definition. If I were to go the route of an external module.pod- and I would if releasing anything to CPAN- I'd still write the POD source inside of module.pm and generate the pure-POD-file from that.

And in fact that looks like an intended use of POD::Tested, its processor can generate POD or test files from the same marked-up module. (I contacted the author with a comment earlier, can vouch the author is indeed dogfooding.)

My co-workers- the only other people who may look at this code- would not think to look at a separate POD file, but are grateful for good documentation in the module. So I am not going down the road of generating an external POD, even though I now see smooth ways of doing that with all desired features.

And a good-enough work-around would be to simply create the file as part of the test:

Given a file F<test.data> as below...

  File::Slurp::write_file("test.data",qq<<'END');
  Here is data
  that this function wants
  END

Results in

  # test continues here
[download]

Comment on Re^2: Extracting/embedding sample files in POD Download Code

Replies are listed 'Best First'.
Re^3: Extracting/embedding sample files in POD by LanX (Saint) on Feb 17, 2015 at 20:32 UTC
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!	[reply] [d/l] [select]
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]

Pod structure:

Workflow:

Known modules

differences