Irrelevant has asked for the wisdom of the Perl Monks concerning the following question:

I'm trying to make a crossreference to one of the standard perl docs from within my POD, but I've been unable to fiddle pod2html into working. I'm using ActivePerl 5.8.3.

The link (one of many): L<are-a|perlobj/isa>

The first attempt:

pod2html.bat --infile=Mini.pm --outfile=Mini.html --css=file://C:/Programs/Perl/html/Active.css --header --verbose --podpath=C:/Programs/Perl/lib

and the error message:

C:\Programs\Perl\bin\pod2html.bat: error opening directory C: No such file or directory

The second attempt (with the "C:" dropped from --podpath),

pod2html.bat --infile=Mini.pm --outfile=Mini.html --css=file://C:/Programs/Perl/html/Active.css --header --verbose --podpath=/Programs/Perl/lib

did run without errors, but resulted in a link to file://programs/Perl/lib/Pod/perlobj.html#isa, which neither Firefox nor IE can resolve. Help!

Replies are listed 'Best First'.
Re: Linking between pods
by crashtest (Curate) on Feb 04, 2005 at 22:15 UTC
    You're second attempt almost got it right. To fix your links, you need to specify the pod root as "/", because otherwise the program just uses the current directory (which is probably not "/").

    From the usage information:
    --podroot - filesystem base directory from which all relative paths in podpath stem (default is .).

    So I think you want: 
    pod2html.bat --infile=Mini.pm --outfile=Mini.html --css=file:///Progra
+ms/Perl/html/Active.css --header --verbose --podroot="/" --podpath="P
+rograms/Perl/html"

    [download]
    You'll notice I modified your style sheet reference from file://C:/Programs/Perl/html/Active.css to file:///Programs/Perl/html/Active.css. That's what it took to get it to work for me. Hope this helps!

    Updated to remove extraneous whitespace in command.
[reply]
[d/l]
      With your version (removing the extraneous space in "-- podpath", pod2html runs successfully, but the link still does not work, and the browser also fails to find the CSS.

      I suspect that pod2html may be expecting to be on a POSIX-style FS, so it requires absolute paths to start with "/". However, Windows browers apparently cannot evaluate absoulute paths with no drive letter. pod2html may only allow the CSS link to start with C:/ because it doesn't actually need to read the CSS, so allows anything.

[reply]
[d/l]
        Have you tried the command above (minus the extra space!) with IE? That's all I had at work yesterday, and it looked fine.

        I use Firefox at home as well though, and since nobody can be expected to make do with IE if given a choice, I fiddled some more with pod2html (following BrentDax suggestion with the "c|").

        1.) To get the stylesheet to link correctly, try the following option (I'm assuming you installed your ActiveState Perl to C:\Programs\Perl):
        --css="file://c|/Programs/Perl/html/Active.css"

        2.) As for the links to perldocs, the "--htmlroot" option allows you to prepend what you need to the links. In combination with --podpath and --podroot, try:
        --podroot="/" --podpath="Programs/Perl/html" --htmlroot="file://c|"
[reply]
[d/l]
[select]
Re: Linking between pods
by BrentDax (Hermit) on Feb 05, 2005 at 17:18 UTC
    Starting the path with /c| may work.

    =cut
    --Brent Dax
    There is no sig.

[reply]
[d/l]
Re: Linking between pods
by doom (Deacon) on Feb 05, 2005 at 21:08 UTC
    A couple of quick comments (that might not be relevant, because I don't know much about the Windows world these days):

    (1) The old Tom Christiansen pod processing code is known to have some problems, but it's taking a *really* long time for a replacement to become accepted. I suggest taking a look at Pod::Simple::HtmlBatch. I posted a review here a while back: Pod::Simple::HtmlBatch.

    (2) A gotcha that took me an embarassingly long time to figure out: Don't indent a list of L<> links. Indentation means "code block" in pod-land. (But it doesn't sound like this is your problem).

[reply]
      #1 worked, thanks. HTMLBatch makes nicer output than pod2html, too.
[reply]

Back to Seekers of Perl Wisdom