Mailing List Archive: Pre-RFC: images in Pod

Pre-RFC: images in Pod

Nov 15, 2021, 5:42 PM

Post #1 of 31 (1878 views)

Images are one of the most frequently requested features for Pod. There
was a proposal in the past[1] but it failed to achieve unanimous support
of the community, mainly because it was perceived as too complicated.

https://github.com/Perl/perl5/issues/18169

My proposal takes a different route. Images will be inputted using the
new formatting code, P<>, which stands for "Picture".

Compared to the previous proposal this has several advantages:

- It's much simpler, it doesn't require a YAML parser.
- Images can be embedded inline inside a paragraph.
- It plays well with the table syntax that I have proposed in the other
pre-RFC.

Of course, there are also some disadvantages. The syntax isn't
extensible; for example, it's impossible to specify the dimensions of
the image. In my opinion, this isn't a big loss.

Some examples:

P<https://example.com/image.jpg>
P<https://example.com/image.jpg|alt text>
L<P<https://example.com/image.jpg|this image is a link>|https://example.com>
P<data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAPBAMAAAAfXVIcAAAAMFBMVEWdDtesnV3g9aGo4gLH7FKz9giz5R6/6Tuy5RKkVpjz+9qwvEKgKcDQ722la4P////TI3mRAAAACXBIWXMAAA7EAAAOxAGVKw4bAAAAaUlEQVQI12P4////qlVAguH/f2djYyMQ43NoW2iwPpBx9XVo9OR+EOOAqACbPZChuufonNR+sJrQ0OB6EKMtLS0ZpPivGZCxHmSORVqaBdhA5bYMKzDji1lyPZjxv9kYYtf/L/ehDDAAACPTVSyPrPcdAAAAAElFTkSuQmCC>

Re: Pre-RFC: images in Pod [ In reply to ]

perl5-porters at perl

Nov 15, 2021, 6:55 PM

Post #2 of 31 (1878 views)

On Tue, 16 Nov 2021 at 09:42, Tomasz Konojacki <me@xenu.pl> wrote:

> Images are one of the most frequently requested features for Pod. There
> was a proposal in the past[1] but it failed to achieve unanimous support
> of the community, mainly because it was perceived as too complicated.
>
> https://github.com/Perl/perl5/issues/18169
>
> My proposal takes a different route. Images will be inputted using the
> new formatting code, P<>, which stands for "Picture".
>

Love it. Yes please.

Re: Pre-RFC: images in Pod [ In reply to ]

grinnz at gmail

Nov 15, 2021, 7:04 PM

Post #3 of 31 (1878 views)

On Mon, Nov 15, 2021 at 8:42 PM Tomasz Konojacki <me@xenu.pl> wrote:

> Images are one of the most frequently requested features for Pod. There
> was a proposal in the past[1] but it failed to achieve unanimous support
> of the community, mainly because it was perceived as too complicated.
>
> https://github.com/Perl/perl5/issues/18169
>
> My proposal takes a different route. Images will be inputted using the
> new formatting code, P<>, which stands for "Picture".
>
> Compared to the previous proposal this has several advantages:
>
> - It's much simpler, it doesn't require a YAML parser.
> - Images can be embedded inline inside a paragraph.
> - It plays well with the table syntax that I have proposed in the other
> pre-RFC.
>
> Of course, there are also some disadvantages. The syntax isn't
> extensible; for example, it's impossible to specify the dimensions of
> the image. In my opinion, this isn't a big loss.
>
> Some examples:
>
> P<https://example.com/image.jpg>
> P<https://example.com/image.jpg|alt text>
> L<P<https://example.com/image.jpg|this image is a link>|
> https://example.com>
>
> P<data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAPBAMAAAAfXVIcAAAAMFBMVEWdDtesnV3g9aGo4gLH7FKz9giz5R6/6Tuy5RKkVpjz+9qwvEKgKcDQ722la4P////TI3mRAAAACXBIWXMAAA7EAAAOxAGVKw4bAAAAaUlEQVQI12P4////qlVAguH/f2djYyMQ43NoW2iwPpBx9XVo9OR+EOOAqACbPZChuufonNR+sJrQ0OB6EKMtLS0ZpPivGZCxHmSORVqaBdhA5bYMKzDji1lyPZjxv9kYYtf/L/ehDDAAACPTVSyPrPcdAAAAAElFTkSuQmCC>
>

I like the basic idea. The loss of sizing control would be unfortunate,
but worked around by sizing the image you include as desired.

