Re: [feature] Add =image to perl pod #18169

> Using a formatting code for this seems a bit more complicated than might
> be necessary, since now the formatter needs to know whether the image
> truly should be inline (an emoji), whether it should float, whether it
> should be set off as a figure, etc.  Formatting codes imply that this is
> an emoji that should be totally inline with the text, which is certainly
> something people may want to do but which I suspect is not the common
> case.

Correct! But isn't it beautiful? One can write it both ways P<x^2 | x_square.png>,
and full-scale

P< Figure 1, description | fig1.png >

However it's not clear how to treat the title best. I'll address that below.

> > =begin text
> 
> > ^ y  **
> > |  ** 
> > |**
> > |----------> x
> 
> This doesn't work with *roff output.

Indeed it doesn't, so here are options when one wants to address non-graphic 
formatter.

Option 1, the old way, write =for text, =for nroff explicitly. That's ugly.

Option 2, expantion of =for,=begin, and =end syntax, where one would be able to write
=for text,nroff. Still somewhat inelegant.

Option 3, extend the P<|> syntax with P<&> and P<^>, so that P<title|pic.png> will 
show either text or picture, P<title&pic.png> will show title only on graphic media,
and P<title^pic.png> would show both on graphic media but text on text/man only.

Option 4, cut the extra possibilities and vote for what the most useful translation of
P<|> would be.

> It's a bit tricky to wedge support for formats that don't support images
> into the POD syntax.  We could make up a keyword for =begin/=for that
> means "doesn't support images" and add support for that, but that means
> the whole image block will disappear for older formatters.

Or indeed as you propose, extend =for with roles/capabilities, so that for
example =for can(text) can answer to text and nroff, while =for can(graphic)
would do so for html,pdf etc.  With this, all discussions whether to include
text together with the image or not becomes irrelevant. The back-compat is important
but if there's no way to avoid breaking it, well, so be it?

Practically I don't see a big problem, because if the feature will be widely
adopted, major sites like github and metacpan would be getting feature requests
to support that, which covers about 95% of graphical pod usage.

> I wonder if it would make sense to do something like:
> 
> =image graph.png
> 
>   ^ y  **
>   |  ** 
>   |**
>   |----------> x
> 
> =endimage

That's along the lines of my original proposal, which has a upside
that older formatter would immediately emit warnings, prompting for upgrade.
And a downside that it opens pandora's box for setting =image width="10em"
and what not, which I don't really want to encourage.


-- 
Sincerely,
	Dmitry Karasik