Front page | perl.pod-people | Postings from October 2020

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

From:
Russ Allbery
Date:
October 1, 2020 19:17
Subject:
Re: [feature] Add =image to perl pod #18169
Message ID:
878scpbvsy.fsf@hope.eyrie.org
Dmitry Karasik <dmitry@karasik.eu.org> writes:

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

I don't have a strong opinion because I don't maintain any graphical POD
formatters and thus will only be working with the alternative text, but I
think this is ambiguous.  It's not at all clear what, say, an HTML
formatter should do with those two examples.

I think you may be assuming there would be some special handling of P<> in
a paragraph by itself as distinct from P<> in a paragraph with surrounding
text, but if so I think that would be the first place in POD where a
formatting code is handled differently based on its surrounding context.
I'm not sure that's a good precedent to set.  It's the sort of hidden
complexity that makes implementation a bit harder.  Plus, the author may
have intended to have a paragraph consisting only of an emoji and would be
quite surprised if that emoji turned into a figure!

My preference is therefore for some method of markup that would make it
explicit whether the image is intended to be inline or set off in a
figure, because these are going to require different handling in a lot of
output formats.

(Also, and I realize this was only an example, but I would not use images
to show mathematical formulas.  For HTML output, MathJax would produce
much better results.  That's a different topic of discussion, though, and
I'm not volunteering to implement eqn support in Pod::Man....)

--
#!/usr/bin/perl -- Russ Allbery, Just Another Perl Hacker
$^=q;@!>~|{>krw>yn{u<$$<[~||<Juukn{=,<S~|}<Jwx}qn{<Yn{u<Qjltn{ > 0gFzD gD, 00Fz, 0,,( 0hF 0g)F/=, 0> "L$/GEIFewe{,$/ 0C$~> "@=,m,|,(e 0.), 01,pnn,y{
rw} >;,$0=q,$,,($_=$^)=~y,$/ C-~><@=\n\r,-~$:-u/ #y,d,s,(\$.),$1,gee,print