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

Dmitry Karasik <[email protected]> writes:

> 1) Full syntax (somewhat YAML-inspired)

> =begin image

> src: file.png
> title: Figure.1
> comment:
> 	This is a multi-line
> 	comment. Must start end end with newline.
> 	Prefix spaces are skipped.

> resolution: 120
> whatever: value

> text:
> 	This is fallback text
> 	shown where graphics is unavailable
> 	but the formatter is smart and knows
> 	the =image tag.

> =end image

Hm, using =begin/=end as an extension mechanism is an interesting idea.
It's unfortunate that limitations in the existing mechanism mean that a
formatter still has to understand the extension to show the fallback text,
but that may not be a significant problem.

I have mixed feelings about introducing new syntax into POD to avoid using
command paragraphs.  I'm also a bit worried about adding a new ad hoc
configuration language rather than using some existing one with a
specification and existing parsers.  There are a lot of details and edge
cases in parsing rules, and a new ad hoc syntax either needs a detailed
specification (which is sort of annoying for everyone) or runs the risk
that different parsers will interpret it differently.  The merit in using
command paragraphs is that Pod::Simple and friends already know how to
parse them.

Unfortunately, the only other non-ad-hoc syntax that has a parser in Perl
core that I know of is JSON, and I certainly wouldn't want to use JSON
here.

I think there is some merit to making your YAML-inspired syntax just be
YAML if you go down that route so that parsers can reuse a YAML parser,
although I understand why the complexity of YAML isn't appealing, and that
also has weird implications for Perl core since introducing a YAML module
into Perl core is going to be unappealing, but POD parsing currently lives
in core.

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