hyperlinks in pod

jpl has asked for the wisdom of the Perl Monks concerning the following question:

According to perldoc perlpod:

  Or you can link to a web page:

  o   "L<scheme:...>"

      "L<text|scheme:...>"

       Links to an absolute URL.  For example,
       "L<http://www.perl.org/>" or "L<The Perl Home
        Page|http://www.perl.org/>".
[download]

I have a file (quirk.pod) containing

=pod

=head1 Ugly Link Rendering

This is an ftp link
L<ftp://ftp2.census.gov/geo/tiger/TIGER2010>.
L<This is not|http://ftp2.census.gov/geo/tiger/TIGER2010/>.
[download]

podchecker has no problem with it. The output of perldoc includes

Ugly Link Rendering
       This is an ftp link <ftp://ftp2.census.gov/geo/tiger/TIGER2010>
+.  This
       is not <http://ftp2.census.gov/geo/tiger/TIGER2010/>.
[download]

The vestigial <'s and >'s are ugly and confusing. They make it appear that you omitted a pod formatting code. If I run

  /honk/perl5.14.1/bin/pod2html quirk.pod > quirk.html
[download]

I see

/honk/perl5.14.1/bin/pod2html: quirk.pod: cannot resolve L<This is not
+|http://ftp2.census.gov/geo/tiger/TIGER2010/> in paragraph 3.
[download]

and quirk.html contains (among other stuff)

<h1><a name="ugly_link_rendering">Ugly Link Rendering</a></h1>
<p>This is an ftp link
<a href="ftp://ftp2.census.gov/geo/tiger/TIGER2010">ftp://ftp2.census.
+gov/geo/tiger/TIGER2010</a>.
<em>This is not</em>.</p>
[download]

This is beyond ugly. The second hyperlink has disappeared altogether.

It's hard for me to believe that this is a bug that has managed to go unnoticed (I see it in 5.8.1, 5.12.1 and 5.14.1). So I must have done something wrong in creating the pod. But not wrong enough for podchecker to notice. And it sure looks to me like I'm doing what perlpod told me to do. Any insights?

Comment on hyperlinks in pod Select or Download Code

