[feature] Add =image to perl pod

[dk]

I propose an extension that, in spirit of "easy things easy", makes embedding of images in pod, well, easy.
Currently it is possible with a 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 html, for example.

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

In my experience an image tag should be able to do the following:

1. display a locally installed image
2. display a remote image (as in "img src")
3. display a text fallback (as in "img alt" or similar)
4. display nothing

An =image tag, in full form, would be thus used like this, for example:

=image begin

=image local "lib/graphic.png" (get searched in @INC for example)

=image remote "http://github.com/.../graphic.png"

^ y
|       *
| *
|------------> x

graphic for man pages

=image end

and also a short syntax for 90% of cases just as

=image "http://github.com/.../graphic.png"

This will break backward compatibility, but I'm decidedly not proposing a weaker but compatible option, such as f.ex.

=begin image 

=for image 

=end image

because I think that images should no longer be hacks but rather 1st class citizens.

Let's discuss this

[Grinnz]

I appreciate the design proposed, and =for html is awkward to use for this (though in practice HTML is the only medium that actually renders images), but I would much rather convince Pod::Simple::XHTML to recognize =for image which does not need to change the spec or break compatibility, and only would affect formatters that care about it.

[xsawyerx]

General comments:

• I wouldn't separate local and remote. I think these create confusion. Instead, the parsers should use a defined location for it. (For example, the current directory where this is rendered, as in HTML.)
• I wouldn't put images in @INC. I absolutely abhor that. (I won't be making the call on this at the moment, just saying I personally really dislike this idea.) Then again, we might use __FILE__ to make this deterministic. But I hate putting non-Perl in a library directory.
• Perhaps we should somehow connect this with some mechanism like File-ShareDir which tries to "correctly" (for different values of "correct") detect the location of files for a module.

I have a lot of questions that come up:

• Do we care about width and height attributes for images?
• Do we care about the title attribute for images?
• HTML5 provides figcaption and figure. What about them?
• HTML5 provides picture. What about it?
• HTML5 supports other multimedia elements like video. Do we intend to natively support them too or limit our support for img?

My biggest concern here is that it will promote a single, specific multimedia element as first-class in the POD specification. There are both additional types of multimedia elements, as well as elements that can replace this one. So why this one? What about them?

My second biggest concern is that we might be growing here into an attempt to recreate arbitrarily complicated HTML using POD and I'm not sure we'll be able to do it. (It might not be exactly "arbitrarily complicated," but it sure can be. The example in the ticket includes <p> tags, so we're definitely trying to replicate paragraphs along with the <img> tag.)

[dk]

@Grinnz I agree that breaking back compatibility is a thing better to avoid, but I also don't see a problem introducing it as it happened already with =head3 and =head4 back then. If old formatters emit a warning f.ex. "tag =image unknown" but will continue working that is even better I think, that way they send a signal to the user that update is needed

[dk]

@xsawyerx I see a need for local images, f ex when converting to latex or pdf, or using an offline documentation. I agree that local and remote subtags are somewhat inelegant, however I seriously doubt that one can (and for that matter, should) enforce a html-like schema where both local and remote images can be defined as a single unambiguous URI. F ex metacpan or github, when rendering a pod file as html, won't extract referenced images that are found correspondingly either in archive or in a repository, that might have different paths compared to where an image is to be installed locally.

What I meant by INC is to define a local storage for a module, which is in my eyes falls quite naturally in $SITEPERL/lib/$MODULE . Many modules already install pod files there - would you consider that a malpractice too? I don't mind though extending =image with location rules other than INC, as long as this is standartized; I wish though this could be done easily because when one runs "perldoc foo", foo.pod is searched exactly in INC.

• width and height: probably we won't care, but we may leave a possibility to extend the syntax for that, without breaking back compatibility, =image size 10x20 for example or similar. This could open a pandoras' box though as we would wish then size="80%" and width="10em".

• title and/or figcaption: could be a good idea actually; add a =image title subtag that gets converted to <figcaption> in a html formatter?

• picture: that looks like a candidate for =for html5, not for =image. I've seen websites with scientific articles that, when f ex viewed on mobile and a figure is too small to fit, expand it to a larger image popup when clicked on. The html formatter could be doing smart tricks like this too.

• video: also answering to "single, specific multimedia element". I see =image as an essential tool for including not only in html, but latex and pdf, and generally things that can be printed on paper, i e "documentation" as in P.O.Documentation. In my optics it falls more in the same category as B<> and I<> rather than a multimedia element (which is not 100% correct, yes, but that's for illustrating my point of view). So, no =video as it cannot be printed.

However I very much agree that =image and potential friends like =video could indeed begin to grow into an unmanageable set of features. That's why I'd rather keep =image spartan, confining it to the 4 options I outlined in the ticket: local, remote, text fallback, and no text fallback. Ah yes, a figcaption too; figcaption is nice.

[haarg]

Previous discussion: metacpan/metacpan-web#1965

[xsawyerx]

Are you suggesting that we decouple the concept of an image from HTML's img property?

If our image property would correlate to the img property in HTML, we would first need to support all the fields it has in a consistent manner (local vs. remote is managed using the implicit URI spec in browsers), we would need to figure out how to support the figure and figcaption options - oh, and maybe srcset too.

If we're not coupling the suggested image property from HTML's img property, we would still need a rich-enough specification to allow translating it into HTML. I think it makes sense for us to do this, but it might be a bigger undertaking to determine the superset of options.

It's worthwhile researching how this is handled in other formats. We could try to steal from TeX, but here lie dragons. TeX is far more capable than Pod and we might be stea^Winspired by TeX but still be unable to properly import the full capability it has (coughPerl6cough). In Markdown, there is a syntax for images but I fear it suffers from the same problems of elevating certain HTML elements to first-class.

Perhaps we could just follow Markdown in minimal support for images and the desire for more compatibility with Markdown to introduce it.

[dk]

I guess it was implicit, but yes, I do suggest to not copycat html's img tag and its properties. Moreover, I don't suggest to dive into devising a rich-enough specification, as this is going to open for 1) endless discussions and 2) will be too much tied up to html. For example, text support in html: it has all these great possibilities to set fonts, use text sub/superpositions, letter spacing, kerning and what not, and yet POD is just fine without these text features. So yes, I think that Markdown's minimal support for images is the way to go, Markdown did it right.

