AW: Ant documentation
> > > > I made an attempt to convert the manual to HTML 5, the rationale > > > being > > > > that HTML 5 deprecates tt tag and recommends to replace it with > > > > tags like code, kbd, samp and var, which could be used in a more > > > consistent > > > > way to achieve something closer to a semantic markup. > > > > > > > > I tried then to use the replacement tags as consistently as > > > > possible in such a large body of text, but I realised that we > > > > perhaps need a kind of a style guide. Would you like to discuss > > > > it? Where would it best fit in the source code tree? > > > > > > > > > > Isn't the HTML manual generated? Sure it's checked-in, but I > thought > > > there was a generation process. > > > If that's the case (I may have dreamed it) then it's likely the > > > generator that needs fixing, not the build product. --DD > > > > No. There were some experiments and maybe some pages were generated > > during that experiment. > > But the manual is a manual work. (double manual ;) > > https://svn.apache.org/repos/asf/ant/sandbox/historical/xdocs/ > > > > One may use xdoc and generate html with Doxia by calling its CLI. > However, Ant sorely lacks a site generator on par with Maven site > plugin. All generation requires a model to generate from. AFAIK the site-plugin uses the pom for this purpose. We don't have such a model in Ant. Also I can't remember a wish for that. Additionally I don't know any project (in my company) that uses these sites. Maybe they are useful for open source projects. I don’t think that we should spend any effort into that. But Ant is an OS project - if you want to do a prototype you're welcome. Jan - To unsubscribe, e-mail: dev-unsubscr...@ant.apache.org For additional commands, e-mail: dev-h...@ant.apache.org
AW: Ant documentation
> > I made an attempt to convert the manual to HTML 5, the rationale > being > > that HTML 5 deprecates tt tag and recommends to replace it with tags > > like code, kbd, samp and var, which could be used in a more > consistent > > way to achieve something closer to a semantic markup. > > > > I tried then to use the replacement tags as consistently as possible > > in such a large body of text, but I realised that we perhaps need a > > kind of a style guide. Would you like to discuss it? Where would it > > best fit in the source code tree? > > > > Isn't the HTML manual generated? Sure it's checked-in, but I thought > there was a generation process. > If that's the case (I may have dreamed it) then it's likely the > generator that needs fixing, not the build product. --DD No. There were some experiments and maybe some pages were generated during that experiment. But the manual is a manual work. (double manual ;) https://svn.apache.org/repos/asf/ant/sandbox/historical/xdocs/ Jan - To unsubscribe, e-mail: dev-unsubscr...@ant.apache.org For additional commands, e-mail: dev-h...@ant.apache.org
AW: Ant Documentation
> 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) {...}
}
...
Dies example does nothing meaningful.
* 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 "
@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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
AW: Ant documentation
> > Not unless we move to Java1.5 attributes :) > > This may be a while No - I wouldnt change from 1.2 to 1.5 as minimum for Ant ;-) Jan
AW: Ant documentation
> >It's often frustrating, like IE eating up the space text nodes, > >so the XML syntax highlighting I describe above doesn't work with > >IE, and needs to be done with a proper (standard compliant) XSL > >engine (Xalan, Saxon, FireFox's XSL engine, etc...), but it's > >rewarding work ;-) I like it's functional model. > > > >XSL 2.0 looks very promising has an improvement over 1.0, > >being even more functional, and having regexp and sequences, > >but that requires Saxon. I don't know how people feel about > >a Saxon 8.x dependency. > > > > > This should not be too much of a problem. It will be used > during the build phase (in the same way that junit is used), > and maybe using , however it would be nicer > just to use xalan. We have a more "non-standard" dependency than JUnit (which is nearly in every project :) : jakarta-site for generating the homepage from xdocs. If Saxon is only need during the build process of Ant and if its free, we could use that - if it´s really better that "our own" (ASF) xsl engine. Jan
Re: AW: Ant Documentation
[EMAIL PROTECTED] writes: >> I am trying to improve the Ant documentation. > >> I am using an approach which, with the help >> of some scripts I am working on, will finally result >> in a DocBook Ant manual. As a stepping stone to this end >> I am doing the document in LaTeX. > >So you will write the Ant doco in LaTeX? Yes. > >Rewrite the whole docs??? Yes. > >... and future modification of the docs? No. > >> I have an awk script >> to do the LaTeX2DocBook conversion. This needs to be >> rewritten in Perl so that it is portable. > >Ok, perl is fine. For faster port to windows you can use >Cygwin. I think it contains an awk. Yes it does. I already have the awk script. I intend to move straight to perl. > >> Attached is the result of running latex2html on the source. >> Please let me have some feedback on this ASAP. > >I got no attachements. Please see http:/www.marlowa.plus.com/a2.tar.bz2 This is a bzip'd tarball of HTML generated from the LaTeX source. > > >> This is quite alot of work and I am only roughly half-way through. >> I need to know if people will be happy with this. > >Sure - many people asked for printable versions of the ant doc. And >you can print LaTeX docs very well :-) I know :-) > > > >Jan > Regards, Andrew There is an emerald here the size of a plover's egg! - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
AW: Ant Documentation
> I am trying to improve the Ant documentation. Always welcome :-) > I would like to have a single multi-platform open format > document. I understand that the project preference is to > use DocBook. DocBook? That´s really new to me. I only know the plain HTMLs. There are tests generating the docs via XDoclet, but DocBook... > I am using an approach which, with the help > of some scripts I am working on, will finally result > in a DocBook Ant manual. As a stepping stone to this end > I am doing the document in LaTeX. So you will write the Ant doco in LaTeX? Rewrite the whole docs??? ... and future modification of the docs? > I have an awk script > to do the LaTeX2DocBook conversion. This needs to be > rewritten in Perl so that it is portable. Ok, perl is fine. For faster port to windows you can use Cygwin. I think it contains an awk. > Attached is the result of running latex2html on the source. > Please let me have some feedback on this ASAP. I got no attachements. > This is quite alot of work and I am only roughly half-way through. > I need to know if people will be happy with this. Sure - many people asked for printable versions of the ant doc. And you can print LaTeX docs very well :-) Jan
