forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nicola Ken Barozzi <>
Subject Re: URI spaces: source, processing, result
Date Thu, 12 Dec 2002 08:17:36 GMT

Jeff Turner wrote:
> On Wed, Dec 11, 2002 at 09:35:47PM +0100, Steven Noels wrote:
>>Nicola Ken Barozzi wrote:

>>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=""> gets translated into <a
> href="">.
> 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?

Ask yourself, what should we use the prefix for?

In the proposal mail I sent (yes, I do feel mildly offended by your
massive snips and sarcastic comments), I tried to explain my POV.
Since it didn't get through, I assume that I wasn't able to convey the
message, so please give me the time and possibility of getting my points

You are mixing three things in the scheme:

   1 - link translation  (scheme -> real uri space)
   2 - source definition (where the source is)
   3 - generation method (what is to be done with it)

I totally agree that we should use it for link translation, but I think
that the other two points are concerns of the sitemap. Hence the use of
a "resource-exists" feature and mount points to address point 2 and CAPs
to address point 3.

Link translation is just a facility, that can be used or skipped.
Let's say that translation has been done, and I have the resulting URI
ready, what does Cocoon do with it?

It would select based on the source mime-type inferred from file
extensions and DTDs from CAPs. Found what to do with the file, it then
resolves the source of the file using also mount points.

This gives you the best flexibility and separation between all these

                                -  ~  -

What the user sees, is that wherever they put the file, they can link to
it without specifying the extension, and Cocoon serves it. I find it
quite straightforward.

If they want to refer to links via shorthands, they define them in the
linkmap; there are special shorthand schemes that help in the definition
of complex links like the mail archives.

Finally, if they want to bring in stuff from outer dirs, they mount
them, and Cocoon treats them as if they were local.

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

I'm confortable with both, and think that if we define an implicit
scheme it should be only one.

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

Yes. Forrest, as said many times before, should be /eventually/
concerned about the skinning of the sources that other programs put
there. For example, I want to use the xjavadoc doclet to make xml
javadocs, and Forrest can skin them.

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

I don't like this, because the +xxx stuff is not part of a mime type.
Forrest should not be concerned, as we have previously decided, about
generating the above stuff, but only eventually skinning it.

Nicola Ken Barozzi         
              - verba volant, scripta manent -
     (discussions get forgotten, just code remains)

View raw message