Proposal: images in POD

[dk]

The discussion started here: https://github.com/metacpan/metacpan-web/issues

As suggested by @haarg, here are my thoughts. What I personally miss is the easy ability to embed images in POD, and I'd like to propose new formatting extension for that.

1. =for image URL

where URL can be either /path which would mean the dist-relative path, or http/ftp/etc url. That I think would cover for 95% of cases needed.

2. =for text

this special formatter is for cases when one wants to fall back gracefully where the renderer is text-based.
Example:

    =for image /pod/moo.png

     =begin text
        _____
         < moo >
     -----
    \   ^__^
     \  (oo)\_______
        (__)\       )\/\
            ||----w |
            ||     ||

     =end

[haarg]

Examples of these ideas: https://metacpan.org/pod/Test::podimage
Related idea with image and text: https://metacpan.org/pod/Pod::Weaver::Plugin::Ditaa

The primary problem here is that "dist relative" only has meaning when you actually have a dist. The images won't be installed along with the modules, so the images won't be available if you try to view the pod as HTML later. When I implemented the dist relative images on metacpan, it was primarily for the lack of any better option. I needed to rewrite the image tags anyway, and thought dist relative (or file relative without the leading slash) was the only sensible thing to do. It doesn't transfer well to some other use cases.

I also wonder if it would be good to have a way to link the image and text representations more closely. To allow a formatter to pick only one of a set of alternatives rather than the current style of using filtering based on the format.

[dk]

The images won't be installed along with the modules

Hmm not necessarily. I remember that older perls came with html prebuilt, however I'm checking current installations and there are no html files. Probably the html consistency is not that important, but if the feature will be adopted, pod2html can be hacked to support relocation of image paths.

What I also expect is that when module writers will begin to include image files together with their pod/pm files, it would be more rational to suggest to not use / in the path, which would mean to use same path where the pod/pm file is located. If they will still use / though, that can point either as it does now, to the distribution root, or we can make it a bit more portable, where it will be
$SPREFIX/site/lib/ModuleName for the installed module, and lib/ModuleName for the dist.

To allow a formatter to pick only one of a set of alternatives rather than the current style of using filtering based on the format

I have experimented with that in https://metacpan.org/pod/Prima::PodView#Content-methods but I can't say I'm proud of the result, it looks somewhat ugly for the sake of supporting many options. It has though an important clause: if the image in question is either not found or cannot be loaded, the fallback will be the related text. But indeed it is possible to copy the effort with f.ex. this:

`

  =for switch start

  =for image foo.png

  =begin text

      F O O

  =end text

  =for switch end

`

It will be harder though to support in the html renderer.

[haarg]

I wonder about something like

=begin :alternate

=for image foo.png

=begin text

Stuff

=end text

=end :alternate

[dk]

I don't have a problem with that. But that needs to get tested on major pod parsers to see if they hiccup on non-alphanumerics

[dk]

Ah sorry I didn't notice =begin :alternate instead of =for. That syntax will get us in trouble when running through pure-text rendered such as basic perldoc. The =for syntax will fall back gracefully

[dk]

There's another aspect to this, I'm thinking about. I wonder what would be the best course of event, start to implement these specs already in metacpan, or send it to p5p for further discussion? I personally favor the first option, because I'm afraid that p5p discussion can stall it forever.

[jgamble]

Huh. Seven and a half years ago I asked a question about including images in my POD.

(The module used as an example in my question, Math-Fractal-Noisemaker linked to images that were hosted on a site that doesn't seem to be up anymore, unfortunately.)

The person who answered my question suggested in-lining the image, which I eventually did (albeit with SVG, see #2088), but he or she also brought up

=for html <p><img src="data:image/png;base64, "[base64 text here...]">

which also seems useful, and would have kept the images in Math-Fractal-Noisemaker from being lost.

Perhaps as a first step the HTML filter could allow 'img' with just that type of 'src' attribute?

[haarg]

That is already allowed.

[jgamble]

Yup, sorry, I was looking at the filter_html() function and didn't realize the replace_img key handled that. Sorry for the noise.