You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ant.apache.org by Tony Rogers <az...@umd.edu> on 2007/12/18 05:28:13 UTC
Ant Documentation
Hello,
New list member here! My name's Tony. :)
(Actually I joined a little while ago, and I meant to send this e-mail
at that time, but things got busy for a bit. Things are better now.)
I just started to gingerly begin participating in open source stuff.
I've been using OSS for years, so as intimidating as it is for little
ol' me, it's actually kinda cool. :)
I've noticed that many newcomers are offered unit testing and
documentation as good places to start. This works out for me, because
I'm a huge believer in good documentation.
If I'm browsing the repository correctly, it looks like the manual is
written in HTML. I think it would be beneficial to convert the manual
to DocBook. I've done similar conversions before, and if everyone is
okay with it, I'll be glad to get started. (Regarding a web-viewable
version, I can either write some XSL sheets to accompany the DocBook
version, or I understand there's a widely used open source set of
DocBook XSL stylesheets which could also be used.)
-- Tony
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org
AW: Ant Documentation
Posted by Ja...@rzf.fin-nrw.de.
> Well, I found the following project on SourceForge, which uses Java's
> Doclet API such that running JavaDoc outputs data to XML
> instead of HTML:
>
> http://jeldoclet.sourceforge.net/
>
> If the output is XML, then (theoretically) it could be
> transformed into
> DocBook format. Does this fulfill the desired effect?
The target is a user manual.
We could get lots of information from the javadocs, but not all. I see
different possible
sources for information for the manual:
* javasources (javadoc+source):
- description of the task
- description of the attributes and nested elements
* testcases (maybe little bit annotated)
- examples
* merge files
- description of the task
The 'problem' could be, that there could be a different meaning in
"description".
The Ant user needs other information than the user of the Ant API and
JavaDoc is designed for
describing the API.
/**
* This task is documented.
* @ant.task="CoreTask"
*/
public MyTask extends Task {
...
/**
* Sets the name of ...
* @ant.requiredGroup="setName,addName"
*/
public void setName(String name) {...}
public void addName(Name name) {...}
}
<project name="antunit">
<target name="testA">
...
<manual-start>
Dies example does nothing meaningful.
</manual-start>
<mytask name="a"/>
<manual-end/>
</target>
</project>
* description of the task: javadoc of the task
* where to place the manual page: @ant.task
* list of attributes: analyze set*(*) methods (also inhereted ones like
setTaskname)
* description of attributes: javadoc of the setter
* is-required: @ant.required="true|false"
* is-required: @ant.requiredgroup
==> "this is required unless you provide a nested <name>"
@ant.requiredgroup="setName,addName"
- remove the current method name --> addName
- add* is nested for element, set* is an attribute
Just thoughts ...
Jan
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org
Re: Ant Documentation
Posted by Steve Loughran <st...@apache.org>.
Matt Benson wrote:
> You can also read about the gendoc sandbox Antlib at
> http://ant.apache.org/antlibs/sandbox.html . For some
> reason this has been in the sandbox over 2.5 years. I
> don't know where the time has gone...
>
we use this @work to generate docs for libraries other than Ant
itself...it would be nice to be able to generate docs of ant tasks that
work outside ant's own manual
At work I'd be happy with java1.5+ annotations for this...for java1.4
and below we could use whatever testng does to get the tags from javadocs.
Regarding docbook, I would be -1 to writing our docs themselves in
docbook, +1 for some format that could be turned into docbook. Why?
because docbook is pretty low level. You may have an emphasis section
rather than <i> or <b>, but you would be better off with
project-specific XML clauses/or at least div/span IDs, e,g <span
id="taskname" />, <div id="antxml" />, so that you can choose better
formatting from XML.
For docbook I've used the xml toolchain that goes through LateX; printed
output is very nice.
--
Steve Loughran http://www.1060.org/blogxter/publish/5
Author: Ant in Action http://antbook.org/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org
Re: Ant Documentation
Posted by Matt Benson <gu...@yahoo.com>.
You can also read about the gendoc sandbox Antlib at
http://ant.apache.org/antlibs/sandbox.html . For some
reason this has been in the sandbox over 2.5 years. I
don't know where the time has gone...
-Matt
--- Tony Rogers <az...@umd.edu> wrote:
> Hi,
>
> Thanks for the response. :)
>
> One quick thoughtâ¦
>
>
> Kevin Jackson wrote:
> > The docbook route for ant has been discussed a few
> times previously, I
> > even got the first part of the manual converted to
> pdf via saxen+fop,
> > but the discussion has revolved around a way of
> making the
> > documentation buildable - ie extracting it from
> metadata placed in the
> > Java src.
> >
> Well, I found the following project on SourceForge,
> which uses Java's
> Doclet API such that running JavaDoc outputs data to
> XML instead of HTML:
>
> http://jeldoclet.sourceforge.net/
>
> If the output is XML, then (theoretically) it could
> be transformed into
> DocBook format. Does this fulfill the desired
> effect?
>
> (This entirely depends on how semantically rich the
> output XML is, and I
> have not tested this project myself. But I thought
> you might be
> interested.)
>
> > Please search the archives for previous
> documentation discussions.
> >
> Oh, my. Mailing list archives are intimidating.
> May I request a brief
> synopsis? Nothing lengthy, just a bullet-list of
> pros and cons or
> something similar?
>
> > I'm sure other people will chime in sooner or
> later too :)
> >
> Not so far. :(
>
> Anybody else wanna add their 2 cents?
>
>
> Thanks for your help!
>
>
>
> -- Tony
>
>
>
---------------------------------------------------------------------
> To unsubscribe, e-mail:
> dev-unsubscribe@ant.apache.org
> For additional commands, e-mail:
> dev-help@ant.apache.org
>
>
____________________________________________________________________________________
Be a better friend, newshound, and
know-it-all with Yahoo! Mobile. Try it now. http://mobile.yahoo.com/;_ylt=Ahu06i62sR8HDtDypao8Wcj9tAcJ
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org
Re: Ant Documentation
Posted by Tony Rogers <az...@umd.edu>.
Hi,
Thanks for the response. :)
One quick thought…
Kevin Jackson wrote:
> The docbook route for ant has been discussed a few times previously, I
> even got the first part of the manual converted to pdf via saxen+fop,
> but the discussion has revolved around a way of making the
> documentation buildable - ie extracting it from metadata placed in the
> Java src.
>
Well, I found the following project on SourceForge, which uses Java's
Doclet API such that running JavaDoc outputs data to XML instead of HTML:
http://jeldoclet.sourceforge.net/
If the output is XML, then (theoretically) it could be transformed into
DocBook format. Does this fulfill the desired effect?
(This entirely depends on how semantically rich the output XML is, and I
have not tested this project myself. But I thought you might be
interested.)
> Please search the archives for previous documentation discussions.
>
Oh, my. Mailing list archives are intimidating. May I request a brief
synopsis? Nothing lengthy, just a bullet-list of pros and cons or
something similar?
> I'm sure other people will chime in sooner or later too :)
>
Not so far. :(
Anybody else wanna add their 2 cents?
Thanks for your help!
-- Tony
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org
Re: Ant Documentation
Posted by Kevin Jackson <fo...@gmail.com>.
Hi,
> I've noticed that many newcomers are offered unit testing and
> documentation as good places to start. This works out for me, because
> I'm a huge believer in good documentation.
>
> If I'm browsing the repository correctly, it looks like the manual is
> written in HTML. I think it would be beneficial to convert the manual
> to DocBook. I've done similar conversions before, and if everyone is
> okay with it, I'll be glad to get started. (Regarding a web-viewable
> version, I can either write some XSL sheets to accompany the DocBook
> version, or I understand there's a widely used open source set of
> DocBook XSL stylesheets which could also be used.)
The docbook route for ant has been discussed a few times previously, I
even got the first part of the manual converted to pdf via saxen+fop,
but the discussion has revolved around a way of making the
documentation buildable - ie extracting it from metadata placed in the
Java src.
Please search the archives for previous documentation discussions.
I'm sure other people will chime in sooner or later too :)
Kev
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org