Re: AW: Working on CPAN Testers fails for Pod::Simple::Search
On 04/24/2016 11:34 PM, Marek Rouchal wrote: Does this mean that there is a "find"-like function in Pod::Simple that replaces Pod::Find? That would be an opportunity to discontinue Pod::Find along with Pod::Parser... -Marek Looking at the man page, it looks like Pod::Simple::Search does a similar function as Pod::Find does
Pod::Simple issues
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>.
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
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.
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
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: Working on CPAN Testers fails for Pod::Simple::Search
On Apr 23, 2016, at 9:45 AM, Neil Bowers wrote: > I talked this through with RJBS, who suggested the order should instead be: > > .pod .pm .pl .plx > > David, you added the comment to the code that’s mentioned above. Was there a > reason you added that comment, or were you just commenting on what the code > was doing? (like much of this module, it’s somewhat opaque :-) I suspect I was just trying to get both functions to prefer things in the same order. I agree with Rik’s suggested ordering, however, especially if it makes the bloody tests pass. Anyone object to making Neil a committer and co-maint on Pod-Simple? (I’m hoping Neil doesn’t object.) The canonical repository is here: https://github.com/perl-pod/pod-simple/ Best, David
Re: Working on CPAN Testers fails for Pod::Simple::Search
On Apr 29, 2016, at 11:41 AM, Karl Williamson wrote: > Looking at the man page, it looks like Pod::Simple::Search does a similar > function as Pod::Find does Yes, and it has been there since forever. Best, David
Re: Working on CPAN Testers fails for Pod::Simple::Search
* "David E. Wheeler" [2016-04-29T16:43:03] > Anyone object to making Neil a committer and co-maint on Pod-Simple? (I’m > hoping Neil doesn’t object.) The canonical repository is here: No objection, and I preemptively overrule Neil's potential objection. -- rjbs signature.asc Description: Digital signature
Re: Working on CPAN Testers fails for Pod::Simple::Search
On Fri, Apr 29, 2016 at 1:54 PM, Ricardo Signes wrote: > * "David E. Wheeler" [2016-04-29T16:43:03] > > Anyone object to making Neil a committer and co-maint on Pod-Simple? (I’m > > hoping Neil doesn’t object.) The canonical repository is here: > > No objection, and I preemptively overrule Neil's potential objection. > I very much welcome it!
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 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:
> 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
