> 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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
