perl-docs-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stas Bekman <s...@stason.org>
Subject Re: Link problems
Date Tue, 02 Apr 2002 11:35:41 GMT
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.

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

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

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?

__________________________________________________________________
Stas Bekman            JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/     mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org   http://ticketmaster.com


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