POD to CPAN to POD?

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?

Replies are listed 'Best First'.
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' )` [download] 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 [download]	[reply] [d/l] [select]

Replies are listed 'Best First'.

Re: POD to CPAN to POD?
by Anonymous Monk on Dec 13, 2011 at 04:23 UTC

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' )
[download]
```
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
[download]

[reply]
[d/l]
[select]

Back to Seekers of Perl Wisdom