John M. Dlugosz has asked for the wisdom of the Perl Monks concerning the following question:

If I refer to another perl script or module within a module's POD, how can I code a hyperlink to that other document?

If the link targer is not found, pod2html writes it as a link to a "man page" which it assumes is found somewhere...where?

Meanwhile, the same link when used at search.cpan.org should expand to its own module/package library on the same site. Which means it has to know it's supposed to be a link to another module.

Is there a portable way to mark these, or use for blocks, to make these module links work in all the common situations?

—John

Replies are listed 'Best First'.
Re: L tags in POD, with search.cpan and POD2HTML
by theorbtwo (Prior) on Jan 11, 2003 at 07:52 UTC

    ActivePerl's documentation (the HTML docs, both in PPM packages and that comes with) is generated by ActiveState::DocTools (not on CPAN), by calling Pod::Html::pod2html on all pods that Pod::Find::pod_find (where the output file does not yet exist or is older then the input file), with the args...

            my @args = (
            "--htmldir=$dir",
            "--htmlroot=$back",
            "--podroot=.",
            "--podpath=$podpath",
            "--libpods=perlfunc:perlguts:perlvar:perlrun:perlopt",
            "--header", 
            "--infile=$infile", 
            "--outfile=$outfile", 
            "--css=$back/$css", 
            "--quiet",
            );

    [download]
    (where all vars are pretty much what you expect them to be.)

    (In other words, it only makes one pass.)

    Warning: Unless otherwise stated, code is untested. Do not use without understanding. Code is posted in the hopes it is useful, but without warranty. All copyrights are relinquished into the public domain unless otherwise stated. I am not an angel. I am capable of error, and err on a fairly regular basis. If I made a mistake, please let me know (such as by replying to this node).

[reply]
[d/l]
Re: L tags in POD, with search.cpan and POD2HTML
by PodMaster (Abbot) on Jan 11, 2003 at 05:19 UTC
    It's a chicken and egg problem. When processing Pod::Html, the pod2html target doesn't exist yet, so a link will not be created.

    Run it again (L<> tags are portable), and it should work itself out.

    update: use L<scriptname>. Subclass Pod::Html or use an alternative to get fancy with it. Pod::POM looks nice.

    MJD says you can't just make shit up and expect the computer to know what you mean, retardo!
    ** The Third rule of perl club is a statement of fact: pod is sexy.

[reply]
[d/l]
[select]
      re: run pod2html again

      You mean it's sensitive to the existance of a file that might be the target of the link? So L<foo> would figure out I meant foo.html in the same directory, if there is a foo.html in that directory?

      As for subclassing, I know I could make it work in my own custom solution, but people will be running the regular pod2html, not my custom job. And ActiveState's doc engine and search.cpan's doc engine does things their way, too.

      I wondered if any documentation or lore existed on details of those, or the existance of =for directives they know.

      —John

[reply]
[d/l]
        L<foo> would never look for a foo.html in that directory. It would look for (for example) \html\lib\foo.html, html\site\lib\foo.html, \html\bin\foo.html, and maybe a few others (like perl -V:installsitebin -V:installuserbin).

        Please read perlpod and the newer perlpodspec for details on how to use L<> tag (or at least how it's supposed to work).

        Implementation should be sensitive to the existence of the target file. I probably misspoke earlier, about it being a chicken and egg problem with Pod::Html specifically (I have enhanced my copy of Pod::Html a few times).

        You should not concern yourself what'll happen if the user don't have the docs for a target (or the module itself).

        Just avoid whatever you thought you might be able to do using =for directives (don't do it) and stick to L<> tags, they're portable (given you use them properl, but it's easy).

        update: I did some testing, and it is a chicken and egg problem, but it doesn't always happen. I ran into it during HTML::Mason installation. I also discovered a bug, L<HTML::Mason> will resolve into L<Bundle::HTML::Mason>. I'm gonna have to fix that, and submit a patch.

        MJD says you can't just make shit up and expect the computer to know what you mean, retardo!
        ** The Third rule of perl club is a statement of fact: pod is sexy.

[reply]
[d/l]

Back to Seekers of Perl Wisdom