You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ant.apache.org by Kev Jackson <ke...@it.fts-vn.com> on 2005/03/02 05:17:21 UTC
Ant documentation
Since there has been some discussion about prodcuing better docs on the
list I thought I'd look into it.
I've recently debugged the AspectJ teams docbook, so I've had my head in
the docbook format/FOP for a couple of weeks. I've just got a basic
transform to PDF done of the first section (really just a test section
to prove that Fop was doing it's thing) (attached for comments).
The dependencies are pretty hefty, currently I'm using :
Fop (latest 20.5 or something)
Saxon (something like version 6, not sure on this, but it works)
Docbook 4.1.2 I think, again a little unsure, and I've made a couple of
bug fixes to this version too.
Anyway, with the correct config, it's a fairly simple build file to
generate the pdf, although rewriting the manual from html->xml will be a
chore (although by no means impossible :)
Thoughts/comments more than welcome
Kev
Re: Ant documentation
Posted by Stefan Bodewig <bo...@apache.org>.
On Wed, 09 Mar 2005, Steve Loughran <st...@apache.org> wrote:
> I hear that going via TeX gives you the best typesetting.
Absolutely!
And I'll stop here or I'll start moaning about people forcing me to
use Word (fortunately the Office for X version) to create docs that
look so much worse than the ones I created using tetex and pdflatex in
half the time ...
Stefan
---------------------------------------------------------------------
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>.
Stefan Bodewig wrote:
> On Wed, 09 Mar 2005, Kev Jackson <ke...@it.fts-vn.com> wrote:
>
>
>>I've read this thread with interest (as you tend to do when your
>>work is 'critiqued' :) ), but I'm still not sure what anyone
>>actually wants, apart from some kind of generated docs that produce
>>nice HTML output, and as an added bonus can be transformed by Fop
>>into a PDF.
>
>
> The main problem here is that there is no unique answer 8-)
>
> My guess is the following is more or less true:
>
> (1) autogenerate as much of the docs as possible from the Java sources.
>
> (2) throw in additional information in an easy to edit format.
>
> (3) create HTML and PDF versions of the docs from a single source.
>
> An effort to do (1) has been started in the proposals directory
> (xdocs). This one uses XDoclet and I have no idea about its state.
Erik wrote it for the reference for our book; it hasnt been touched much
since. We also had to go through all the source and add the code
snippets. That took a weekend or so. I've used it to generate some ant
docs, plus also in Axis and smartfrog...the sole changes to the build
file was to make third party use easier.
Its brittle, needs -Xmx1024M to work, etc, etc. But it does generate
HTML. Not good HTML, and it loses <pre> formatting in javadoc sections.
Needs
-nested element support
-types, conditions, filters, etc as well as just tasks
-cross referencing
-moving to Ant1.2
> Basically since I never looked at it - I find other things that I
> prefer to work on all the time 8-)
>
> For (2), as much as I'm comfortable with LaTeX, I wouldn't consider it
> easy to edit for a newbie, either. The main things we need as
> additional informations are the examples AFAIK - and in that case a
> custom simplistic XML format may be the best option, something like
IMO, LaTeX is a downstream format :) It's good for doc authoring, but
the output is then mostly .DVI and .PDF: printables.
>
> <example>
> <description>The following fuzzes the foo into a bar</description>
> <code><[CDATA[
> <fuzz from="foo" to="bar"/>
> ]]>
> </code>
> </example>
>
> The less powerful that DTD the better since it would force us to move
> the important pieces of documentation to the code.
A bit like 'pragmatic xml' the pragmatic programmers use, perhaps.
> If the result of (1) and (2) is XML, then it would be a matter of
> stylesheets (be they XSLT or Velocity stylesheets or anything else) to
> go from there to XHTML or PDF. Again, something I personally don't
> enjoy too much, so I walk away and work on something else.
There are tools we can use there. I hear that going via TeX gives you
the best typesetting.
-steve
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org
Re: Ant documentation
Posted by Stefan Bodewig <bo...@apache.org>.
On Wed, 09 Mar 2005, Kev Jackson <ke...@it.fts-vn.com> wrote:
> I've read this thread with interest (as you tend to do when your
> work is 'critiqued' :) ), but I'm still not sure what anyone
> actually wants, apart from some kind of generated docs that produce
> nice HTML output, and as an added bonus can be transformed by Fop
> into a PDF.
The main problem here is that there is no unique answer 8-)
My guess is the following is more or less true:
(1) autogenerate as much of the docs as possible from the Java sources.
(2) throw in additional information in an easy to edit format.
(3) create HTML and PDF versions of the docs from a single source.
An effort to do (1) has been started in the proposals directory
(xdocs). This one uses XDoclet and I have no idea about its state.
Basically since I never looked at it - I find other things that I
prefer to work on all the time 8-)
For (2), as much as I'm comfortable with LaTeX, I wouldn't consider it
easy to edit for a newbie, either. The main things we need as
additional informations are the examples AFAIK - and in that case a
custom simplistic XML format may be the best option, something like
<example>
<description>The following fuzzes the foo into a bar</description>
<code><[CDATA[
<fuzz from="foo" to="bar"/>
]]>
</code>
</example>
The less powerful that DTD the better since it would force us to move
the important pieces of documentation to the code.
If the result of (1) and (2) is XML, then it would be a matter of
stylesheets (be they XSLT or Velocity stylesheets or anything else) to
go from there to XHTML or PDF. Again, something I personally don't
enjoy too much, so I walk away and work on something else.
> I'm willing to lend a hand to get the docs done,
Which really is apreciated, even if my comments may sound different.
> Also with the amount of recent changes (jeez I was away from work
> for one day and someone edited practically every html source in the
> CVS!!),
Yep, but almost all changes only added a new CSS stylesheet.
Cheers
Stefan
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org
Re: Ant documentation
Posted by Kev Jackson <ke...@it.fts-vn.com>.
> I tried to use docbook and ended up hating it too. Not enough macros
> see, you may be describing structure <emphasis></emphasis> rather than
> style <i></i>, but what I want is <todo> and <taskname>, independent
> of the structure to use.
>
> Also, as it doesnt cross-ref across docs, it is not as good as bibtex.
> I have stopped using it for now; it is not for humans to edit.
>
The original bug requesting a PDF manual was fairly old, and one of the
suggestions was to use docbook (one of the reasons why it struck a chord
with me). I don't have anything for/against docbook (I think it's a
massive improvement on pure HTML, but that's in terms of describing
books), simply that I can use it generate a PDF from an xml source, and
the xml can also be used to create xhtml output, and that was
essentially a solution to the posted bug.
>>
>> Anyway, docbook is not worse than HTML, only that people will have to
>> learn it in order to contribute to the docs. I'm not 100% sure that
>> I'd want to go that route.
>
>
> acutally it is worse in that the time from entry to view is longer; at
> least with (X)HTML you can hit reload and view the result immediately
>
I can see this, but isn't that a complaint with all xml sources -> web
readable? Surely pretty much any xml document needs to be transformed
before display. This a weakness of using XML full stop, not specific to
docbook (the xdocs also suffer from this to a degree).
> Also: too verbose, paragraph logic too complex, not enough people know
> it.
Amen! Typing <para> instead of <p> is a pain, having to include <para>
inside a list to get the entries to display is also not great
<itemizedlist>
<entry><para>foo</para></entry>
...
this is way too verbose, infact most of the tags seem to be more verbose
than is necessary. I presume a WYSIWYG editor would make all the pain
go away, but then we're nearly back to using Word [spit], just because
it's easy. I don't mind marking up text, it seems perfectly natural to
have to tell the document how you would like it displayed (exactly, not
some M$ approximation), and if that's using a slick editor that holds
your hand then that's great, but I want to be able to see the structure
of the doc when I open the file in vi.
Maintainability of docbook does seem to be a problem. It isn't widely
used and hence people aren't exposed to it, hence it isn't widely used.
Erm not sure where I'm going with this :)
>>
>> Having the xdocs stuff output the docs as docbook instead of HTML
>> would be fine. But maybe it would be easier to create PDFs using FOP
>> from the output the xdocs proposal currently creates.
>
>
> dunno about the existing output. But we could go straight to Latex if
> we wanted :)
I've read this thread with interest (as you tend to do when your work is
'critiqued' :) ), but I'm still not sure what anyone actually wants,
apart from some kind of generated docs that produce nice HTML output,
and as an added bonus can be transformed by Fop into a PDF. I'm willing
to lend a hand to get the docs done, but I can see that blindly pushing
ahead with transforming the html->docbook xml isn't the right way to go
(if for no other reason than because committers - they that have the say
- don't feel that it's the best solution). Also with the amount of
recent changes (jeez I was away from work for one day and someone edited
practically every html source in the CVS!!), I'd have to somehow merge
these with the xml versions I have - not something I'd actually want to
do. I imagine there's a much simpler solution waiting to be discovered,
but I haven't (so far) had time to look for it.
/me goes to look at Forrest...
---------------------------------------------------------------------
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>.
Stefan Bodewig wrote:
> On Wed, 02 Mar 2005, Kev Jackson <ke...@it.fts-vn.com> wrote:
>
>
>>Thoughts/comments more than welcome
>
>
> Being a LaTeX guy myself, I've grown some bad feelings towards docbook
> when I had to use it on one project. It's so powerless in
> comparision, but maybe that's only due to the default stylesheets and
> could be improved by better styles (something I have no desire to work
> on).
I tried to use docbook and ended up hating it too. Not enough macros
see, you may be describing structure <emphasis></emphasis> rather than
style <i></i>, but what I want is <todo> and <taskname>, independent of
the structure to use.
Also, as it doesnt cross-ref across docs, it is not as good as bibtex. I
have stopped using it for now; it is not for humans to edit.
>
> Anyway, docbook is not worse than HTML, only that people will have to
> learn it in order to contribute to the docs. I'm not 100% sure that
> I'd want to go that route.
acutally it is worse in that the time from entry to view is longer; at
least with (X)HTML you can hit reload and view the result immediately
Also: too verbose, paragraph logic too complex, not enough people know it.
>
> Having the xdocs stuff output the docs as docbook instead of HTML
> would be fine. But maybe it would be easier to create PDFs using FOP
> from the output the xdocs proposal currently creates.
dunno about the existing output. But we could go straight to Latex if we
wanted :)
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org
Re: Ant documentation
Posted by Stefan Bodewig <bo...@apache.org>.
On Wed, 02 Mar 2005, Kev Jackson <ke...@it.fts-vn.com> wrote:
> Thoughts/comments more than welcome
Being a LaTeX guy myself, I've grown some bad feelings towards docbook
when I had to use it on one project. It's so powerless in
comparision, but maybe that's only due to the default stylesheets and
could be improved by better styles (something I have no desire to work
on).
Anyway, docbook is not worse than HTML, only that people will have to
learn it in order to contribute to the docs. I'm not 100% sure that
I'd want to go that route.
Having the xdocs stuff output the docs as docbook instead of HTML
would be fine. But maybe it would be easier to create PDFs using FOP
from the output the xdocs proposal currently creates.
Stefan
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org