ant documentation

[Antoine L�vy-Lambert <le...@tiscali-dsl.de>]

I would like to try to summarize the debates relating to ant documentation on the ant-dev and ant-user
mailing lists.

1) current situtation :
   the ant documentation consists mostly of :
        - ant manual, hand written, may or may not diverge from the potentialities offered by the ant classes
        for instance, it is possible to forget to :
                   - describe an existing task, 
                   - describe an existing attribute of a task
      on the other hand, the manual contains a lot of examples and hints which are not in the code
      - api manual, generated by Javadoc

2) different alternatives concerning the workflow in the future
a number of emails have been sent putting forward proposals to change this status quo.
typically, the new workflows which are proposed are of this type :

a) FakeForrest or Docbook solution with static xml documents
 
|--------------------- |                                   |--------------------- |
| static xml documents | --->---transformation  ----->-----| manual in html format| 
|--------------------- |        engine                     |--------------------- |

in the case a there is already some debate about :
   - which dtd and which transformation engine should be used
Nicola Ken Barozzi says if I understand well that we should use forrest
Costin Manolache seems to prefer docbook

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              |--------------|
                    
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 ?


I have the following concerns/suggestions :


  - need for a reasonably quick decision for developers to know
where/how to maintain the documentation :
there should be quickly votes to decide which way the ant
documentation is going, so that, whatever decision is taken, people
know which files should be worked on (source, xml , or html) to change
the actual manual available to ant users,

  - clear concept definition :
the workflow to generate the documentation of ant should be clear

  - availability of tools :
the tools needed to do the documentation generation should be listed
developers should be able to test quickly how their documentation
looks like in "end user format", typically html
One of the problems in the beginning might be that people will stumble
on "how do I type in the xdoc tag in java a semi colon, so that it is
actually rendered as a semi colon in the html or pdf" 

 - 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 ?

Erik, your documentation extracted out of the java code is quite convincing.
( http://www.manning.com/hatcher/appendixE.pdf )

Antoine

below an extract of an email of Erik Hatcher to the ant user list


From: "Erik Hatcher" <ja...@ehatchersolutions.com>
To: "Ant Users List" <an...@jakarta.apache.org>
Sent: Sunday, January 05, 2003 12:52 AM
Subject: Re: Ant Core Task Quick Reference


> ....
> 
> Its in progress.  In fact, the past several days I've been refactoring 
> the proposal/xdocs stuff and I'm going to make it part of the XDoclet 
> project as a special set of Ant-specific subtasks to process Ant tasks 
> and datatypes and extract the useful info and XML-ify it.  Its already 
> been done, and the results can be seen here:
> 
> http://www.manning.com/hatcher/appendixE.pdf
> 
> As Steve has already mentioned, there is still a way to go with making 
> documentation as rich as the current HTML docs, but that can be handled 
> with some merge points in XDoclet to pull in some extra files per task 
> to include examples or more.
> 
> Its always been my goal to generate a quick reference of Ant 
> tasks/datatypes, and we achieved this goal mostly already and its 
> dead-on 100% accurate with how Ant works, rather than the current HTML 
> documentation which may (or may not) have holes in which 
> attributes/elements are shown.  Generating from XDoclet will ensure 
> accuracy and allow attribute/element descriptions to be where they are 
> defined rather than separately maintained.
> 
> Erik
> 
> 


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: ant documentation

[Erik Hatcher <ja...@ehatchersolutions.com>]

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:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>