How can I have link text with a URL in Pod's L<>?

Question

The L<name> formatting code allows you to set the display text for the link if you're linking to other POD, as in L<Display Text|link_dest>, but this isn't allowed for L<scheme:...> links, such as

L<http://perldoc.perl.org/strict.html&gt;

How do I specify a display text for such links? Alternatively, how do I manually write such a link without the angle brackets being HTML entitized by pod2html?

Answer 1

http://perldoc.perl.org/perlpod.html#Formatting-Codes

L<<a href="http://www.perl.org/"&gt;http://www.perl.org/&lt;/a&gt;&gt;

As you point out, it looks like this should work, but perhaps I've misunderstood your question?

EDIT: It seems that pod2html does not like that approach.
I found a slightly more involved solution at,

http://blogs.techrepublic.com.com/howdoi/?p=114

#!/usr/bin/perl                                                                                                              
use strict;
use warnings;
use Pod::2::html;


my $pod_file =  $ARGV[0];
my $template =  $ARGV[1];

# Create pod2html object                                                                                                    
my $pod = Pod::2::html->new($pod_file);

# The path to the HTML template                                                                                             
$pod->template($template);

# The formatted HTML will go to STDOUT                                                                                      
$pod->readpod();

I tested this out and it seems to have no problem interpolating generic html, so that you don't actually need th L<> tag at all. This seems like a decent solution to me.

Answer 2

If you want to do something fancy with your Pod, it's really easy to write a Pod translator. Most of the work is already done for you in Pod::Simple, so you only need to handle the cases for L<>. There's a chapter in Mastering Perl about it.

Answer 3

You were SO close! You're missing a required space between both angle brackets and the URL. Try this:

I think L<< http://example.com >> is the best site on the web!

The extra space is mandatory according to perldoc perlpod (scroll down from here to find it):

"A more readable, and perhaps more "plain" way is to use an alternate set of delimiters that doesn't require a single ">" to be escaped. With the Pod formatters that are standard starting with perl5.5.660, doubled angle brackets ("<<" and ">>") may be used if and only if there is whitespace right after the opening delimiter and whitespace right before the closing delimiter! For example, the following will do the trick:"

       C<< $a <=> $b >>