cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Robert Koberg" <>
Subject RE: [RT] Moving towards a new documentation system
Date Sat, 11 Oct 2003 15:13:43 GMT

> -----Original Message-----
> From: news [] On Behalf Of Nicola Ken Barozzi
> Sent: Saturday, October 11, 2003 7:54 AM
> To:
> Bertrand Delacretaz wrote:
> ...
> >> ...Messy. what would something like this behave?
> >>
> >>  22003-this-is-first-doc.xml
> >>  22003-this-is-second-doc.xml
> >> ...
> >
> > that's what I meant by the system having to ensure the uniqueness of
> > IDs. It is certainly problematic.
> Look at Forrest, we have been having super-easy revision for a while now.
> howto-multi.xml
> revision-howto-multi-2003-09-14.xml
> revision-howto-multi-2003-09-15.xml
> Here is how it shows:
> So you always get the latest version and can also see the revisions.
> > I agree that a pure ID for naming pieces  of content might be better,
> > provided lookup is super-easy and doesn't get in the way of editing,
> > keeping track of changes etc., and the ID's stay readable and
> > "communicable".
> I really think that using ids /instead/ of filenames is not a good idea.
> URIs are about where to find a certain information, not necessarily with
> a specific date version.
> That's why the Forrest revisions have a defined date (or number) in the
> name, so that that stays the same.
> What I would propose, and that I would like to implement, is an indexing
> system that scans all source files and associates a number with that file.
> This means that a file can have a barcode attached to it, and if we keep
> a repository of site barcodes, we can have a fully resolvable barcoded
> page.
> Then, when pages are added or changed, the system would index the files
> again, and add other new pages with incremented numbers.
> Note that there is another trick in this: if I also index site.xml, I
> can get to know the *history* of the site: ids, and can automatically do
> redirects.
> For example, I start with this site.xml.
>   <site label="My Site">
>     <mynicepage label="Nico Page" url="nicepage.html"/>
>   </site>
> I can refer to that in my docs as:
>    <link href="site:mynicepage">
> (note that site nodes can be hierarchical)
> Then one day I change the node to be:
>   <site label="My Site">
>     <mynicepage label="Nico Page" url="newnicepage.html"/>
>   </site>
> The system would understand that the node leads to another page, and
> would generate redirects from the previous link to the new one.
> Of course, we can do this *if* we don't create different pages at the
> same old locations, unless we generate URIs following site.xml instead
> of the file structure (I do not reccomend ATM).

Wasn't this all a conversation from a couple of years ago? It is good to see
opinions change...

First, forrest's site.xml should change the element names to something
generic, like:

<site label="My Site">
  <page id="p34568656" label="Nico Page" url="newnicepage.html"/>

So the site.xml can be validated. In its current state a custom schema would
be required for each site.xml instance -- just doesn't make sense. The
element names are currently being used as identifiers. Why not simply make
them valid IDs?

Also, much more site/folder/page metadata can be applied to nodes to trigger
certain things in a transformation.

Next, why wouldn't you recommend using the site.xml as the site structure?
The site.xml should be a *virtual* representation of the site. This way
(with a validatable site.xml) it is easy to build a tool (in javascript)
that can manipulate it. 

The static site gets generated from the site.xml using the site.xml as a
main Source xml for a transformation. This way all nav and content links can
*always* be valid base on the virtual representation.


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

View raw message