Return-Path: 
 <cocoon-docs-return-625-apmail-xml-cocoon-docs-archive=xml.apache.org@xml.apache.org>
Delivered-To: apmail-xml-cocoon-docs-archive@xml.apache.org
Received: (qmail 53005 invoked by uid 500); 12 Mar 2003 14:18:39 -0000
Mailing-List: contact cocoon-docs-help@xml.apache.org; run by ezmlm
Precedence: bulk
list-help: <mailto:cocoon-docs-help@xml.apache.org>
list-unsubscribe: <mailto:cocoon-docs-unsubscribe@xml.apache.org>
list-post: <mailto:cocoon-docs@xml.apache.org>
Reply-To: cocoon-docs@xml.apache.org
Delivered-To: mailing list cocoon-docs@xml.apache.org
Received: (qmail 52925 invoked from network); 12 Mar 2003 14:18:38 -0000
Received: from mail.matrix.msu.edu (35.8.2.176)
  by daedalus.apache.org with SMTP; 12 Mar 2003 14:18:38 -0000
Received: from matrix-40.user.msu.edu (oscar) [35.10.86.157]
	by mail.matrix.msu.edu with esmtp (Exim 3.35 #1 (Debian))
	id 18t742-0007MC-00; Wed, 12 Mar 2003 09:18:38 -0500
Received: from savs (helo=localhost)
	by oscar with local-esmtp (Exim 3.36 #1 (Debian))
	id 18t73L-0000gw-00
	for <cocoon-docs@xml.apache.org>; Wed, 12 Mar 2003 14:17:55 +0000
Date: Wed, 12 Mar 2003 14:17:55 +0000 (GMT)
From: Andrew Savory <andrew@luminas.co.uk>
X-X-Sender: savs@oscar
To: cocoon-docs@xml.apache.org
Subject: Re: [RT] Cocoon's own publishing system
In-Reply-To: <EEB727BA-5474-11D7-A089-0030653FE818@apache.org>
Message-ID: <Pine.LNX.4.51.0303121346490.1233@oscar>
References: <EEB727BA-5474-11D7-A089-0030653FE818@apache.org>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
Sender: Andrew Savory <savs@luminas.co.uk>
X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N


[Moved here from cocoon-dev]

On Wed, 12 Mar 2003, Diana Shannon wrote:

> On Tuesday, March 11, 2003, at 03:22  PM, Andrew Savory wrote:
>
> > On Tue, 11 Mar 2003, Diana Shannon wrote:
> >
> >> I agree 100% with Andrew that two "clearly" separated repositories
> >> won't
> >> really improve on what we had. But it's all we have at the moment.
> >
> > Sure. I'm happy to help try and refactor it down to one archive. Or
> > perhaps we could set up cocoon-docs with the content from 2.1 and then
> > go
> > through and import any 2.0 content that is missing? I'm assuming 2.1
> > is a
> > superset of 2.0 content.
>
> You could say that. A majority of the core docs are the same. Only a
> handful of docs are different at the present time. Clearly this will
> start to change is we get more docs for various blocks/samples and if we
> start importing wiki content.
>
> Do you have a particular approach in mind? If so, then this discussion
> should probably continue on cocoon-docs.

Ok: here's what I'd suggest. It may not be the most efficient or
scientific way, but it will certainly be methodical.

- Create cocoon-doc CVS module
- Populate with content from cocoon-2.1
- Remove cocoon-2.1 docs and point at cocoon-doc
- Individually review 2.0 docs, merging with cocoon-doc content where
applicable
- Remove cocoon-2.0 docs and point at cocoon-doc

Problems with this approach:

- Getting it done quickly enough that changes to docs in 2.0 don't fall
through the cracks. I don't know if we could/should somehow "freeze" 2.0
docs during the process. This will depend greatly on likely time to
completion.

Also, there seem to be a number of ways to indicate the version in the
docs. A quick random sample:

xdocs/faq/faq-sitemap.xml:cachability (since 2.1)
xdocs/howto/howto-flow-debugger.xml:<note>Since: 2.1 2002-12-07</note>
xdocs/userdocs/matchers/template-matcher.xml:<td>SINCE</td><td>Cocoon X.Y</td
xdocs/faq/faq-xslt.xml:Yes. For Cocoon version 2.0.3
xdocs/howto/howto-paginator-transformer.xml:Make sure you have the version 2.0.3 or greater of Cocoon.

etc etc. So we should probably decide on a standard way to denote all of
these (I think SINCE is the preferred method?).

I'm also wondering if we should take this opportunity to add some good
quality metadata to the docs, for example using Dublin Core. This will add
some much needed semantisation, make the docs more widely (and accurately)
visible, and all the other benefits usually associated with resource
description. Here's a possible example:

<?xml version="1.0"?>
<!DOCTYPE rdf:RDF SYSTEM
"http://purl.org/dc/schemas/dcmes-xml-20000714.dtd">

<rdf:RDF
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  xmlns:dc="http://purl.org/dc/elements/1.1/">
  <rdf:Description about="http://url.of.page">
    <dc:title/>
    <dc:creator/>
    <dc:subject/>
    <dc:description/>
    <dc:contributor/>
    <dc:publisher>Apache Software Foundation</dc:publisher>
    <dc:date/>
    <dc:type/>
    <dc:format/>
    <dc:language/>
    <dc:relation/>
    <dc:coverage/>
    <dc:identifier/>
  </rdf:Description>
</rdf:RDF>

Before you all go "eek!" and run away, most of these fields can be
automagically generated either by CVS (contributor, creator, date) or by
stylesheets (type and format).

This allows some seriously cool stuff: cocoon-docs as RDF/RSS (anyone for
a "cocoon-docs latest additions" news feed?), cocoon-docs as an OAI data
provider, to name but two.

What do you all think?


Andrew.

-- 
Andrew Savory                                Email: andrew@luminas.co.uk
Managing Director                              Tel:  +44 (0)870 741 6658
Luminas Internet Applications                  Fax:  +44 (0)700 598 1135
This is not an official statement or order.    Web:    www.luminas.co.uk