Beefy Boxes and Bandwidth Generously Provided by pair Networks
No such thing as a small change
 
PerlMonks  

POD to CPAN to POD?

by jgamble (Pilgrim)
on Dec 13, 2011 at 00:32 UTC ( #943218=perlquestion: print w/ replies, xml ) Need Help??
jgamble has asked for the wisdom of the Perl Monks concerning the following question:

Before I get into the gist of my question, I'd like to direct your attention to Math::Fractal::Noisemaker, in particular the NOISE TYPES section. If you are viewing this in HTML, you will see nice graphics demonstrating the different types of fractal noise.

This was a nice idea that I immediately wanted to steal, so I looked at the author's POD code, and found that between "=begin HTML" and "=end HTML" sections he put an img tag pointing to jpeg on a github server.

Irrationally, I found this to be a little disappointing. To my mind, it would seem more elegant to have a CPAN document refer back to CPAN instead of a separate site. Thinking it over, I wondered if it made sense. Could a POD parser refer back to the module it was documenting? If I put an "images" directory in my package, could I have an HTML tag referring back to a directory that doesn't exist until PAUSE creates it?

I expect the answer is "no" (or even "hell no"), but I thought I'd run the idea by the perlmonk community. Stupid idea? Nice idea that's too tricky to get implemented? Or... possible to do?

Comment on POD to CPAN to POD?
Re: POD to CPAN to POD?
by Anonymous Monk on Dec 13, 2011 at 04:23 UTC
    Some thoughts
    • search.cpan.org is not CPAN, it is the official search engine, but there are others, like Kobesearch, MetaCPAN
    • PAUSE does not create html, see for yourself http://github.com/andk/pause
    • don't put an images directory in your package, use File::ShareDir and File::ShareDir::Install instead
    • A POD parser can do anything :) so yes, this is trivial to implement, but only practical if it is based on standard tools like File::ShareDir, say
      =for image dist_file( 'File-ShareDir', 'images/foo.jpg' ) =for image module_file( 'File::ShareDir', 'images/foo.jpg' ) =for image class_file( 'File::ShareDir', 'images/foo.jpg' )

      It would also be trivial to assume a dist or module or class based on the current dist/file being processed (also assuming a standard naming convention, which isn't universally followed), but it doesn't have to :)

      And it would also be trivial to update Pod::Simple::HTML and maybe Pod::Html to handle =for image (?:dist|module|class)_file\( (?:'[^']+\'|\s+|,)+ \) for end users (me, you)

      Not sure how search.cpan.org works exactly, but if it doesn't install modules (and it appears it doesn't) or run Makefile.PL && make (maybe it doesn't), then CPAN::Meta::Spec ( http://module-build.sourceforge.net/META-spec-v1.4.html ) might need to be updated to determine the sharedir info

    • you can preview/test your pod with search.cpan.org online pod previewer http://search.cpan.org/pod2html
    • Try it with inlined img/pod file to cpan :) pod and images/Re^2: Inline images in POD, it worked in my test (with modern browser)
      =head1 NAME pod-img.pod - example embedding html data uri image in pod =head1 THE IMAGE =for html <p><img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA +BQAAAAVCAIAAADJt1n/AAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAgY0hSTQ +AAeiYAAICEAAD6AAAAgOgAAHUwAADqYAAAOpgAABdwnLpRPAAAAKdJREFUOE/Fk2sOgCA +Mg/HqxpuZeC1sqI5ReSh/JATB7Os6HkuMMUw3wNMttMhjP7Z16+vWYWDWO3yGUTgAG5mZ +vcVfMIMAIA4jd9D4AWwAJYj5Q6jyWrO3yjkL8TD+cKmwVC6w2SlgaH3qCpfGmlrpRl6xt +/v0ZXKbVL28hc1LTnVLV2z7zGLkucy7bdo+SDKLtMK+SKl8nFngD5nnz7n/bgcP4wf4BN +5NffCErP3uAAAAAElFTkSuQmCC"> =cut

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://943218]
Approved by ww
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others meditating upon the Monastery: (6)
As of 2014-07-26 19:21 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    My favorite superfluous repetitious redundant duplicative phrase is:









    Results (178 votes), past polls