ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Kev Jackson <>
Subject Re: Ant documentation
Date Wed, 09 Mar 2005 07:46:23 GMT

> 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
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:
For additional commands, e-mail:

View raw message