perl-docs-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stas Bekman <>
Subject Re: Link problems
Date Tue, 02 Apr 2002 16:35:52 GMT
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/ "Source Documents Lookup"

>>> - 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.

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 

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)

Stas Bekman            JAm_pH ------> Just Another mod_perl Hacker     mod_perl Guide --->

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message