A couple months ago, RJBS and I collaborated on adding a new feature to Pod: sane URL links. For, well, ever, the case has been that to link to URLs or any other scheme: links in Pod, You had to do something like this:

For more information, consult the pgTAP documentation:
L<http://pgtap.projects.postgresql.org/documentation.html>

The reasons why you couldn't include text in the link to server as the link text has never been really well spelled-out. Sean Burke, the most recent author of the Pod spec, had only said that the support wasn't there "for various reasons."

Meanwhile, I accidentally discovered that Pod::Simple has in fact supported such formats for a long time. At some point Sean added it, but didn't update the spec. Maybe he thought it was fragile. I have no idea. But since the support was already there, and most of the other Pod tools already support it or want to, it was a simple change to make to the spec, and it was released in Perl 5.11.3 and Pod::Simple 3.11. It's now officially a part of the spec. The above Pod can now be written as:

For more information, consult the L<pgTAP
documentation|http://pgtap.projects.postgresql.org/documentation.html>.

So much better! And to show it off, I've just updated all the links in SVN::Notify and released a new version. Check it out on CPAN Search. See how the links such as to "HookStart.exe" and "Windows Subversion + Apache + TortoiseSVN + SVN::Notify HOWTO" are nice links? They no longer use the URL for the link text. Contrast with the previous version.

And as of yesterday, the last piece to allow this went into place. Andy gave me maintenance of Test::Pod, and I immediately released a new version to allow the new syntax. So update your t/pod.t file to require Test::Pod 1.41, update your links, and celebrate the arrival of sane links in Pod documentation.

Backtalk

anonymous coward wrote:

What? That's not a nice link. Have you clicked on it?

The last piece is only achieved when you get Graham to update Pod::Simple::HTML from the version 2.01 he's running at search.cpan.org.

Theory wrote:

Wrong Link, AC!

Hey AC, look at the links in the 2.80 release, not 2.79.

—Theory

kentnl wrote:

AC is right. Here is where the links point to:

http://search.cpan.org/perldoc?http%3A#/svn.haxx.se/users/archive-2006-05/0593.shtml

http://search.cpan.org/perldoc?http%3A#/www.koders.com/csharp/fidE2724F44EF2D47F1C0FE76C538006435FA20051D.aspx

and neither of those links WorkForMe.

kentnl wrote:

Doh

Also: if people set their "URL" field on your blog without a prefixing 'http://' it appears to link to 'http://www.justatheory.com/computers/programming/perl/{$URL}'

Theory wrote:

D’oh Indeed!

@kentnl—Oh, I gotcha, my mistake. The point is that the text is being used for the link, though. I hadn't clicked on them, though, just looked to see that they looked good. Making the link use perldoc is probably a bug in Graham’s subclass of Pod::Simple::HTML. I'll bug him about it.

And yeah, I've been meaning to modify the Blosxom writeback plugin to put in the "http://" if it's not there. I'll just go do that right now since someone's actually complaining about it. :-)

—Theory