External link shortcuts

Writing an external link is done with the basic tag \L. This tag takes an URL option which needs to be set to the correct, complete URL, like so:

    \L{url="http://cpan.perl.org"}<CPAN>

The first issue with this is that one has to write the protocol again and again. \L needs to know it, but often is is fix and always http. So, a first macro could insert that protocol for us.

    +URL:\L{url="http://__url__"}<__body__>

This works well as long as one remembers not to add the protocol to an URL when using the \URL macro, otherwise one ends with invalid links that duplicate the protocol. More convenient for users, the following version detects if the protocol is already there, and adds it if required. As it uses embedded Perl, Active Contents has to be enabled (converter option -active requires to be set). Remove the newlines when copying.

    +URL:\EMBED{lang=perl}
           my $url='__url__';
           $url=join('', 'http://', $url) unless $url=~m(^[^:]://);
           \L{url="$url"}<__body__>
         \END_EMBED

Now, both \URL{url="cpan.perl.org"}<CPAN> and \URL{url="http://cpan.perl.org"}<CPAN> can be used and will be handled correctly.

To make use even more convenient, we could shorten the URL option name to n and provide an optional protocol setting.

    +URL:\EMBED{lang=perl}
           my ($url, $protocol)=('__n__', '__prot__');
           $prot='http' unless $prot;
           $url=join('://', $prot, $url) unless $url=~m(^[^:]://);
           \L{url="$url"}<__body__>
         \END_EMBED

Now usage looks like \URL{n="cpan.perl.org" prot=https}<CPAN>.

But again, there's room for improvements. As a special case there are links that name the page address - say you want to mention search.cpan.org, and this address should be a link to the site. With \URL, this is no problem, but we have to write the address twice: \URL{n="search.cpan.org"}<search.cpan.org>.

To address this we can extend the macro definition to fall back to the body text when no address was given.

    +URL:\EMBED{lang=perl}
           my ($url, $protocol)=('__n__', '__prot__');
           $url='__body__' unless $url;
           $prot='http' unless $prot;
           $url=join('://', $prot, $url) unless $url=~m(^[^:]://);
           \L{url="$url"}<__body__>
         \END_EMBED

So finally we have a clever macro that allows us to write just \URL<search.cpan.org> to link the address text to the address.