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