I'm not really proficient in TeX/LaTeX, but I know how to deal with images in PDFs. That format has a rather unique set of image capabilities not necessarily available in html - it can apply arbitrary matrices, stencil masks, alpha masks, porter-duff operators (special alpha blendings), create filling patterns from images, and more. I think supporting these would be a serious overkill, and that is the same point of view I take when arguing against supporting all of html image functionality.

[tonycoz]

@xsawyerx I see a need for local images, f ex when converting to latex or pdf, or using an offline documentation. I agree that local and remote subtags are somewhat inelegant, however I seriously doubt that one can (and for that matter, should) enforce a html-like schema where both local and remote images can be defined as a single unambiguous URI. F ex metacpan or github, when rendering a pod file as html, won't extract referenced images that are found correspondingly either in archive or in a repository, that might have different paths compared to where an image is to be installed locally.

Resolving relative references to images is something the parser will likely need to do (possibly as an option indicating a base URL for pod2html).

I think a simple relative URL rather then distinguishing local and remote URLs would work.

I expect most formatters would disable remote URLs by default to avoid remote images becoming an attack vector by default if some image library ends up with an attackable security issue. I'd be inclined to not support remote URLs at all, since some (most?) processors will need to fetch the URL to render the image, or even to just get the size for HTML.

While I'd love images in POD, I'm not sure they belong in the format.

[dk]

@tonycoz As my concern with remotes is only for metacpan/github/etc online renderers, I do agree that remotes, as a general concept, should be out of the picture. But let's look at github f ex: if I want to include an image from the same repository, I need this URL:

https://raw.githubusercontent.com/$USER/$MODULE/$BRANCH/pod/pic.png

whilte a pod itself, when rendered, is served from

https://github.com/$USER/$MODULE/tree/$BRANCH/pod/foo.pod

On one hand I'd love to say just =image pod/pic.png, on the other how would one persuade github to implement this?

[dk]

update:

1. just tested it on github, shows images just fine.

2. metacpan can display markdown files but can't show images

So I guess remote and local could be indeed merged! This is great. Which means that we could also borrow from the markdown syntax and make images part of a text paragraph, not a paragraph on its own - with syntax like P<title|uri.png>, for example. This would also cut attempts to extend on the image functionality (width, alpha, whatever), which I think is a good thing.

[yuki-kimoto]

because I think that images should no longer be hacks but rather 1st class citizens.

I think so. I also want pod syntax which can express image.

[dk]

Another point, the P<> syntax doesn't need to contain special text fallback. Because, contrary to the multitude of the graphical formatters, text can be addressed simply as =for text. That means one can write a pod such as

P<foo.png>

=for text this is graphic

if so desired.

I'm thinking about working on a patch however I don't want to find myself in a situation where it would be rejected or premature because the very topic is undecided yet. @xsawyerx what kind of consensus should be reached there for the green light, if any?

[karenetheridge]

Proposed changes to pod syntax should be run through the pod-people list before merging.

https://lists.perl.org/list/pod-people.html