Bug #104696 for Module-Metadata: [PATCH] Fix some POD syntax errors.

Mon May 25 15:38:41 2015 roam [...] ringlet.net - Ticket created

From:	roam [...] ringlet.net
Subject:	[PATCH] Fix some POD syntax errors.

Hi, First of all, thanks for writing and maintaining Module-Metadata! What do you think about the following trivial patch that is about to be applied to the Debian package? It fixes a couple of POD syntax errors - well, actually all it does is escape a couple of '<' and '>' characters used within other POD constructs. It's true that recent versions of perldoc display the POD correctly, but still it might be just a little bit better if it were also strictly compliant. Just in case something happens to the patch in transit, you may also view it in the Debian Perl Group's Git repository at https://anonscm.debian.org/cgit/pkg-perl/packages/libmodule-metadata-perl.git/plain/debian/patches/01-pod-syntax.patch Thanks in advance for your attention, and keep up the great work! G'luck, Peter Pentchev, Debian Perl Group

Mon May 25 15:38:45 2015 roam [...] ringlet.net - Correspondence added

Here's the patch.

Message body is not shown because sender requested not to inline it.

Mon May 25 15:38:45 2015 The RT System itself - Status changed from 'new' to 'open'

Mon May 25 16:11:15 2015 ether [...] cpan.org - Correspondence added

RT-Send-CC:

roam [...] ringlet.net

On 2015-05-25 12:38:41, ROAM wrote: Show quoted text

> It fixes a couple of POD syntax > errors - well, actually all it does is escape a couple of '<' and '>' > characters used within other POD constructs. It's true that recent > versions of perldoc display the POD correctly, but still it might be > just a little bit better if it were also strictly compliant.

I'm confused by this. Every < and > character should be parsed correctly when inside a C<< >> construct, so why is there a need to escape it again? Can you clarify what errors you're seeing, and what versions of pod parsers you're using?

Mon May 25 16:56:01 2015 ether [...] cpan.org - Taken

Mon May 25 17:35:24 2015 roam [...] ringlet.net - Correspondence added

На пон май 25 16:11:15 2015, ETHER написа: Show quoted text

> On 2015-05-25 12:38:41, ROAM wrote:

> > It fixes a couple of POD syntax > > errors - well, actually all it does is escape a couple of '<' and '>' > > characters used within other POD constructs. It's true that recent > > versions of perldoc display the POD correctly, but still it might be > > just a little bit better if it were also strictly compliant.

> > I'm confused by this. Every < and > character should be parsed > correctly when inside a C<< >> construct, so why is there a need to > escape it again? > > Can you clarify what errors you're seeing, and what versions of pod > parsers you're using?

Oof, of course you're right - and I just learned something new about POD, thanks! :) The problem seems to lie with the "podlint" utility from Pod-POM; even in the most recent version, 0.29, Pod-POM still flags << ... > ... >> with an error. Now that you've pointed me in the right direction, it seems that this has already been reported in #48812 and also a similar problem has been reported in #53335; unfortunately the patch from #53335 does not seem to fix this particular problem (with no encloding L<>). I'll dig deeper into it, this time from Pod-POM's side... thanks, and sorry for the confusion; that's what comes from blindly following code checkers, I guess. Still, what do you think about the other part of the patch (see attached) that only quotes the <..> characters around the authors' e-mail addresses? G'luck, Peter

Subject:

01-pod-syntax.patch

Description: Fix some POD syntax errors. Forwarded: https://rt.cpan.org/Ticket/Display.html?id=104696 Bug: https://rt.cpan.org/Ticket/Display.html?id=104696 Author: Peter Pentchev <roam@ringlet.net> Last-Update: 2015-05-26 --- a/lib/Module/Metadata.pm +++ b/lib/Module/Metadata.pm @@ -1004,10 +1004,10 @@ =head1 AUTHOR Original code from Module::Build::ModuleInfo by Ken Williams -<kwilliams@cpan.org>, Randy W. Sims <RandyS@ThePierianSpring.org> +E<lt>kwilliams@cpan.orgE<gt>, Randy W. Sims E<lt>RandyS@ThePierianSpring.orgE<gt> -Released as Module::Metadata by Matt S Trout (mst) <mst@shadowcat.co.uk> with -assistance from David Golden (xdg) <dagolden@cpan.org>. +Released as Module::Metadata by Matt S Trout (mst) E<lt>mst@shadowcat.co.ukE<gt> with +assistance from David Golden (xdg) E<lt>dagolden@cpan.orgE<gt>. =head1 COPYRIGHT & LICENSE

Mon May 25 17:39:37 2015 ether [...] cpan.org - Correspondence added

On 2015-05-25 14:35:24, ROAM wrote: Show quoted text

> Oof, of course you're right - and I just learned something new about > POD, thanks! :) > > The problem seems to lie with the "podlint" utility from Pod-POM; even in > the most recent version, 0.29, Pod-POM still flags << ... > ... >> with > an error. Now that you've pointed me in the right direction, it seems > that this has already been reported in #48812 and also a similar problem > has been reported in #53335; unfortunately the patch from #53335 does not > seem to fix this particular problem (with no encloding L<>).

Thanks, I'll watch those tickets! Show quoted text

> I'll dig deeper into it, this time from Pod-POM's side... thanks, and > sorry for the confusion; that's what comes from blindly following code > checkers, I guess. Still, what do you think about the other part of > the patch (see attached) that only quotes the <..> characters around > the authors' e-mail addresses?

As far as I know, the current docs are syntactically valid. This distribution has a release test that uses Test::Pod to check for bad syntax, and the test passes. Moreover, 'perldoc perlpod' says this: "E<escape>" -- a character escape Very similar to HTML/XML "&foo;" "entity references": * "E<lt>" -- a literal < (less than) * "E<gt>" -- a literal > (greater than) * "E<verbar>" -- a literal | (vertical bar) * "E<sol>" -- a literal / (solidus) The above four are optional except in other formatting codes, notably "L<...>", and when preceded by a capital letter.

Tue Jun 02 16:06:33 2015 ether [...] cpan.org - Status changed from 'open' to 'stalled'

Bug #104696 for Module-Metadata: [PATCH] Fix some POD syntax errors.

Maintainer(s)' notes