forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Turner <>
Subject Adding protocols to links
Date Mon, 09 Dec 2002 15:59:25 GMT

Seems the commonest complaints about Forrest are to do with linking..

a) How do I link to an existing static file, like a PDF?
b) How to I link to not-yet-generated stuff like Javadocs without getting

Doing a bit more thinking about it..

<link> elements contain URI pointers.  URIs always have a protocol (aka
scheme); http:, ftp:, file:, urn: etc.

For Forrest, the implied protocol in relative hrefs is 'cocoon:'.  So
<link href="mypdf.pdf"> actually means <link href="cocoon:mypdf.pdf">.

For people trying to link to a static mypdf.pdf, or a nonexistent
apidocs/ directory, or a file that will be created by a non-Forrest app,
this is no good.

So I think users should be able to specify protocols other than
'cocoon:', to say to Cocoon, "don't touch, this isn't your business", and
correspondingly, say to Forrest, "process this some other way".

So how about the following solution:

When encountering a file: link like <link href="file:foo.pdf">, Cocoon

 - Rewrite the link to <a href="foo.pdf"> in document2html.xsl
 - Not traverse the link (ie, filterlinks.xsl ignores file: links)
 - Record the link in a file, say, unprocessed-files.txt

After Cocoon has finished, then opens
unprocessed-files.txt, and copies the listed files into build/site.

I have this system working locally.  Eg, I have
src/documentation/content/hello.pdf, and can link to it with <link
href="file:hello.pdf">.  This works for webapp and command-line.

Can I check this stuff in, or did anyone else have a brilliant solution
to this problem up their sleeve?

If we're happy with the general idea of using protocols in links, then in
future we can do some other nice stuff:

 - Links to javadocs, with <link href="java:org.apache.myproj.MyClass">.
   The user specifies their javadoc directory (say, 'apidocs'), and the
   stylesheet transforms the link to

 - Emulate Stylebook's "resources".  If you recall, in Stylebook XML
   files, you can have, say: <resource-ref idref="bugzilla"/>, which
   opens a resources.xml file, and finds the following:

   <resource id="bugzilla"
    title="Bugzilla (the Apache bug database)"

   and the resource-ref expands to "<a
   href="">Bugzilla (the Apache bug

   We can have equivalent functionality with <link href="res:bugzilla"/>.

 - If the linkmap [1] ever becomes reality, then pages can link to each
   other with abstract addresses, eg <link href="site:/index">Index



View raw message