ant-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Steve Loughran" <stev...@iseran.com>
Subject Re: Ant Core Task Quick Reference
Date Sat, 04 Jan 2003 20:31:22 GMT

----- Original Message -----
From: "Kenneth Lee" <kennethl@netvigator.com>
To: "Ant Users List" <ant-user@jakarta.apache.org>
Sent: Saturday, January 04, 2003 09:55
Subject: Re: Ant Core Task Quick Reference


> Thank you. I was once thinking about doing something similar.
> But then I realize that keeping another set of documentation is likely
> to have it not-synced with the rapidly changing core manual.

One word: xdoclet. That's how we (well Erik) autogenerated the quick
reference in our book, and some of the very new tasks (setproxy, all the
apache axis tasks) are autogenerated from the same tags.

>
> Moreover, as a beginner, I find that the existing core manual has
> inadequate information and examples to follow, ambiguous and
> incomplete in some areas, and inconsistent for both content and
> layout.

A quirk of history and the fact that open source projects are done by
volunteers. You may not appreciate it, but compared to other projects the
Ant stuff is very good.

>
> So I propose that the core documentation to be rebuilt from scratch,
> probably in XML, so that different views of the manual (normal view
> as well as quickref and index) could be generated in a unified manner
> (thru XSLT and CSS.), for both core docs and third-party docs.
> The information in the XML may also be useful for some Ant build file
> editor. An online (or offline) searchable manual is also a very good
> helper. There should be a repository of the documentation of all commonly
> used tasks, including core and third party tasks.

Are you volunteering to do it?

> May be there should be an Ant-doc subproject?

I dont think we need to go that far, we just need
(a) Xdoclet markup enhancements to bind the docs to the task source
(b) XSLT xforms to generate HTML, PDF output
(c) someone to move everything else to a docbook format for autogen of html
or PDF

Adding new markup to every single task is hard work, I should point out. We
currently have a lot of duplication in the .java and .html content, but the
.html is still richer. We need to get to a point where xdoclet generated
docs is the core of the ant task reference, and the rest is handwritten
docbook XML.


> I sincerely hope that there will be a more complete, well written Ant
> documentation which could benefit to all of us, both experienced or
> beginners.

Well, Ant always appreciates new documentation; if you have more to add, or
corrections to make to the existing stuff, get on board.


--
To unsubscribe, e-mail:   <mailto:ant-user-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:ant-user-help@jakarta.apache.org>


Mime
View raw message