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
