cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeremy Quinn <>
Subject Re: documentation linking [was: Re: Cocoon and Web Services -- A Presentation at SD West 2002]
Date Sun, 28 Apr 2002 15:05:53 GMT

On Friday, April 26, 2002, at 12:32 , Diana Shannon wrote:


> This brings up an important point, raised by several already 
> (Jeremy, Christian) on this list, about the need to implement 
> efficient mechanisms for linking within Cocoon's internal 
> document set. Can we address these concerns with a cleanly 
> designed URI space, or do we need an xlink/shared 
> glossary/transformer approach as described by Jeremy in:

Some of the things I discussed there are not possible yet in Cocoon ....

> I too use something similar to what Jeremy described (xinclude 
> and XSLT) with my projects in their early stages, when the URI 
> space/data structure isn't clear to me. However, as my project 
> develops, I tend to be able to refactor my linking approach 
> through intuitive URIs. However, I haven't dealt with a project 
> that had so many potential contributors as well as this level 
> of volatile content. I'm sure I'm overlooking other issues.

I am also still developing my understanding of how to deploy 
XLink in Cocoon projects ;)

I am currently re-factoring the HRC site (about 400 links, 
highly hierarchal) to make it compliant with the XLink standard 
and separate my application-specific aspects.

Possibly the way to go for the Cocoon docs would be to make each 
document a valid extended xlink including the standard structure 
for referencing LinkBases, which are used to de-reference the 
links inside the document (very similar to processing i18n) and 
provide standardised navigation. This could be implemented as a 

We would need to add the xlink semantic and namespace to the 
document DTD.
XLink consists entirely of namespaced attributes.

Inside the documents you could have links (XLink arcs) like:

	<new xl:to="external. xindice"/> (opens a new window)
	<link xl:to="docs.xmldb"/>

Inside LinkBases you can have XLink arcs and locators:
(unfortunately this approach requires calculating relative paths 
between assets)

	<ext xl:label="external.xindice"
	  xl:title="Home page of ...">Apache XIndice</loc>

	<int xl:label="docs.xmldb"
	  xl:title="How to use XML:DB with Cocoon">XIndice</loc>

	<int xl:label="docs.sql"
	  xl:title="How to use SQL with Cocoon">SQL</loc>

	<!-- you can specify links externally to the documents themselves -->

	<home xl:to="home"/> <!-- link every page that uses this 
linkbase to home -->

	<note xl:from="docs.sql" xl:to="docs.xmldb">
		You might also like to read about using XIndice with Cocoon
	</note >

	<note xl:from="docs.xmldb" xl:to="docs.sql">
		You might also like to read about using SQL with Cocoon
	</note >

My solution to the relative links problem (probably not 
acceptable to Cocoon docs) in sites like KISS 
<> has been to use the 
xlink:label as the actual URL that the browser uses, and the 
xlink:href as the internal reference for retrieving the asset, 
meaning I am effectively using my linkbase as a Generator, thus 
every document is "in the same folder" as the browser sees it, 
greatly simplifying the urls for embedded assets etc.

Furthermore, every page shares a "LinkMap" an 
application-specific (but XLink compliant) structure of nested 
arcs which describe the site hierarchy and provides the basis 
for the expanding and collapsing menu on the top left (burrow 
into the site to see the effect).

Cocoon docs already have this concept, but broken down into 
small components.

Since the Cocoon docs are accessed live as well as rendered as 
static html, we need to solve the relative url problem somehow. 
Luckily since we have Ant getting Cocoon to generate the docs, 
we have some leeway.

Enough ramble ..... ;)

regards Jeremy

To unsubscribe, e-mail:
For additional commands, email:

View raw message