Hi,
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
errors.
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
will:
- 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, forrest.build.xml 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
apidocs/org/apache/myproj/MyClass.html
- 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)"
location="http://nagoya.apache.org/bugzilla"/>
and the resource-ref expands to "<a
href="http://nagoya.apache.org/bugzilla">Bugzilla (the Apache bug
database)</a>"
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
page</link>
--Jeff
[1] http://marc.theaimsgroup.com/?t=103444042500002&r=1&w=2
|