ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Kevin Jackson <foamd...@gmail.com>
Subject Re: sandbox gendoc
Date Thu, 12 Jan 2006 23:48:07 GMT
> what does (sp?) means in this context?
>

Sorry, it means I wasn't sure I got the spelling of your name right.

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

yes I read that the <m:description> etc are too long <m:desc> etc
suggested instead.


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

when I say script here I'm talking about a ruby script (partially as I
saw this as being a converter for the manual for a limited amount of
time, not immediate throwaway, but not a piece of code that's going to
fester in svn for years after, partially because I know enough ruby to
get it done in it (and I don't know enough perl/python)

also for light text processing I think Java is probably too
heavyweight (sledgehammer to crack a nut) and ruby has nice regexp
capabilities.

RE: processing xml, I thought the current opinion was to use xsl +
ants own style task for the HTML (forgive me if I'm wrong), for pdf
version of the manual there's fop (new version recently released) and
latex2pdf (was mentioned too).  There's always forrest too, and I
suppose we could use XDoclet.

> 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'm aiming for a proof of concept script (for echo task) sometime in
the next week (if work doesn't get in the way too much).  After that
I'll see how easy a refactoring job will be for making it generic.

Right now I'm working with the source HTML as is (yes adding divs etc
would help immensely) - to see how difficult it is.  I've got a fair
amount done, but the tokenizer I'm using is being a little greedy and
I've got the examples table as part of the parameters (oops).

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

Yes the 'literate programming' style of documentation (at least I
think this is correct usage of the term) is a different matter
altogether.  Having something embedded in the source files would
require an example or two in some of the tasks, could this go into the
trunk or into sandbox (ie copy a taskdef into sandbox and use it to
experiment with the embedded docs).

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


Mime
View raw message