A larger question is how to refer to images without an absolute URL as it
relies on having external hosting for the image available. Most commonly
images would be included with the CPAN distribution and displayed by
metacpan so it's worth optimizing for that use case. I believe there was
some discussion of this in the previous thread that it would be worthwhile
to review.

-Dan

Re: Pre-RFC: images in Pod [ In reply to ]

Nov 15, 2021, 7:09 PM

Post #4 of 31 (1878 views)

On Tue, 16 Nov 2021 02:42:05 +0100
Tomasz Konojacki <me@xenu.pl> wrote:

> Some examples:
>
> P<https://example.com/image.jpg>
> P<https://example.com/image.jpg|alt text>
> L<P<https://example.com/image.jpg|this image is a link>|https://example.com>
> P<data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAPBAMAAAAfXVIcAAAAMFBMVEWdDtesnV3g9aGo4gLH7FKz9giz5R6/6Tuy5RKkVpjz+9qwvEKgKcDQ722la4P////TI3mRAAAACXBIWXMAAA7EAAAOxAGVKw4bAAAAaUlEQVQI12P4////qlVAguH/f2djYyMQ43NoW2iwPpBx9XVo9OR+EOOAqACbPZChuufonNR+sJrQ0OB6EKMtLS0ZpPivGZCxHmSORVqaBdhA5bYMKzDji1lyPZjxv9kYYtf/L/ehDDAAACPTVSyPrPcdAAAAAElFTkSuQmCC>

I made a small mistake. The order of the alt text and the URL should be
reversed for consistency with L<>.

Re: Pre-RFC: images in Pod [ In reply to ]

leonerd at leonerd

Nov 16, 2021, 2:18 AM

Post #5 of 31 (1878 views)

On Mon, 15 Nov 2021 22:04:53 -0500
Dan Book <grinnz@gmail.com> wrote:

> I like the basic idea. The loss of sizing control would be
> unfortunate, but worked around by sizing the image you include as
> desired.

As you're already using a | symbol to separate the URL from alt-text
(though I see you swapped them later), could you not also use this for
sizing?

P<A little logo|http://url-to-my/logo.png|64x48>

(admittedly my email client seems to think that a | symbol is valid
inside a URL, so that might be a problem in itself. Hrm)

> A larger question is how to refer to images without an absolute URL
> as it relies on having external hosting for the image available. Most
> commonly images would be included with the CPAN distribution and
> displayed by metacpan so it's worth optimizing for that use case. I
> believe there was some discussion of this in the previous thread that
> it would be worthwhile to review.

Yes this - I'd quite often be wanting to include those images in the
dist tarball, rather than relying on some external site.

--
Paul "LeoNerd" Evans

leonerd@leonerd.org.uk | https://metacpan.org/author/PEVANS
http://www.leonerd.org.uk/ | https://www.tindie.com/stores/leonerd/

Re: Pre-RFC: images in Pod [ In reply to ]

arne-9544 at thaw

Nov 16, 2021, 4:56 AM

Post #6 of 31 (1878 views)

Paul LeoNerd Evans wrote:
>
> As you're already using a | symbol to separate the URL from alt-text
> (though I see you swapped them later), could you not also use this for
> sizing?

If there will be images, then having some way to size them seems sensible.

> P<A little logo|http://url-to-my/logo.png|64x48>
>
> (admittedly my email client seems to think that a | symbol is valid
> inside a URL, so that might be a problem in itself. Hrm)

According to RFC 3986 character definitions, the VERTICAL LINE is neither in the set of reserved nor unreserved characters, which means it is forbidden inside a URI if not escaped.

This is an issue in your email client. But I use an entirely different client than you do, and it exhibits the same issue. Using SPACE instead of VERTICAL LINE as the separator for the image size would avoid this. There is no history in perlpod of using multiple VERTICAL LINE as part of a single formatting code, so using a new delimination character for a new kind of attribute (the size) might be appropriate.

P<A little logo|http://url-to-my/logo.png 64x48>

--
Arne Johannessen
<https://arne.johannessen.de/>

Re: Pre-RFC: images in Pod [ In reply to ]

Nov 21, 2021, 6:42 PM

Post #7 of 31 (1877 views)

On Tue, 16 Nov 2021 10:18:03 +0000
"Paul \"LeoNerd\" Evans" <leonerd@leonerd.org.uk> wrote:

