ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Bill Burton" <bi...@progress.com>
Subject Re: Official direction for xdocs
Date Sun, 17 Feb 2002 05:33:42 GMT
Hello,

Paul Hammant wrote:
> 
> Question : What is the official direction for xdocs?

Well, I can't speak officially, but from various discussions on this list,
it does appear something the committers would like.  

> Context : We used to have a <stylebook> taskdef (but we had o build a
> special optiona.jar as things were missing from download).  I've seen a
> lot of <java> invocations of Cocoon to do the same thing now.  Where are
> we going for this?  Will we ever be able to download an Ant distribution
> that allows building html docs from xdocs out of the box?

Along this line, I've been doing some experimenting using DVSL
(http://jakarta.apache.org/velocity/dvsl/index.html) to generate Ant
manual and task pages.  Right now, the only page committed is for the
<dvsl> task
(http://jakarta.apache.org/velocity/dvsl/ant_task_reference.html) and it
was styled using the default site.dvsl without any specific support for
Ant.  The XML DTD I used for this page is the same as that for all of the
Jakarta site.  The advantage of this is many of the committers are
familiar with this format and it's also easy to work with.  From my
experimentation thus far, this DTD seems to work well with the Ant manual
and task reference pages.

However, selecting and configuring the tool used (whether Docbook, DVSL,
etc.) is not the biggest issue but rather the effort it will take to
convert from the existing HTML to XML.  

Although I'm sure everyone would agree this would be excellent, just doing
a straight conversion would not help the issue of keeping the docs in sync
with the tasks.  A better goal would be to generate much of the XML
documentation directly from the .java task source itself.  

Some recent work on the Myrmidon proposal could be useful in this area. 
XDoclet (http://xdoclet.sourceforge.net/) is being used to generate XML
task configuration files directly from doclet tags placed in the javadoc
comments of the tasks, i.e. @ant:task name="javac".  So although
documentation isn't being generated in this case, it's possible XDoclet
could be configured for this purpose.  The real benefit of this seems to
me the ability to generate the documentation for parameter attributes and
nested elements.  Even better if subclassing is correctly supported in the
process.  As it may be akward to maintain the body of the task
documentation within the javadoc comments, XDoclet supports the notion of
"Merge Points" allowing the generated XML to include an existing XML file.

Experimenting with documentation ideas like this would be good way anyone
can help out.  This would probably be a good candidate for a directory
under proposal/sandbox/.

-Bill

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