ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Antoine LÚvy-Lambert" <levylamb...@tiscali-dsl.de>
Subject ant documentation
Date Sun, 05 Jan 2003 18:57:49 GMT
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" <jakarta-ant@ehatchersolutions.com>
To: "Ant Users List" <ant-user@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:   <mailto:ant-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:ant-dev-help@jakarta.apache.org>


Mime
View raw message