POD L<> and relative links?

[skazat]

In my pod, if I have something like this:

 
 For more information, see L<thisfile.html>

When parsed

(EDIT: I'm currently using the pod2html utility, ala:

 
system("pod2html --infile $the_pod_source --outfile $the_pod_source\.h
+tml");

, I'll get an error like this:

 
 cannot resolve L<thisfile.html> in paragraph xxx.

If I set the above to something like:

 
 For more information, see L<http://example.com/thisfile.html>

and, "http://example.com/thisfile.html" exists, it works.

Any way to turn off the "check if it's actually there" test? I've got C<pod2html> in a little makefile - type script, so there's times where it's not going to be around in a URL and may not be around in the environment it's being parsed and created.

Update:

using the pod2html utility, I thought I'd see if passing the, --htmlroot parameter would help things - giving a base to place the relative URL to - no dice.

I guess the question *really* is, how do you pass a relative URL to an HTML document inside an L<> thingy in POD. If you can't, I guess I'm outta luck.

I guess I'll also look at the P6 version of POD and see if there's a way in there for the future. (crosses fingers)

[brian_d_foy]

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;

The Pod::Simple equivalent is:

use Pod::Simple::HTML;

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

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;

Now your pod2html becomes:

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

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

[skazat]

I shall consider this.

Thanks for chiming in! Your post is most excellent and extremely helpful

Cheers,

[halley]

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.

[skazat]

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.

[Joost]

Depends. You can link to other POD documents by using L<DocumentName> but the POD translator needs to know how to turn that into a relative link. You can also create any HTML by using the =for html or =begin html statements:

=for html
<a href="relative/link.html">relative</a>

 or

=begin html

some <b>html</b>

=end html

update: also see perlpod

[skazat]

Understand the =begin =end =for and friend, just seems like using the L<> would be a little cleaner. For example, I could put the link inline of the paragraph I'm writing in, without having a new paragraph and it would work, wherever you're viewing the POD.

Pity I can't just say in L<>, "hey this is a relative URL, and it doesn't have to turn into anything - just trust me". Seems like that's within Perl culture of Do What I Mean.

I usually make two sets of docs - one that comes with the distribution, and anything that goes on the support site.

[Joost]

The thing is, you're writing POD, not HTML. POD does not really have a concept of relative links, it just has "links". The pod translator has to figure out how to link stuff, and it can do that by making (relative) urls for HTML, creating hyperlinks in for info files or just displaying the raw text. Full URLs in links are useful because they will work more or less anywhere, independent of the location of the POD or generated file. Relative links depend on the eventual location of the generated file, which is not known in general. Ofcourse, you can always write your own pod2html tranlator if you do know.

[Bro. Doug]

Have you tried formatting your filename in different ways?

For example, you could pass in a complete file path, along with 'file://'.



L<file://this/is/your/file>


This could, if it works, come with advantages and disadvantages. The advantage is having links that work in your HTML POD, but the disadvantage seems to be the extra hassle of putting in long file paths.

It's just a thought. Enjoy.

[geoffleach]

The problem is where to link to. pod2html punts. podhtmleasy.pl (found in Pod::HtmlEasy) makes a CPAN search out of it: thisfile.html This module has hooks that permit you to do something more to your liking. Pod::HtmlEasy has not been maintained for a couple of years. However, I've just uploaded a new version. If you'd like to try it, check out: https://pause.perl.org/pub/PAUSE/authors/id/G/GL/GLEACH/Pod-HtmlEasy-0.08_01.tar.gz

[skazat]

Thanks for letting me know - I'll give it a go soon! I'll make a new thread in Perlmonks or chime in on the RT if I come into any trouble;

[Anonymous Monk]

No. Pod is not html.

[skazat]

Yeah, got that part - just following the documentation in perlpod.