Beefy Boxes and Bandwidth Generously Provided by pair Networks
Welcome to the Monastery
 
PerlMonks  

hyperlinks in pod

by jpl (Monk)
on Sep 27, 2011 at 17:44 UTC ( #928125=perlquestion: print w/ replies, xml ) Need Help??
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/>".
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/>.
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/>.
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
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.
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>
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
Re: hyperlinks in pod
by davies (Vicar) 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

      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).
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>

    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.
      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>
      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.

        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 ...

        And you will be warned about invalid formatting codes (even from pod2text), like

        Around line 16: Deleting unknown formatting code R<>

        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

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://928125]
Approved by planetscape
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others chanting in the Monastery: (11)
As of 2014-10-24 18:18 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    For retirement, I am banking on:










    Results (134 votes), past polls