develooper Front page | perl.perl5.porters | Postings from June 2022

Re: Pre-RFC: images in Pod

Thread Previous | Thread Next
Tomasz Konojacki
June 17, 2022 23:03
Re: Pre-RFC: images in Pod
Message ID:
On Thu, 9 Jun 2022 23:24:53 +0100
Neil Bowers <> wrote:

> Revisiting this after something of a gap … here’s the basic case:
> 	P<There can be only one|>
> Q1: how should this be rendered if an image can’t be displayed? Someone commented that styling should be left to formatters, but I think podspec should propose a standard rendering as text.

IMO it should be up to the renderer to decide. HTML, GUI and pure-text
renders have completely different constraints.

> Q2: should we support non http URLs? For example a CPAN dist might want to bundle images for the doc (and have them turn up on MetaCPAN), and the Perl distribution might want to include images for diagrams: P<illustration of method resolution|images/mro.png>. That’s like to get hairy, so one option is to say that v1 just supports http URLs and worry about relative paths if there’s a call for it.

The original proposal also includes base64 data URLs.

As for bundling image files with the distribution, I think that just
storing them in the same place as .pm/.pod files is the only reasonable
way. It's simpler than sharedir and it will work for both installed and
non-installed modules. Some CPAN modules are already doing that for
storing all kinds of static data, not necessarily just images. For
example, Mojolicious has a "resources" directory:

> Seems sensible to allow optional dimensions with an additional parameter:
> 	P<There can be only one||640x480>
> Q3: I often just put just a width on images, so it should probably allow that. I.e. P<alt text||320>. Should any other format of dimensions be supported?

I think that's reasonable.

Thread Previous | Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About