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

I=E2=80=99m not sure that I understand your argument and it feel a bit of a s=
traw man - I=E2=80=99m targeting specifically html, latex, and pdf as the gr=
aphic backends, and have in mind markdown and xml as easily supported too. T=
he proposal is that title and image are always shown together, or always ign=
ored together. For html and others, P<> doesn=E2=80=99t need to be wrapped i=
n =3Dbegin, that=E2=80=99s the whole point of it to not care about specific f=
ormat, and only care for man pages when there is a gracious fallback.=20

/dk

> On 1 Oct 2020, at 12.42, Patrice Dumas <[email protected]> wrote:
>=20
> =EF=BB=BFOn Thu, Oct 01, 2020 at 11:35:45AM +0200, Dmitry Karasik wrote:
>> Hello,
>>=20
>> I've proposed addition of images to pod, as discussed at [1], and would l=
ike to
>> ask for some more discussion here as well The idea is rather simple, to
>> introduce a P<> tag in two forms, P<foo.png> and P<title|foo.png>, that w=
ould
>> get converted to image in graphic formats, and ignored otherwise.
>>=20
>> The image URI would be related either to the pod file location (without l=
eading
>> /) or to the distro root (with leading /), that would allow referencing b=
oth
>> locally installed images as well as web views on github and metacpan.
>>=20
>> Image title would get converted into <figcaption> in html, if present.
>>=20
>> In case a graceful fallback is needed by an author, the following trick c=
ould be
>> used:
>=20
> I am not sure that it is good enough.  There is not only html and text
> as output format, the proposal seems a bit too format specific to me. =20
> One option is to use the "title" in formats that cannot render the=20
> image (text, man, for example).  The downside is that if one want to=20
> have the title in html as alt/figcaption, but not rendered in the text
> case, one would need to use a specific format block for html too
> and would require format blocks for all the formats.
>=20
> In that case there could be simply, if it is ok to have title as
> figcaption in html and title used in pllace of the image in text
>=20
> P<title|graph.png>
>=20
> But if one want to do a specific formatting for text, for example, it
> could be the following, with the downside that the other formats, even
> those which would be able to handle P<title|graph.png> will have to=20
> have something explicitly specified:
>=20
> =3Dbegin :html
>=20
> P<title|graph.png>
>=20
> =3Dend :html
>=20
> =3Dbegin text
>=20
> y  **
> |  **=20
> |**
> |----------> x
>=20
> =3Dend text
>=20
>=20
>>=20
>> P<graph.png>
>>=20
>> =3Dbegin text
>>=20
>> ^ y  **
>> |  **=20
>> |**
>> |----------> x
>>=20
>> 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 i=
s
>> undecided yet.=20
>>=20
>> Let's discuss this.
>>=20
>> [1] https://github.com/Perl/perl5/issues/18169
>>=20
>>=20
>> --=20
>> Sincerely,
>>    Dmitry Karasik