You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs-dev@perl.apache.org by Per Einar Ellefsen <pe...@skynet.be> on 2002/03/30 12:05:53 UTC
Link problems
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://....>
- relative links, URL form: L<the search|../search/swish.cgi>
- 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>)
- 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.
--
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
Re: Link problems
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 04:24 03.04.2002, Stas Bekman wrote:
>Per Einar Ellefsen wrote:
>>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).
>
>we cannot. the 2.0 documentation is about to take over the 1.0 documentation,
>most likely that you will need these features in 2.0 docs too.
Most likely, but I could still use it in 1.0 docs :)
Ok, I'll try and work without it. Do as best you can with pod-people to
push the U<> construct, and we'll see how it goes.
--
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
Re: Link problems
Posted by Stas Bekman <st...@stason.org>.
Per Einar Ellefsen wrote:
>>> 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.
I didn't mean using L<> for URIs, you simply say: http://foo.com/bar and
it gets linked. Of course this doesn't work for relative links.
>> 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).
we cannot. the 2.0 documentation is about to take over the 1.0
documentation,
most likely that you will need these features in 2.0 docs too.
__________________________________________________________________
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
Re: Link problems
Posted by Per Einar Ellefsen <pe...@skynet.be>.
At 18:35 02.04.2002, Stas Bekman wrote:
>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
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
Re: Link problems
Posted by Stas Bekman <st...@stason.org>.
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.
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)
__________________________________________________________________
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
Re: Link problems
Posted by Per Einar Ellefsen <pe...@skynet.be>.
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
Re: Link problems
Posted by Stas Bekman <st...@stason.org>.
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