Re: Pod::Simple issues
Karl Williamson 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)
--
#!/usr/bin/perl -- Russ Allbery, Just Another Perl Hacker
$^=q;@!>~|{>krw>yn{u<$$<[~|| 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
Re: Pod::Simple issues
On 04/29/2016 04:33 PM, Russ Allbery wrote: Karl Williamson 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.
Re: Pod::Simple issues
Karl Williamson 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<$$<[~|| 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
Re: Pod::Simple issues
On 04/29/2016 01:58 PM, Shawn H Corey wrote: On Fri, 29 Apr 2016 13:34:21 -0600 Karl Williamson 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.
Re: Pod::Simple issues
On Fri, 29 Apr 2016 13:34:21 -0600 Karl Williamson wrote: >Nested L<> are illegal. Pretending inner one is X<> so can > continue looking for other errors. That would be Z<> -- Don't stop where the ink does. Shawn
