Per Einar Ellefsen wrote:Hia agin everyone.
Pod has a big problem: linking is horrible. I knowyou already know about this, but we have to correct these problems in some way. I'd gladly do it, if someone tells me where to correct it.
What is needed:
- off site links, of the form L<some site|http://....>
Cannot use L<> because of the / in the URI, which is reserved for separating the section in the document.
We can easily extend pod with a new flag/syntax, but bear in mind that perldoc and friends will have a problem if someone tries to render the pods themselves. See the suggestion at the end of this post.
- relative links, URL form: L<the search|../search/swish.cgi>
this is not a problem, if you solve the above one.
Ok to both..
- being able to link to index pages: from guide/help.pod, being able to link to guide/index.html when it's created( for example with L<the guide|guide> or L<the guide|docs::1.0::guide>)
yup, I didn't think about this potential need, since we haven't used this before. I guess we can make the "::index" in foo::index as a special token so we can say: L<the guide|docs::1.0::guide::index> and the linker will check for docs/1.0/guide and link to index.html?
Yes, we definitely need that.
Another question: does this type of linking make all pages reachable? For example, can we from a Pod document link to products/products.html, which is only a normal HTML file, through the use of L<products::products> ? If not, this is needed too (unless solved by the U<> below).
- probably something else I don't remember.
I hit into this problem because in the guide/help.pod page, we link to the guide, to the faqs, etc... but it's pretty hard doing that right now.
Agreed
Notice that I've extended F<> to actually check that the file exists and link to it if so. Also in the pdf version F<> actually inlines the whole file, since you cannot fetch the external file along with pdf.
Watch out for that: for example in win32_binaries, Randy uses F<> to denote a file, like in the Docbook <filename> tag. He didn't intend the file to be included. Looking at the PDF file I don't see any file included, so I guess all is ok. Should we replace all accidental instances of F<> with I<> along the way?
I suggest a simple extension:
U< title | uri >
U: used for hyperlinks (mnemonics: *U*RI) title: any char with '|' and '>' escaped uri: full_uri | rel_uri full_uri: as in RFC spec rel_uri: ...
Should I try to push this extension to pod-people and perlpodspec?
Totally agreed.
But I don't think we should wait for it being acknowledged though. I feel that many Pod parsers are somewhat broken, and don't all seem to be following the spec. If we need a feature, it won't hurt anyone to include it. Of course, the best would be to have it in the spec, but right now I'm more worried about what we can do with our site versus what would be the right thing.
-- Per Einar Ellefsen [EMAIL PROTECTED]
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
