[feature] Add =image to perl pod

[dk]

Hello all,

As discussed here Perl/perl5#18169 I'd like to start working on a patch that implements image capabilities in pod. The proposition and syntax is there, I'll copy it in the next message to continue the discussion here as there are no objections to the general idea in the perl github.

So I'd like to foster a more concrete discussion of the final syntax and implementation details here, before I put lots of efforts in the patch. I don't expect that producing the patch is going to be a quick process, so it's not at all an urgent call, however early comments would indeed be appreciated.

[dk]

I propose an extension that, in spirit of "easy things easy", makes embedding of images in pod, well, easy. Currently it is possible to achieve that with lots of ugly hacks, but the worst is especially knowing the formatted beforehand - f.ex. to show such a pod in github or metacpan requires magic like

=for html <p><img src="...png">

where you need to know that it is actually html.

(see https://metacpan.org/pod/distribution/Prima/pod/Prima/Drawable.pod#Font-ABC-metrics as an example. It works but it is ugly).

After several rounds of discussion the consensus syntax became a yaml embedded into 'image' formatter, like the following:

=begin image

src: /path/file.png
title: "Figure 1"
text: 
  multiline
  entry
resolution: 120

=end image

or, for 90% of cases, simply

=for image src:file.png
   title:"Figure 1"

Apparently the yaml is also TMTWODI about multiline entries ( see https://yaml-multiline.info/ ), and what's more interesting, cpan's YAML doesn't understand neither of these, but that's not really relevant because YAML.pm is not in the core. The proposal is agnostic about multiline style.

Pod people raised a concern about how to parse these YAML sections in core perl modules. It seems the most sensible solution would be to include a minimal Pod::Simple::YAML parser, just enough to parse 1-level deep structures found in the image section.

The "src:" tag is to be used for both local and remote path, referring to the installation and/or distribution root. It will be the module author's job to make sure that, the image referred is installed in the same relative path as it is found in the distribution.

The "text:" fallback will be produced by formatter that understands =image, but where graphic output is unavailable. The drawback is that old and non-conforming formatters will not display the fallback text

The "resolution:" tag is to be used when the image size is important to match the text size. Formatters may use the value, in DPI, to scale the output image accordingly.

The "title:" tag is to be displayed as a generic description of the image. For example XHTML may use <figcaption> for this. When graphic is unavailable, the tag content may not be displayed if the "text:" tag exists.

The format is open for more tags, however I think these should be conservative - potential addition of "width: 90%" and "rotation: 45" and what not will complicate the things greatly; the rationale is to keep syntax rather terse, in the same vein as markdown's image syntax.

In the output, an image will not be part of text, ie a floating image with f ex inline formula. An image will always end the current paragraph and will start a new one. Two =image blocks will be rendered as two separated paragraphs.

It is proposed to adjust the core Pod::Simple so that it knows about the =image block, and will parse it so that the formatters don't need doing so. Pod::Simple creates an element tree and passes it to the formatters; these, in turn, should be adjusted to produce the corresponding output.