http://www.perlmonks.org?node_id=928156


in reply to hyperlinks in pod

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.

Replies are listed 'Best First'.
Re^2: hyperlinks in pod
by Anonymous Monk on Sep 27, 2011 at 20:06 UTC
[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]

      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]

In Section Seekers of Perl Wisdom