ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Erik Hatcher <jakarta-...@ehatchersolutions.com>
Subject Re: ant documentation
Date Sun, 05 Jan 2003 20:50:32 GMT
On Sunday, January 5, 2003, at 01:57  PM, Antoine Lévy-Lambert wrote:
> 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:ant-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:ant-dev-help@jakarta.apache.org>


Mime
View raw message