cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ovidiu Predescu <ovi...@cup.hp.com>
Subject Re: documentation of components in */cocoon.xconf
Date Mon, 12 Nov 2001 19:54:52 GMT
On Sun, 11 Nov 2001 21:58:05 +0100, "Bernhard Huber" <bh22351@i-one.at> wrote:

> Hi,
> thanks for the hint,
> I understand extending the document-v10.dtd only principally. Can you 
> explain it in a bit more detail?

The idea is try avoiding to duplicate in your DTDs all of the elements
already declared in the stylebook DTD. The way the DTD was written is
to allow you to add your own elements to the stylebook DTD. Usually
this is done through the so called parameter entities, defined like:

<!ENTITY % param-entity "">

When a DTD is read by an SGML/XML processor, it will consider only the
first definition it encounters for a given parameter entity. A
customizable entity is usually defined to be empty in the main
DTD. You can override this default definition, to include your own
elements, which will be added to the set of elements recognized in a
certain context.

Take a look for example at the link-content.mix in
document-v10.dtd. You'll notice it uses the local.content.mix
parameter entity, which is defined few lines above as being empty. By
defining local.content.mix to anything you want before you include
document-v10.dtd, you essentially add your new elements to the
definition of link-content.mix:

-- my-new-dtd.dtd ---

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

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

<!-- definition of elementref follows here -->

---------------------

In the above example I define local.content.mix to contain my own
elements, then I include the document-v10.dtd. My local definition of
local.content.mix will take precedence over the one declared in
document-v10.dtd, thus the new link-content.mix will also allow for
<elementref> elements to appear in its context.

You can pretty much add your own elements anywhere in the stylebook
DTD. Just take a look at its definition, and search for parameter
entities.

> I'm doing that documentation stuff, in my spare time.
> Thus I was starting off. Perhaps there are already some more detailed 
> DTDs for documenting
> actions, generators, etc?

As far as I'm aware, there's nothing for this yet. You're more than
free to define them ;-)

Regards,
-- 
Ovidiu Predescu <ovidiu@cup.hp.com>
http://orion.rgv.hp.com/ (inside HP's firewall only)
http://sourceforge.net/users/ovidiu/ (my SourceForge page)
http://www.geocities.com/SiliconValley/Monitor/7464/ (GNU, Emacs, other stuff)

> Ovidiu Predescu wrote:
> 
> >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">
> >%document-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;)*>
> >
> >
> >Regards,
> >

---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org


Mime
View raw message