Re: POD L<> and relative links?

Write your own Pod translator.

No, seriously, it's really easy. I talk about it in a chapter for or two for Mastering Perl, but mostly "Working with Pod". Although I use Pod::PseudoPod::HTML because O'Reilly has some extra Pod features, it's the same idea. You can even grab my own pod2html from the Mastering Perl repository. All of the HTML for the chapter pages comes out of my own pod2html.

Instead of using pod2html (the one that uses Pod::Html from Tom C.), create your own pod2html. It's not that hard considering that the entire script is:

use Pod::Html;

pod2html @ARGV;
[download]

The Pod::Simple equivalent is:

use Pod::Simple::HTML;

Pod::Simple::HTML->parse_from_file( @ARGV );
[download]

That's just the stock, off-the-shelf behavior though. If you want to change what happens when it parses the L<> stuff, you only have to override the parts that handle that part.

package My::Pod::HTML::Simple;
use base qw( Pod::HTML::Simple );

sub do_link { ... whatever you want ... }

1;
[download]

Now your pod2html becomes:

use My::Pod::Simple::HTML;

My::Pod::Simple::HTML->parse_from_file( @ARGV );
[download]

--
brian d foy <brian@stonehenge.com>
Subscribe to The Perl Review

Comment on Re: POD L<> and relative links? Select or Download Code

Replies are listed 'Best First'.
Re^2: POD L<> and relative links? by skazat (Chaplain) on Oct 20, 2006 at 00:03 UTC
I shall consider this. Thanks for chiming in! Your post is most excellent and extremely helpful Cheers, -justin simoni skazat me	[reply]
Re^2: POD L<> and relative links? by halley (Prior) on Oct 20, 2006 at 14:16 UTC
I suggest just adding support for something that other people would find useful in the future. Like `U<>` for URL links instead of `L<>` for POD links. Then pod2html would make `<a href="blah">blah</a>`, pod2txt would leave it alone, and pod2rtf would do whatever RTFs do for URLs and so on. Since the clicky URL kind of link is ubiquitous in just about any readable file format, but the POD standard doesn't really seem to cover it, I expect it would be handy for a lot of people. If I can go one step further, maybe even add a `G<>` for inline graphics files. I hate the lack of simple diagramming in PODs, and the cumbersome `=for html` idiom for all these everyday wants. -- `[ e d @ h a l l e y . c c ]`	[reply] [d/l] [select]
Re^3: POD L<> and relative links? by skazat (Chaplain) on Oct 23, 2006 at 21:44 UTC
Not a bad idea - I'll take it into consideration. For some inspiration, I know O'Reilly writes many of its books in a pseudo pod format - I forget what book has the source to their converter (Template Toolkit? - I may be way in Right Field), but using that as a starting point and just taking what I need would probably help ;) Seems like a lot of problems with the current POD will be helped with the POD for Perl 6 - if not, now's the time I guess for everyone to chime in - Damian just released the spec and almost has a working Perl5 parser. -justin simoni skazat me	[reply]