forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Turner <je...@apache.org>
Subject Re: URI spaces: source, processing, result
Date Thu, 12 Dec 2002 06:27:19 GMT
On Wed, Dec 11, 2002 at 09:35:47PM +0100, Steven Noels wrote:
> Nicola Ken Barozzi wrote:
> 
> >
> >Does this make sense?
> >
> 
> I really don't know. I have been talking offlist to both you and Jeff, 
> and some of this is above my drugged head these days.

Heaven help us if forrest-dev ever becomes as incomprehensible as
avalon-dev :P

> Trying to bring the town of you together, I see there is some general 
> tendency to tolerate and even advocate some source:/ or scheme:/ like 
> think, if not for the same reason. While I love to KISS, the aspect of 
> having to declare my links in my future Forrest docs like <link 
> href="protocol:name"/> feels kinda good, protocol being things like
> 
>  - javadoc
>  - code
>  - keyword
>  - index
>  - raw
>  - href (default)
>  - linkmap (indirection layer, also to aforementioned protocols)

One I'm really keen on is "mail:", for referencing list emails by
Message-Id.  For example, <link
href="mail:3DF7A1A3.6010109@outerthought.org"> gets translated into <a
href="http://marc.theaimsgroup.com/....">.

But anyway..

Once we have 'linkmap' implemented, that accounts for 95% of relative
links in our xdocs.  So eventually, unprefixed links will become an
anachronism.  So why try to "guess" if a link is static to preserve the
current prefix-less status quo, when we want Forrest to eventually have
_all_ links prefixed?

Here is an analogy with the seemingly uncontroversial 'linkmap' scheme.
How should 'linkmap' links be implemented?

a) Have an explicit prefix, like <link href="site:/primer">
b) Have unprefixed links like <link href="primer">, and have the CLI open
the linkmap.xml file, and check if a 'primer' entry exists.  If so, treat
as a linkmap link.

This same choice of implementation; explicit or inferred, needs to be
made for every potential scheme.  We have a clear fork in the road:

1) _All_ schemes are explicit.  Implemented with XSLTs and Transformers
   in Forrest

2) Some schemes (like javadoc:) are explicit, and others (like file:, and
   perhaps linkmap:?) are inferred.  Implicit schemes are implemented
   with CLI modifications and 'conditional' sitemap hacks like
   resource-exists.

Are we ready for a vote yet?

> and name being a filename or a named resource name depending on the 
> protocol and the eventual indirection
> 
> In terms of implementation, some of this will point towards SAXable 
> information that must be passed across Cocoon pipelines, some of this is 
> external data, perhaps binary in the sense of not being based on XML and 
> not serializable as such. So some of this information will require its 
> own Source implementation or Generator, some will just need to be copied 
> around, either as a file, or as a collection of files. Some of it will 
> require link augmentation or resolution, if linkmaps/indirection has 
> been used.
> 
> With regards to greater datasets, such as massive Javadoc collections, 
> I'm not sure whether we would need to try and keep this within the 
> concern of Forrest, at least in terms of the static generation of it - 
> there exist tools to do that.

Yes, I would prefer for Javadoc invocation to be the concern of whatever
invoked Forrest, eg, an Ant script.

> In terms of doing something with tools like qdox, I'm not sure - I
> think this can be a value for the Forrest user: <link
> href="src:/org.apache.cocoon.foobar"/> bring up a syntax-highlighted
> version of that class.

Remember how we kinda decided that link MIME type should be specified as
a separate attribute?  Well here is a neat example:

<link href="java:/org.apache.cocoon.foobar" type="text/html+javadoc"/>
<link href="java:/org.apache.cocoon.foobar" type="text/html+uml"/>
<link href="java:/org.apache.cocoon.foobar" type="text/html+qdox"/>

So the identifier (URI) stays the same, and 'type' specifies different
representations of that URI.  This illustrates why 'java:' is preferable
'javadoc:'.


<snip good implementation summary>

--Jeff

Mime
View raw message