b) Erik Hatcher is proposing something even more radical
(correct me if my schema is wrong)
|------------| |--------------| |--------------|
| ant | xdoc generation | generated | | manual in |
| source code|-->--with a new xdoclet-->--| xml documents|->---transformation----->| html or pdf |
|------------| ant task |--------------| engine |--------------|
Why is this so radical? The Ant source has the information of attributes and elements supported for tasks so this seems incredibly right and straightforward to me. Am I missing a reason why this is not the only truly viable solution to this?
By the way, Erik, I am not sure whether you wrote how you are going from xml to html or pdf. Is it with Forrest, Cocoon, Docbook, something else ?
Look at the proposal/xdocs/dvsl directory. Someone else contributed the DVSL pieces and had it generating HTML very nicely. This still works, in fact.
- need for a reasonably quick decision for developers to know where/how to maintain the documentation :
Documentation for tasks, attributes and elements should be in the .java file for the task as Javadoc comments. Otherwise we'll be stuck with the same situation we have now where we have to maintain two separate files and that easily gets out of sync.
- support for incremental transition :
If the Erik's solution is chosen, maybe it would be a good idea to define special tags to put
in the java source code of each task to say if the automatically generated documentation is good
enough for the task or not yet.
For instance @xdocfinished or @xdocinprogress
Each time a document would be @xdocfinished, the corresponding html file of the ant documentation
could be removed from CVS. When building ant, it would be generated.
for instance, if src/main/org/apache/tools/ant/taskdefs/Zip.java has @xdocfinished in its header,
the commiter would remove docs/manual/CoreTasks/zip.html from CVS too.
Would this be an acceptable roadmap to migrate from the current static manual to a new, generated manual,
while insuring that in any case all ant developers know whether they should maintain xdoc tags in the source
code or html files under manual to convey how to use their tasks ?
As for migration - I haven't thought through all of the issues, but it seems we just generate in parallel until we are happy with the XDoclet generated way. The main issue is how to handle the samples and merging them in. The DVSL piece does that, or at least it used to unless I broke it.
Erik, your documentation extracted out of the java code is quite convincing.
( http://www.manning.com/hatcher/appendixE.pdf )
Thanks!
Steve and I worked really hard to get Ant's Javadocs up to this challenge and it seems to have paid off.
Erik
-- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
