Per Einar Ellefsen wrote:At 13:35 02.04.2002, Stas Bekman wrote:
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).
It's handled, similar to @INC, so you have to fully qualify the files, e.g. see the mailist/list-* links.
Please take a look at the docs inside:
lib/Docset/RunTime.pm: "Source Documents Lookup" lib/DocSet/Source/POD.pm
- 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?
It includes the file only if it's relative to the current directory and located below it. That's how I link to the code scripts in the guide. Otherwise it does the same as I<>. I believe it's safe.
The only caveat is that when the pdf is rendered and the file is automatically inlined it breaks the original paragraph the F<> was in. Also if the file is big it can make the pdf much bigger.
If we get the U<> to work, I may remove this feature as it won't be needed anymore (thouh that means that the pdf inlining will have to go away too)
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.
It's not that bad right now, it's just that the real link is displayed as a title,
so it's not nice. It's more or less working.
I don't understand what you mean...Using URLs inside L<> clearly doesn't work, we get the linked item in italics and that's it.. As for relative links (which aren't auto-detected by the parser) it's even worse.
The thing is that the documentation is distributed with the sources too.
Try to check out modperl-2.0 and you will see that modperl-2.0/docs is the same as modperl-docs/src/docs/2.0. So people will try to read the pod files with perldoc and pod2man, and using extended pod will cause problems.
The distribution in the source was made to avoid the duplication and having
all the docs in one place.
Again this is not a showstopper, we can try to push for a new markup for perlpodspec, not sure if we will be lucky to push it into 5.8 before it goes live. (of course I realize that it still won't work for older perls)
I understand. We should try to keep new features out of documentation that is distributed elsewhere (that means keeping it out of the 2.0 user's guide for a while), but that we could use it in the general site pages (which includes the guide which will unlikely reside on user computers and even less likely reside there in source form).
-- Per Einar Ellefsen [EMAIL PROTECTED]
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