Replies are listed 'Best First'.
Re: hyperlinks in pod by davies (Prior) on Sep 27, 2011 at 18:06 UTC
What are you using to convert POD to HTML? If it's `pod2html`, then be very afraid. I started using it a couple of years ago and have had extensive grief. I have reported some bugs but have had neither movement nor prospect of same, and the latest issue I had with it, where it put in unintended links for no clear reason, was the final straw. I am currently using `Pod::Simple::XHTML` and it seems (to me, on short acquaintance) to be much better. Regards, John Davies	[reply] [d/l] [select]
Re^2: hyperlinks in pod by jpl (Monk) on Sep 27, 2011 at 21:23 UTC
It shouldn't be necessary to fear commands that come as part of a standard distribution. It's wonderful that people come up with CPAN modules that do good things, but not-so-wonderful that standard utilities misbehave. Bug reports are always likely to get more satisfactory action if fixes are included (perl-porters time is not unlimited). If you aren't up to fixing the underlying problem, then propose a fix to the misleading documentation. That's where I'm headed with this "problem", if it turns out to be a real problem (and it does appear to be).	[reply]
Re: hyperlinks in pod by Anonymous Monk on Sep 27, 2011 at 19:30 UTC
The vestigial <'s and >'s are ugly and confusing. They make it appear that you omitted a pod formatting code Aside from delimiting a url in text, how else would you distinguish the beginning and end of a url in text-only console? How would you tell these apart without delimiters? `Visit L<http://example.com/hi?there>. Visit L<http://example.com/hi?there.> Visit L<http://example.com/hi?there:>+buddy Visit L<http://example.com/hi?there:+buddy>` [download] Since angle brackets need escaping in html, folks avoid them in urls, so they make for good delimiters in a text console This is beyond ugly. The second hyperlink has disappeared altogether. Actually it doesn't even rise to the level of ugly, its just unsupported :) not official pod format, though this tool supports it `perl -MPod::Simple::HTML -e Pod::Simple::HTML::go hyperlink.pod hyperlink.html` It's hard for me to believe that this is a bug that has managed to go unnoticed It hasn't gone unnoticed :) Though I don't immediately see it in https://rt.perl.org/rt3/Public/Search/Simple.html?q=pod%3A%3Ahtml/https://rt.perl.org/rt3//Public/Search/Simple.html?q=pod2html, I've seen this bug reported before, and rejected as not-a-bug, as per http://perldoc.perl.org/perlpodspec.html#About-L%3C...%3E-Codes Authors wanting to link to a particular (absolute) URL, must do so only with "L<scheme:...>" codes (like L<http://www.perl.org>), and must not attempt "L<Some Site Name\|scheme:...>" codes. This restriction avoids many problems in parsing and rendering L<...> codes.	[reply] [d/l] [select]
Re^2: hyperlinks in pod by Anonymous Monk on Sep 27, 2011 at 20:06 UTC
Though perlpodspec still contains that warning, apparently that restriction is gone: remove prohibition against L<text\|href> So, now this pod2html bug is a real bug again And now, perlpodspec has outdated warning against "`L<text\|href>`"	[reply] [d/l]
Re^2: hyperlinks in pod by jpl (Monk) on Sep 27, 2011 at 21:02 UTC
The vestigial <'s and >'s are ugly and confusing. They make it appear that you omitted a pod formatting code Aside from delimiting a url in text, how else would you distinguish the beginning and end of a url in text-only console? How would you tell these apart without delimiters? `Visit L<http://example.com/hi?there>. Visit L<http://example.com/hi?there.> Visit L<http://example.com/hi?there:>+buddy Visit L<http://example.com/hi?there:+buddy>` [download] Perhaps with something like B<...> or C<...> do in a text-only environment. Certainly not with something that was indistinguishable from a missing or invalid format code. It hasn't gone unnoticed :) Though I don't immediately see it in https://rt.perl.org/rt3/Public/Search/Simple.html?q=pod%3A%3Ahtml/https://rt.perl.org/rt3//Public/Search/Simple.html?q=pod2html I've seen this bug reported before, and rejected as not-a-bug, as per http://perldoc.perl.org/perlpodspec.html#About-L%3C...%3E-Codes I'm interested in the conflict between current documentation and current behavior. As far as I can tell, I'm following current documentation, which is in conflict with current behavior, as other responders have observed.	[reply] [d/l]
Re^3: hyperlinks in pod by Anonymous Monk on Sep 28, 2011 at 09:00 UTC
Perhaps with something like B<...> or C<...> do in a text-only environment. Hmm, both stars and quotes (italic and "code") seem more common than <> in urls ... and they're already used for emphasis Certainly not* with something that was indistinguishable from a missing or invalid format code.* But you see, stray angle brackets are perfectly valid in pod, but `podchecker -w -w ...` will warn you if you're interested `*** WARNING: 2 unescaped <> in paragraph at line 18 in file ...` [download] And you will be warned about invalid formatting codes (even from pod2text), like `Around line 16: Deleting unknown formatting code R<>` [download] I personally feel this is a mistake, its like a browser appending a list of html errors at the bottom of each page, after all, perldoc/pod2text/pod2html... aren't exactly author tools like podchecker/Pod::Checker, podtidy/Pod::Tidy, podlinkcheck/App::PodLinkCheck, podlint/Pod::POM, pod_cover/Pod::Coverage, Test::Pod, Test::Pod::Coverage, Test::XT As far as I can tell, I'm following current documentation, which is in conflict with current behavior, as other responders have observed. Yes, I concluded this also, same me Re^2: hyperlinks in pod :) Oh look pod2cpanhtml/App::Pod2CpanHtml	[reply] [d/l] [select]

Back to Seekers of Perl Wisdom