cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ovidiu Predescu <>
Subject Re: documentation of components in */cocoon.xconf
Date Sun, 11 Nov 2001 18:30:20 GMT
Hi Bernhard,

I'm taking a similar approach with your DTDs documenting some of the
logicsheets and XML configuration files.

One thing that you should be able to do is to extend the stylebook DTD
instead of writing a new one that has the same elements. Here is for
example such a DTD for documenting other DTDs.

Stefano did such a great job writing the stylebook DTD to be
extensible, it would be a waste not to take advantage of this!

<!ENTITY % local.blocks "|element">
<!ENTITY % local.content.mix "|elementref">

<!ENTITY % document-dtd SYSTEM "document-v10.dtd">

<!-- DTD to be used when documenting XML documents. -->

<!-- Starts the documentation for an XML element. -->
<!ELEMENT element (title, description, attributes?, elements?, examples?)>

<!-- name: The name of the element documented. -->
<!ATTLIST element
          id CDATA #REQUIRED>

<!-- The description of the element. -->
<!ELEMENT description (%blocks;)*>

<!-- Documents the attributes of an element. -->
<!ELEMENT attributes (attribute)+ >

<!-- Documents a particular attribute of an element. -->
<!ELEMENT attribute (description)>

<!-- name: The name of the attribute.
     type: The type of the attribute. -->
<!ATTLIST attribute
          id CDATA #REQUIRED
          type CDATA #REQUIRED
          defvalue CDATA #IMPLIED>

<!-- The default value of the attribute. -->
<!ELEMENT defvalue (%text;)>

<!-- The list of elements that can be embedded in the documented element. -->
<!ELEMENT elements (elementref)*>

<!-- Reference an element. The element must be documented in the same
     XML document. -->
<!ELEMENT elementref (description?)>

<!-- name: The name of the documented element we are referring to. -->
<!ATTLIST elementref
          name CDATA #REQUIRED>

<!-- examples: Starts the examples for the element -->
<!ELEMENT examples (example)+>

<!ELEMENT example (%blocks;)*>

Ovidiu Predescu <> (inside HP's firewall only) (my SourceForge page) (GNU, Emacs, other stuff)

On Sun, 11 Nov 2001 17:13:59 +0100, "Bernhard Huber" <> wrote:

> Hi, david
> I was making some effort to documentation of cocoon.
> As I was writing a transformer for URL rewritting I was trying to make some
> more formal approach to documentation of this cocoon component.
> (I was some what jealousy about the well document structs project.)
> I was extending the idea of faq2document.xsl approach.
> Perhaps the DTD for cocoon-components is not general enough,
> at the end cocoon-components should be for documenting, and generating
> deployment descriptors.
> I was only taking a quick look at xdoclet approach, which extends doclet.
>  Using this approach you write more javadoc @tags in your java-source code,
> and special ant taks will generate xmlish-documents.
> Any ideas?
> I put a zip in the attachment containing the xml, and xsl files, 
> including some template.
> I hope this helps, at least that more, and better documentation of 
> cocoon is created.
> David Crossley wrote:
> >One of the big todo items before final release is to 
> >document everything in cocoon.xconf
> >There are various xconf files:
> > documentation/cocoon.xconf
> > webapp/cocoon.xconf
> >
> > webapp.tutorial/WEB-INF/cocoon.xconf
> >
> >Before we all dive in and document our favourite component,
> >i thought that it would be a good idea to tidy these files to
> >make them more readable and consistent. There were a lot of
> >differences that were not necessary (e.g. indentation)
> >so i fixed that. I also added consistent structure for the
> >comment section for each block. I have not added anything
> >new - just aligned and tidied the files as a start.
> >
> >Now it can be more clearly seen that there are some differences
> >between the various xconf files. Anyway, we can each
> >attend to that, now that there is a consistent base.
> >
> >I am holding back on these commits, because today is RC2
> >day. Should i do it now or later?
> >cheers, David

To unsubscribe, e-mail:
For additional commands, email:

View raw message