cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <>
Subject Re: [RT] Cocoon's own publishing system
Date Wed, 12 Mar 2003 19:16:27 GMT

On Wednesday, March 12, 2003, at 09:17  AM, Andrew Savory wrote:

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

I don't see why a freeze would be a problem. Docs simply aren't updated 
that often. :( We could also have a testing/prototype phase using ant 
scripts to pull content from both repositories.

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

Why can't we use page-based metadata for versioning? It's not as 
efficient when your content isn't very granular (e.g. page-based as 
above), but it will work well for faqs/snippets/how-tos ATM and more 
complex docs could be refactored down the road (e.g. topic map 
approach). Embedding "since" in one form or the other sounds kind of 
messy (maintenance and editing-wise) to me, unless it's an attribute of 
some kind. Think what it will be like supporting versions 2.0x, 2.1x, 
2.2x, ... I'm not an expert here, so I'll defer to those with more CMS 

> 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"?>
> "">
> <rdf:RDF
>   xmlns:rdf=""
>   xmlns:dc="">
>   <rdf:Description about="">
>     <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).

I looked at this about a year ago and thought it not expressive enough 
for our needs. It's isn't obvious to me how/if the above might handle 
software release versioning. Suggestions?

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

Sure, let's hope...

> What do you all think?

Great start, Andrew. Thanks.


View raw message