perl-docs-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Per Einar Ellefsen <per.ei...@skynet.be>
Subject Re: Link problems
Date Tue, 02 Apr 2002 16:09:53 GMT
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).


>>- 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
per.einar@skynet.be



---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org


Mime
View raw message