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

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

Thread Previous | Thread Next
From:
Russ Allbery
Date:
October 1, 2020 16:28
Subject:
Re: [feature] Add =image to perl pod #18169
Message ID:
877ds9digf.fsf@hope.eyrie.org
Dmitry Karasik <dmitry@karasik.eu.org> writes:

> I've proposed addition of images to pod, as discussed at [1], and would
> like 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 would get converted to image in graphic formats,
> and ignored otherwise.

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.

I suspect what people care the most about is figures, which would argue
for the proposal that you have in the title (=image) instead of P<>.

> In case a graceful fallback is needed by an author, the following trick
> could be used:

> P<graph.png>

> =begin text

> ^ y  **
> |  ** 
> |**
> |----------> x

This doesn't work with *roff output.

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.

I wonder if it would make sense to do something like:

=image graph.png

  ^ y  **
  |  ** 
  |**
  |----------> x

=endimage

This a bit ugly, but it means that a formatter that ignores unknown
command paragraphs will display the fallback, which is probably the
backwards compatibility behavior you want.

Not sure how best to handle the title.  The cleanest way from the
perspective of a POD formatter is probably to add =imagetitle as well
(valid only inside an =image/=endimage pair) rather than trying to parse
the argument to =image.

-- 
#!/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

Thread Previous | Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About