> On Mon, 15 Nov 2021 22:04:53 -0500
> Dan Book <grinnz@gmail.com> wrote:
>
> > I like the basic idea. The loss of sizing control would be
> > unfortunate, but worked around by sizing the image you include as
> > desired.
>
> As you're already using a | symbol to separate the URL from alt-text
> (though I see you swapped them later), could you not also use this for
> sizing?
>
> P<A little logo|http://url-to-my/logo.png|64x48>

I was a little bit worried that three positional parameters might be too
many, but now I think I'm OK with that. Most images probably won't need
it, but it's better to have this option than not.

Re: Pre-RFC: images in Pod [ In reply to ]

Nov 22, 2021, 5:51 PM

Post #8 of 31 (1877 views)

On Tue, Nov 16, 2021 at 01:56:00PM +0100, Arne Johannessen wrote:
> Paul LeoNerd Evans wrote:
> >
> > As you're already using a | symbol to separate the URL from alt-text
> > (though I see you swapped them later), could you not also use this for
> > sizing?
>
> If there will be images, then having some way to size them seems sensible.

An image already has an intrisic size, so IMO there's no point in
repeating that information inside the P<> element. In my understanding,
the main issue with images is when they are much bigger than the
containing document. This is when they need resizing for display purposes.

In the case of HTML, it's relatively easy to constrain an image to
be resized to the width of the container ("max-width: 100%") if
it's larger. If smaller, there is probably no need to resize it.
(Then more styling questions pop up: should it be centered?, etc.)

I think image size in pixels is a property of the image itself, and
needs no repeating in the POD. Its size when displayed in a formatted
document is an issue for the formatter to deal with.

POD is about content, and styling should be left to the formatters.

--
Philippe Bruhat (BooK)

