How to link to other directories within Pod

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

My question is best begun by quoting perlpod about the L<> linking sequence

    L<name/ident>	item in manual page
    L<name/"sec">	section in other manual page ...
		(Text can not contain the characters '/' and '|', 
		and should contain matched '<' or '>')

How then to specify a directory structure for a link?

Specifically, I wanted to be able to link between pod, pl, pm files that were arranged as follows

aproject/code/ascript.pl         # all code in one directory
aproject/code/modules/amodule.pm     # modules in another
aproject/docs/anote.pod            # general documentation seperated f
+rom code
[download]

and then I wanted to be able to link within docs/anote.pod (say) as follows

L<../code/ascript.pl>    # link in docs/anote.pod to code/ascript.pl
[download]

I'm becoming quite fond of using pod, especially given my lack of html experience. This however is a showstopper for me if I can't incorporate directory heirarchies and be able to pod up my general project notes seperately with links to the pl pod.

I have tried the perl2html utility, searched through Pod::Tree::Html and tried the pods2html snippet all to no avail.

The only two clues I have found are examples of link sequences written as

L<C<ascript>>
[download]

and maybe that produces something different and examples of links written

L<Pod::Tree::Html>
[download]

which must somehow give close to what I would like to do given my perl html docs.

Which (no doubt obvious) points am I missing?

Thanks Tony

Comment on How to link to other directories within Pod Select or Download Code

Replies are listed 'Best First'.
Re: How to link to other directories within Pod by perrin (Chancellor) on Nov 07, 2001 at 11:43 UTC
I believe the idea is for you to link to other modules, so they would be expected to follow module naming conventions. However, Pod::Find might be helpful to you.	[reply]
(tye)Re: How to link to other directories within Pod by tye (Sage) on Nov 07, 2001 at 21:24 UTC
The POD specification has always been a bit vague in some areas and `L<>` is certainly one of those. But there have been some recent improvements in more rigorously defining POD. Unfortunately, the p5p weekly summary didn't include thread-specific links so you'll probably just have to search the archives. One link that was provided was for joining the "pod-people" e-mail list if you are interested in this type of stuff. Be prepared for the possibility that the new definition nails down the answer to your question as "you can't". POD was designed with much more emphasis on simplicity than power, so it is easy to find things that POD can only almost do. - tye (but my friends call me "Tye")	[reply] [d/l]