cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nicola Ken Barozzi <>
Subject Re: [RT] Moving towards a new documentation system
Date Sat, 11 Oct 2003 13:09:02 GMT
Bertrand Delacretaz wrote:
> Le Samedi, 11 oct 2003, à 14:25 Europe/Zurich, Nicola Ken Barozzi a écrit :
>> Bertrand Delacretaz wrote:
>>> ...We can then build all kinds of navigational structures, trails, 
>>> multiple tables of contents, beginners/advanced, whatever (again 
>>> picking up on wiki idea of a flat page structure with many navigation 
>>> paths), but the path to a given document stays valid forever unless 
>>> documents are removed.
>> Forrest's site.xml is ready to adapt to the needs.
> ok. I'd prefer multiple "navigation definition" files though, one for 
> each "navigation concern" (tracks, beginner/advanced, 
> functionality-based, etc).
> Is this possible with Forrest, or what do you suggest?

site.xml is a file that keeps all the site navigational structure in one 
place. The upside is also that you can link to pages using a 
site:nameofnode syntax, so that changing pages does not break links as 
long as you update site.xml.

In there we also have a resources section, that are not part of the 
navigational structure but are easy to use for site: page linking.

My opinion is that it would be swell to add a "navigations" section that 
contains navigational concerns, each differently named. It has also been 
proposed some time back too BTW, it just needs someone to do it.

>> ..Eh, why "Forrest /probably/ "?
> Only because I haven't been following it lately and don't know much 
> details about where it is and where it is going.

It's there just to be what you want the documentation to be :-)

> Nothing against Forrest!

Pfew! ;-)

>>> ...
>>> -if the docs format changes for the new doc management system, 
>>> navigation definitions stay valid.
>> There was a discussion on Forrest about making all links be done to 
>> files without extensions, and now we use site.xml to reference these 
>> links.
>> The only thing that is still lacking is making the output remain 
>> "static" over time.
> Not sure if I understand this, can you explain?

I mean that in the docs I can refer to a page via the site: system. If I 
keep the site.xml links uptodate, all my links in all my pages are correct.

But this is on *source*. Forrest translates the links to the correct 
location on disk, which has changed. Hence doc writers have no issues, 
but links break.

What we need is to cater for these changes and add a "history" system 
that tracks changes to the site.xml nodes, that are our defined URI 

BTW, Forrest has a simple revision system, take a look in Forrest.

>> ...What I wanted to do is to have Forrest generate an index of pages 
>> and the users add this to CVS. With this index we have all the doc 
>> history, and Forrest can generate redirects if urls change. I also 
>> want want to generate redirects for filenames without urls and add an 
>> unique id to every page in the index, so that Forrest can add barcodes 
>> to the pages.
> Sounds good.

It's a bit lonely out there. If Cocoon developers would be at Forrest to 
discuss these things it would be much better.

>> ...Please don't forget Forrest.
> Certainly not!


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

View raw message