ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Steve Loughran <ste...@apache.org>
Subject Re: sandbox gendoc
Date Thu, 12 Jan 2006 21:42:21 GMT
Dominique Devienne wrote:
>>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?

probably (spelling?)

> 
> 
>>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.

I think think docbook is interesting but something that should be hidden 
from users by a docbook editor, not handwritten. Also its too low-level; 
I want to mark something as a <task>, not as a bit of code.

> 
> 
>>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.

I'd like to see a machine generated manual, with PDF alongside the 
online stuff. I've been using things like hibernate, and their docs are 
impressive.


> 
> 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

If we set this up, I'll try and help with markup in the source. Vested 
interest: I need to make another summary of all the tasks when I get 
that far in the book.

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org


Mime
View raw message