ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dominique Devienne <>
Subject Re: sandbox gendoc
Date Thu, 12 Jan 2006 14:59:48 GMT
> I've had a look through the sandbox and I noticed Dominique's (sp?) xml'd
> version of the docs.

what does (sp?) means in this context?

> As you know I had a play with DocBook-izing the manual last year and in
> the end the effort of manually altering every html page to be valid
> DocBook xml drove me mad (gibber etc).  Also there seemed to be a
> consensus (or rather a few well informed arguments against DocBook in
> general) that DocBook was not the way to go for the ant manual[1]

Yes, DocBook, also a standard, is indeed very verbose and doesn't seem
to have the favor among commiters.

> So I've had a look at the gendoc version (all 2 manual pages + whatsnew)
> and I thought that if this is at least in the sandbox, it's 99% more
> official than choosing a.n.other xml.

Well, it's hardly official in any way, but it's a start. Note though
that there were objections regarding the verbosity of schema chosen,
which I tried to address in another version not in SVN. I was trying
to have a looser schema, easier to write by hand, which would be
converted to the canonical, more verbose and structured XML, for
further processing.

> Given this I'm preparing a little script to automate the conversion of
> the html docs to the xmlised version in the sandbox.
> So far I'm trying to get it to work correctly with echo, but most of the
> code is generic so when I get a passable version of that I'll refactor
> (a lot) and run it against the doc directory.
> Given the formatting issues of html, I expect at least a little manual
> intervention along the way, but manually converting all the docs would
> be insane (there's over 400 in the core tasks directory alone)

Yes, I thought that would be the way to go as well down the line,
parsing the HTML with tagsoup or the xerces-native-api based Sax
reader for HTML (don't recall it's name). Given how the examples are
usually all together, I thought there would need to be more that just
a little editing, to sprinkle <div class="example"> all over the
manual. But all in all, I didn't do any of the above, as I didn't much
of the whole gendoc thing. I simply thought premature to write a
script to convert the HTML manual into this XML, is the back end
processing of the XML manual wasn't there.

> Anyone interested in the results?

I am. I think it would be valuable work, provided gendoc goes
somewhere. As is obvious, I'm having trouble devote enough time to it.
The one piece of advise I'd give you is to not throw write a one time
throw away converter, as I'd foresee the HTML and XML manual to
co-exist for some time, until the XML version matures enough. Doc
fixes would go on in the HTML version most likely only. As long as a
little structure is added to the HTML with <div>s and CSS classes, the
converter should continue working.

This would take care of the manually written manual, but remains the
part that extracts from the sources and IntrospectionHelper all the
relevant attribute/element information from tasks. --DD

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message