forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <cross...@apache.org>
Subject Re: [Fwd: RefDoc - Neutral XML Document Format Input/Current State]
Date Sun, 07 Aug 2005 05:45:32 GMT
Cyriaque Dupoirieux wrote:
> Diwaker Gupta a ?crit :
> 
> >This sounds exciting. Do we have access to any example/samplout output of 
> >RefDoc?
> >
> >One of the interesting possibilities is to generate examples 
> >automagically. For instance by correlating the Java source file for a 
> >Cocoon Generator with its usage in a processing pipeline.
> >
> >w.r.t Forrest, it would be nice to have a way of generating more friendly 
> >documentation of the DTDs. The current DTD documentation is good, but I 
> >think it could get better.

Please see the DTDx plugin todo notes [1] and issue FOR-221 [2].

[1] http://forrest.apache.org/pluginDocs/plugins_0_70/org.apache.forrest.plugin.input.dtdx/todo.html
[2] http://issues.apache.org/jira/browse/FOR-221
    "NekoDTD generated dtd documentation needs improvement, some bugs".

The NekoDTD parser author would be pleased to receive patches.

I agree that other representations of the DTDs could also help.

> Right now its a very "mechanical" kind of 
> >documentation -- just listing the attributes and children and parents and 
> >so on. A little more annotated DTD documentation would be great (what does 
> >each element mean, what are recommended usages and so on).
>
> Excellent idea, I remember - when I was young - that I spent lot of time 
> to understand how I could have the former link and fork behaviour 
> whereas we only have <a> tag in document-v20.
> Maybe a little comment of the author used to be displayed in the 
> generated documentation should have helped me...

However the documented examples would have helped.
[3] http://forrest.apache.org/dtdx/document-v20.html#changes

Anyway, it will be very good if the RefDoc work can help
with enhanced DTD documentation.

How far can we go there? I mean, if the contents of [3] were
all embedded in the actual DTDs, then the DTDs would become
rather bloated. Perhaps have some minor explanations, but
still use specific example documents for the full story.

David

Mime
View raw message