Blood is thicker than water... so beware of thick relatives.
(Moral from Groo The Wanderer #18 (Epic))

Re: Pre-RFC: images in Pod [ In reply to ]

felipe at felipegasper

Nov 22, 2021, 6:05 PM

Post #9 of 31 (1877 views)

> On Nov 22, 2021, at 20:51, Philippe Bruhat (BooK) <book@cpan.org> wrote:
>
> On Tue, Nov 16, 2021 at 01:56:00PM +0100, Arne Johannessen wrote:
>> Paul LeoNerd Evans wrote:
>>>
>>> As you're already using a | symbol to separate the URL from alt-text
>>> (though I see you swapped them later), could you not also use this for
>>> sizing?
>>
>> If there will be images, then having some way to size them seems sensible.
>
> An image already has an intrisic size, so IMO there's no point in
> repeating that information inside the P<> element.

This isn’t true of vector images such as those from MermaidJS.

-FG

Re: Pre-RFC: images in Pod [ In reply to ]

grinnz at gmail

Nov 22, 2021, 6:35 PM

Post #10 of 31 (1877 views)

On Mon, Nov 22, 2021 at 8:51 PM Philippe Bruhat (BooK) <book@cpan.org>
wrote:

> On Tue, Nov 16, 2021 at 01:56:00PM +0100, Arne Johannessen wrote:
> > Paul LeoNerd Evans wrote:
> > >
> > > As you're already using a | symbol to separate the URL from alt-text
> > > (though I see you swapped them later), could you not also use this for
> > > sizing?
> >
> > If there will be images, then having some way to size them seems
> sensible.
>
> An image already has an intrisic size, so IMO there's no point in
> repeating that information inside the P<> element. In my understanding,
> the main issue with images is when they are much bigger than the
> containing document. This is when they need resizing for display purposes.
>
> In the case of HTML, it's relatively easy to constrain an image to
> be resized to the width of the container ("max-width: 100%") if
> it's larger. If smaller, there is probably no need to resize it.
> (Then more styling questions pop up: should it be centered?, etc.)
>

This is for use in POD sections, which do not contain such formatting
capability. Styling is entirely up to the HTML renderer which is largely
disconnected from the POD declarations. Image sizing seems somewhat more
technical.

I think image size in pixels is a property of the image itself, and
> needs no repeating in the POD. Its size when displayed in a formatted
> document is an issue for the formatter to deal with.
>
> POD is about content, and styling should be left to the formatters.
>

I would agree as I did earlier in this thread, but the proposed simple
extension to optionally provide this information seems fine to me for the
convenience of this common task.

-Dan

Re: Pre-RFC: images in Pod [ In reply to ]

Nov 23, 2021, 12:25 AM

Post #11 of 31 (1877 views)

On Mon, Nov 22, 2021 at 09:05:20PM -0500, Felipe Gasper wrote:
>
> > An image already has an intrisic size, so IMO there's no point in
> > repeating that information inside the P<> element.
>
> This isn’t true of vector images such as those from MermaidJS.

Vector images have a bouding box. It can be made to fit the container.

--
Philippe Bruhat (BooK)

To flaunt your strength is to make it your weakness.
(Moral from Groo The Wanderer #25 (Epic))

Re: Pre-RFC: images in Pod [ In reply to ]

kimoto.yuki at gmail

Jan 6, 2022, 6:01 PM

Post #12 of 31 (1835 views)

2021-11-16 19:18 Paul "LeoNerd" Evans <leonerd@leonerd.org.uk> wrote:

>
> P<A little logo|http://url-to-my/logo.png|64x48>
>
>
I have an idea to customize the width and height of the image.

In the current idea the first thing is the "alt" attribute, and the second
is URL.

P<A little logo|http://url-to-my/logo.png|64x48>

If it is changed to the following.

P<alt:"A little logo",width:64,height:48|http://url-to-my/logo.png
<http://url-to-my/logo.png%7C64x48>>

Re: Pre-RFC: images in Pod [ In reply to ]

grinnz at gmail

Jan 6, 2022, 6:20 PM

Post #13 of 31 (1835 views)

On Thu, Jan 6, 2022 at 9:01 PM Yuki Kimoto <kimoto.yuki@gmail.com> wrote:

>
> 2021-11-16 19:18 Paul "LeoNerd" Evans <leonerd@leonerd.org.uk> wrote:
>
>>
>> P<A little logo|http://url-to-my/logo.png|64x48>
>>
>>
> I have an idea to customize the width and height of the image.
>
> In the current idea the first thing is the "alt" attribute, and the second
> is URL.
>
> P<A little logo|http://url-to-my/logo.png|64x48>
>
> If it is changed to the following.
>
> P<alt:"A little logo",width:64,height:48|http://url-to-my/logo.png
> <http://url-to-my/logo.png%7C64x48>>
>

This seems more complex (does order matter? parsers need to ignore unknown
keys, additional escape mechanisms and delimiting rules are needed for the
alt text which don't have any precedent currently). I think the idea of
three sections in the style of existing directives is fine.

-Dan

Re: Pre-RFC: images in Pod [ In reply to ]

kimoto.yuki at gmail

Jan 6, 2022, 8:43 PM

Post #14 of 31 (1835 views)

2022-1-7 11:20 Dan Book <grinnz@gmail.com> wrote:

> On Thu, Jan 6, 2022 at 9:01 PM Yuki Kimoto <kimoto.yuki@gmail.com> wrote:
>
>>
>> 2021-11-16 19:18 Paul "LeoNerd" Evans <leonerd@leonerd.org.uk> wrote:
>>
>>>
>>> P<A little logo|http://url-to-my/logo.png|64x48>
>>>
>>>
>> I have an idea to customize the width and height of the image.
>>
>> In the current idea the first thing is the "alt" attribute, and the
>> second is URL.
>>
>> P<A little logo|http://url-to-my/logo.png|64x48>
>>
>> If it is changed to the following.
>>
>> P<alt:"A little logo",width:64,height:48|http://url-to-my/logo.png
>> <http://url-to-my/logo.png%7C64x48>>
>>
>
> This seems more complex (does order matter? parsers need to ignore unknown
> keys, additional escape mechanisms and delimiting rules are needed for the
> alt text which don't have any precedent currently). I think the idea of
> three sections in the style of existing directives is fine.
>
> -Dan
>

Dan

OK.

My concern is, to be honest, that P <> is actually implemented.

It is desirable to be flexible even if it is a little complicated because
there is actual demand.

- width
- height
- max-width
- alt
- display(block)

For example,

=begin html

<img alt="Foo" style="max-width:100%; width:640px; display:block;">

=end html

Is there an implementation proposal we can agree on to proceed to pre-RFC?

Re: Pre-RFC: images in Pod [ In reply to ]

Jun 9, 2022, 3:24 PM

Post #15 of 31 (1574 views)

Revisiting this after something of a gap … here’s the basic case:

P<There can be only one|https://highlander.org/macleod.png>

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.

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.

Seems sensible to allow optional dimensions with an additional parameter:

P<There can be only one|https://highlander.org/macleod.png|640x480>

Q3: I often just put just a width on images, so it should probably allow that. I.e. P<alt text|https://foo.com/bar.png|320>. Should any other format of dimensions be supported?

Neil

Re: Pre-RFC: images in Pod [ In reply to ]

grinnz at gmail

Jun 9, 2022, 3:57 PM

Post #16 of 31 (1574 views)

On Thu, Jun 9, 2022 at 6:25 PM Neil Bowers <neilb@neilb.org> wrote:

> Revisiting this after something of a gap … here’s the basic case:
>
> P<There can be only one|https://highlander.org/macleod.png>
>
> 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.
>

This isn't up to the formatter, it should always render the equivalent of
the image tag. "can't be displayed" would be discovered when the browser
attempts to fetch the image and whatever normal behavior would occur.

> 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.
>

This seems like a common enough case to consider and was discussed before.
But the exact details would get hairy as you say. For example, would it be
relative to the root of the dist (which would work for metacpan, which
renders using the dist tarball) or relative to a sharedir (which would work
after installation, such as perldoc.perl.org and pod2html, but way too
complicated for the pod spec)?

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

Optimizing for specifying width seems appropriate to me.

-Dan

Re: Pre-RFC: images in Pod [ In reply to ]

jkeenan at pobox

Jun 9, 2022, 5:02 PM

Post #17 of 31 (1574 views)

On 6/9/22 18:24, Neil Bowers wrote:
> [snip]
>
> Seems sensible to allow optional dimensions with an additional parameter:
>
> P<There can be only one|https://highlander.org/macleod.png|640x480>
>

When I click on that highlander.org link, Firefox tells me, "Warning:
Potential Security Risk Ahead".

So perhaps we should choose a different sample link.

Re: Pre-RFC: images in Pod [ In reply to ]

perl5-porters at perl

Jun 9, 2022, 6:13 PM

Post #18 of 31 (1574 views)

* Neil Bowers <neilb@neilb.org> [2022-06-09 23:24:53 +0100]:

> Revisiting this after something of a gap ? here?s the basic case:
>
> P<There can be only one|https://highlander.org/macleod.png>
>
> 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.

"alt" text, just like in HTML is my suggestion.

However, if something is being displayed in the gopherverse, for example,
someone way want the URL available to download (e.g. in lynx).

>
> 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.

Some joker is going to recommend supporting embedded data URLs and sprites,
I can see it now. <_< ... >_> ..

>
> Seems sensible to allow optional dimensions with an additional parameter:
>
> P<There can be only one|https://highlander.org/macleod.png|640x480>

Since the primary target outside of the terminal is going to be HTML, may
want to throw some text flow information in there. And someone is inevitably
going to want to put a L<> around it.

>
> Q3: I often just put just a width on images, so it should probably allow that. I.e. P<alt text|https://foo.com/bar.png|320>. Should any other format of dimensions be supported?

LaTeX might be useful to anticipate the extremes of what might be "requested":

Basic example,

\begin{figure}[h]
\includegraphics[width=9cm]{sun}
\end{figure}

https://www.resurchify.com/latex_tutorial/latex_images.php

I do caution that allowing images on a site like MetaCPAN is going to invite
abuse. It happens. And this is going to invite minders; and this is going to
invite screams of censorship, etc. Just pointing that out before Pandora's
Box is opened a little more here.

Cheers,
Brett

>
> Neil

--
--
oodler@cpan.org
oodler577@sdf-eu.org
SDF-EU Public Access UNIX System - http://sdfeu.org
irc.perl.org #openmp #pdl #native

Re: Pre-RFC: images in Pod [ In reply to ]

tony at develop-help

Jun 9, 2022, 9:37 PM

Post #19 of 31 (1574 views)

On Thu, Jun 09, 2022 at 06:57:58PM -0400, Dan Book wrote:
> On Thu, Jun 9, 2022 at 6:25 PM Neil Bowers <neilb@neilb.org> wrote:
>
> > Revisiting this after something of a gap … here’s the basic case:
> >
> > P<There can be only one|https://highlander.org/macleod.png>
> >
> > 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.
> >
>
> This isn't up to the formatter, it should always render the equivalent of
> the image tag. "can't be displayed" would be discovered when the browser
> attempts to fetch the image and whatever normal behavior would occur.

Not every renderer produces HTML as the final form.

Rendering to PDF, whether it's via LateX or HTML, will need access to
the images to finish the process.

Tony

Re: Pre-RFC: images in Pod [ In reply to ]

perl5-porters at perl

Jun 9, 2022, 9:45 PM

Post #20 of 31 (1574 views)

On Fri, 10 Jun 2022 at 09:14, Oodler 577 via perl5-porters <
perl5-porters@perl.org> wrote:

> I do caution that allowing images on a site like MetaCPAN is going to
> invite
> abuse. It happens. And this is going to invite minders; and this is going
> to
> invite screams of censorship, etc. Just pointing that out before Pandora's
> Box is opened a little more here.
>

It might, yes, but a bit late for that - MetaCPAN already allows images and
HTML, has done for years.

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

Re: Pre-RFC: images in Pod [ In reply to ]

oodler577 at sdf-eu

Jun 10, 2022, 6:42 PM

Post #21 of 31 (1574 views)

* Tom Molesworth via perl5-porters <perl5-porters@perl.org> [2022-06-10 12:45:53 +0800]:

> On Fri, 10 Jun 2022 at 09:14, Oodler 577 via perl5-porters <
> perl5-porters@perl.org> wrote:
>
> > I do caution that allowing images on a site like MetaCPAN is going to
> > invite
> > abuse. It happens. And this is going to invite minders; and this is going
> > to
> > invite screams of censorship, etc. Just pointing that out before Pandora's
> > Box is opened a little more here.
> >
>
> It might, yes, but a bit late for that - MetaCPAN already allows images and
> HTML, has done for years.
>
> =for html <img src="...">

Cool! So why are we discussing this, then?

Brett

--
--
oodler@cpan.org
oodler577@sdf-eu.org
SDF-EU Public Access UNIX System - http://sdfeu.org
irc.perl.org #openmp #pdl #native

Re: Pre-RFC: images in Pod [ In reply to ]

curtis.poe at gmail

Jun 10, 2022, 10:43 PM

Post #22 of 31 (1574 views)

On Sat, Jun 11, 2022 at 3:45 AM Oodler 577 <oodler577@sdf-eu.org> wrote:

> > It might, yes, but a bit late for that - MetaCPAN already allows images
> and
> > HTML, has done for years.
> >
> > =for html <img src="...">
>
> Cool! So why are we discussing this, then?
>

Because POD is used in places other than MetaCPAN, and it's output in
formats other than HTML.

--
Curtis "Ovid" Poe
CTO, All Around the World
World-class software development and consulting
https://allaroundtheworld.fr/

Re: Pre-RFC: images in Pod [ In reply to ]

Jun 11, 2022, 12:25 AM

Post #23 of 31 (1574 views)

Brett asked:
> Cool! So why are we discussing this, then?

Curtis replied:
> Because POD is used in places other than MetaCPAN, and it's output in formats other than HTML.

If you want to include diagrams in your CPAN distribution’s documentation, right now you’ve to get it online somewhere. There are plenty of options, such imgur (just picking an example that I’ve used), but now one of your distribution’s assets is not bundled with it. You _could_ include it in the dist, put your dist on github and use a raw content URL, but that’s a bit nasty to be explaining to casual CPAN authors.

And your diagrams might evolve over releases. Being able to bundle images in the distribution, knowing that the CPAN ecosystem can handle them, means you don’t need to worry about versioning the images – the right version is included for the version that a user is looking at.

Neil

Re: Pre-RFC: images in Pod [ In reply to ]

tony at develop-help

Jun 11, 2022, 12:43 AM

Post #24 of 31 (1574 views)

On Thu, Jun 09, 2022 at 11:24:53PM +0100, Neil Bowers wrote:
> 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 problem I see with only http URLs is, at least for CPAN
distributions, you can't link to the image included in the
distribution.

You *could* link to the image in some previous version, or on github,
but relative links keep your distribution more self-contained.

It also reduces privacy exposure - if say metacpan kept linking
through to some linked image (rather than to a cached copy) a CPAN
author could track views of their documentation on metacpan. This is
a problem with the existing =for html method.

Tony

Re: Pre-RFC: images in Pod [ In reply to ]

perl5-porters at perl

Jun 11, 2022, 1:11 AM

Post #25 of 31 (1574 views)

Hi there,

On Sat, 11 Jun 2022, Tony Cook wrote:

> The problem I see with only http URLs is, at least for CPAN
> distributions, you can't link to the image included in the
> distribution.

Does the planet not have a way of including a diagram in a document
without resorting to HTTP?

It might be very tempting but will it not make things more fragile?

The problem I see with URLs all the time is built-in obsolescence.
Can't seem to read online docs anywhere thesedays without running
into a bunch of dead links.

--

73,
Ged.