Pod::Simple issues

[Karl Williamson]

I stumbled across a bug in Pod::Simple the other day: It does not create
the promised {'raw'} structure element usable by parsers for L<>
constructs if they occur within another formatting code, such as the
fairly common C<L<foo::bar>>.

I figured out a way to fix this, but in doing so I realized that
Pod::Simple does not catch nested L<... L<...>...>, contrary to the
specification:

Authors must not nest L<...> codes. For example, "L<The L<Foo::Bar>
man page>" should be treated as an error.

Pod::Simple does not treat this as an error. I think it should. Is
there any disagreement?

Rather than aborting parsing at the point where this occurs, I think it
should continue on, but generate an errors section, like it does for
most other errors. Properly handling nested L<> is tricky. Currently,
it sort of works, but the generated output for html doesn't link
properly, as one can't nest links in html. I came up with this
tentative message, which perhaps explains too much of how I was able to
easily keep parsing with this error, and still fix the original {'raw'}
bug; improved wording welcome:

Nested L<> are illegal. Pretending inner one is X<> so can continue
looking for other errors.

[Karl Williamson]

On 04/29/2016 01:58 PM, Shawn H Corey wrote:

> On Fri, 29 Apr 2016 13:34:21 -0600
> Karl Williamson <pub...@khwilliamson.com> wrote:
>
>> Nested L<> are illegal. Pretending inner one is X<> so can
>> continue looking for other errors.
>

> That would be Z<>
>
>

That would generate an additional warning that it wasn't empty. The
mechanism is to divert the incoming text into the X<> so it doesn't do
anything bad. I suppose we could set a flag for the Z<> to suppress the
warning.

[Russ Allbery]

Karl Williamson <pub...@khwilliamson.com> writes:

> Rather than aborting parsing at the point where this occurs, I think it
> should continue on, but generate an errors section, like it does for most
> other errors.

This will cause a hard failure in pod2man and pod2text by default, since
they do not generate ERRORS sections by default (you have to request that
behavior with a flag). They used to generate ERRORS sections, which made
people very unhappy because they didn't want their documents published
with sections saying the documents were bad, and after a lot of previous
discussion I changed the default to fail on generation. (I'd really
rather not reverse that decision at this point.)

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

[Karl Williamson]

On 04/29/2016 04:33 PM, Russ Allbery wrote:
> Karl Williamson <pub...@khwilliamson.com> writes:
>
>> Rather than aborting parsing at the point where this occurs, I think it
>> should continue on, but generate an errors section, like it does for most
>> other errors.
>
> This will cause a hard failure in pod2man and pod2text by default, since
> they do not generate ERRORS sections by default (you have to request that
> behavior with a flag). They used to generate ERRORS sections, which made
> people very unhappy because they didn't want their documents published
> with sections saying the documents were bad, and after a lot of previous
> discussion I changed the default to fail on generation. (I'd really
> rather not reverse that decision at this point.)
>

I'm not sure I understand what "fail on generation" means. I think it
might mean just not generate a pod, rather than generate one with an
error section. What I was intending was to add a scream() call. The
only failure that I saw in Pod::Simple that stopped parsing was when it
was clear the encoding of the pod was not understandable, so there was
no point in continuing. So I don't understand what you do, unless it is
to die on pod errors, or some such.

I tend to agree about not reversing your earlier decision.

[Russ Allbery]

Karl Williamson <pub...@khwilliamson.com> writes:

> I'm not sure I understand what "fail on generation" means. I think it
> might mean just not generate a pod, rather than generate one with an error
> section.

Correct -- it will exit with an error message.

lothlorien:~$ cat > foo.pod
=item foo

Invalid POD.
lothlorien:~$ pod2man foo.pod > foo.1
foo.pod around line 1: '=item' outside of any '=over'
foo.pod around line 1: =over without closing =back
POD document had syntax errors at /usr/bin/pod2man line 68.
lothlorien:~$ echo $?
255

> What I was intending was to add a scream() call. The only failure that I
> saw in Pod::Simple that stopped parsing was when it was clear the
> encoding of the pod was not understandable, so there was no point in
> continuing. So I don't understand what you do, unless it is to die on
> pod errors, or some such.

Correct, the scripts die on POD errors, unless the --errors flag is used
to request some other behavior.

-errors=style
Set the error handling style. "die" says to throw an exception on
any POD formatting error. "stderr" says to report errors on
standard error, but not to throw an exception. "pod" says to
include a POD ERRORS section in the resulting documentation
summarizing the errors. "none" ignores POD errors entirely, as
much as possible.

The default is "die".

(Now let me go fix the missing - in the pod2man docs....)