You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@cocoon.apache.org by Andrew Savory <an...@luminas.co.uk> on 2003/03/12 15:17:55 UTC
Re: [RT] Cocoon's own publishing system
[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
Re: [RT] Cocoon's own publishing system
Posted by Andrew Savory <an...@luminas.co.uk>.
On Wed, 12 Mar 2003, Diana Shannon wrote:
> > - 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.
Ok, that's cool. Freezing relevant doc trees is the right way to go then,
as we really don't want people updating the wrong things.
> 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
> expertise.
Hmm. Just trying to think of the situations that we need to put version
content in, and how it might be used.
As I understand it, we'll have one set of docs, from which we need to
build documentation for 2.0, 2.1, 2.x. So "build docs" on a given version
would ideally either:
- create docs with ONLY content applicable to the version being built
or
- create docs with flags to say "in version X, ..." (useful for people
to see when they'd need to upgrade/downgrade?)
> > 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?
Not sure I follow you here -- do you mean CVS wasn't expressive enough, or
that Dublin Core wasn't expressive enough?
If you mean the former, yes, I guess CVS may be a bit limited in what it
could do ... we may need to use Ant.
If you mean the latter, we could always use Qualified Dublin Core (ie, add
our own subset of tags for a given field, eg creator, to create a richer
markup scheme to cope with whatever else we need to store).
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
Re: [RT] Cocoon's own publishing system
Posted by Diana Shannon <co...@terracare.com>.
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
expertise.
> 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).
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.
Diana