From Ulrich.Windl@rz.uni-regensburg.de

Hi!

This is for perl 5.10.0 and 5.18.2​:
I see some complaints form podchecker that are not really useful​:

"*** WARNING​: node 'RFC 2445/4.8.2.7 Time Transparency' contains non-escaped | or / at line..."
triggered by "(See L<RFC 2445/4.8.2.7 Time Transparency> for details)."

"man perlpod" isn't very helpful on this​: Putting "4.8.2.7 Time Transparency" in double-quotes doesn't help.

--
"*** WARNING​: (section) in 'omnirpt(1)' deprecated at line..."
triggered by "L<omnirpt(1)>". The solution "L<name/sec>" does not work, because it will produce "sec in name" as output.
--
"*** WARNING​: multiple occurrence of link target '#' at line - in file ..."
Here the problem is that no line numbers are part of the warning. Also there is no description of "link target" in perlpod. I suspect the problem comes from these items​:
=item 10. C<# Errors>

=item 11. C<# Warnings>
--
Likewise "*** WARNING​: multiple occurrence of link target 'Session' at line - in file ...", possibly triggered by these items​:

=item 3. C<Session ID>

=item 4. C<Session Type>

So I think if perl (perldoc) collects the "Link targets" it should also collect the source line numbers to be able to use those in case of problems related to the targets.

"man perlpod" should mention the concept "link target".

There should be a valid example (in man perlpod) how to refer to another manpage, as well as to some external document (like the RFC).

Possibly the exact semantics of "stuff" for =item in perlpod should be explained, specifically ist relation to link targets.

Regards,
Ulrich

From @jkeenan

On Mon Mar 14 05​:33​:48 2016, Ulrich.Windl@​rz.uni-regensburg.de wrote​:

Hi!

This is for perl 5.10.0 and 5.18.2​:
I see some complaints form podchecker that are not really useful​:

"*** WARNING​: node 'RFC 2445/4.8.2.7 Time Transparency' contains non-
escaped | or / at line..."
triggered by "(See L<RFC 2445/4.8.2.7 Time Transparency> for
details)."

"man perlpod" isn't very helpful on this​: Putting "4.8.2.7 Time
Transparency" in double-quotes doesn't help.

--
"*** WARNING​: (section) in 'omnirpt(1)' deprecated at line..."
triggered by "L<omnirpt(1)>". The solution "L<name/sec>" does not
work, because it will produce "sec in name" as output.
--
"*** WARNING​: multiple occurrence of link target '#' at line - in file
..."
Here the problem is that no line numbers are part of the warning. Also
there is no description of "link target" in perlpod. I suspect the
problem comes from these items​:
=item 10. C<# Errors>

=item 11. C<# Warnings>
--
Likewise "*** WARNING​: multiple occurrence of link target 'Session' at
line - in file ...", possibly triggered by these items​:

=item 3. C<Session ID>

=item 4. C<Session Type>
---

1. Can you attach the file containing documentation in POD format which you believe 'podchecker' is handling incorrectly?

2. Also, please note that the 'podchecker' program is part of the Pod-Checker distribution, which is primarily maintained on CPAN, not in perl5 blead. To report a bug in that distribution, you should file a report at​:
https://rt.cpan.org/Public/Dist/Display.html?Name=Pod-Checker

Thank you very much.
Jim Keenan

So I think if perl (perldoc) collects the "Link targets" it should
also collect the source line numbers to be able to use those in case
of problems related to the targets.

"man perlpod" should mention the concept "link target".

There should be a valid example (in man perlpod) how to refer to
another manpage, as well as to some external document (like the RFC).

Possibly the exact semantics of "stuff" for =item in perlpod should be
explained, specifically ist relation to link targets.

Regards,
Ulrich

--
James E Keenan (jkeenan@​cpan.org)

The RT System itself - Status changed from 'new' to 'open'

From Ulrich.Windl@rz.uni-regensburg.de

Hi!

An update​:

I changed the problematic L<>s into C<>s as suggested by some Google and cpan wisdom. However, I would prefer a link to be a link, even if the POD processor does not know what to do. This is, because I want to semantically mark the text, not to create a specific look (a L<> is another (part of a) document, while C<> is some literal thing).

I also changed the items to something like "=item 10. C<S<# Errors>>" which results in the desired output, but still triggers a "*** WARNING​: multiple occurrence of link target '#' at line - in file ...". This looks like the result of some bad design in anchor creation.

Regards,
Ulrich

From @jkeenan

On Tue Mar 15 05​:50​:12 2016, Ulrich.Windl@​rz.uni-regensburg.de wrote​:

Hi!

An update​:

I changed the problematic L<>s into C<>s as suggested by some Google
and cpan wisdom. However, I would prefer a link to be a link, even if
the POD processor does not know what to do. This is, because I want to
semantically mark the text, not to create a specific look (a L<> is
another (part of a) document, while C<> is some literal thing).

I also changed the items to something like "=item 10. C<S<# Errors>>"
which results in the desired output, but still triggers a "***
WARNING​: multiple occurrence of link target '#' at line - in file
...". This looks like the result of some bad design in anchor
creation.

Regards,
Ulrich

As noted previously, any change would have to be made upstream in the Pod-Checker distribution​: https://rt.cpan.org/Public/Dist/Display.html?Name=Pod-Checker

Closing this ticket.

--
James E Keenan (jkeenan@​cpan.org)

@jkeenan - Status changed from 'open' to 'rejected'