ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Dominique Devienne" <DDevie...@lgc.com>
Subject RE: Prototype work on XML+XSL based Ant doc
Date Tue, 22 Mar 2005 21:03:19 GMT
> From: Peter Reilly [mailto:peterreilly@apache.org]
> I do not want to be too negative but...

Well, I did ask for input... It's sometimes painful to get negative
feedback, but it's usually constructive.

> >2) Second, is the XML syntax I used too verbose? 
> The xml looks very verbose.

It is. I tried to add as much semantic as I could.

> I would drop description and synopsis. I would make "type" and
"required"
> be attributes and not elements.

So you're not interested in having the Task Overview be auto-generated
from all the synopsis elements? We'd still hand maintain that other
page?

> The use of namespaces is clever but a bit offputting. I see the big
> picture - allowing antlib documention to be cross-linked, but I wonder
> if this is really necessary.

Which one? attr: and elem:? Or the automatic recognition of antlib:*
URIs?

> Adding in cross-refernces etc, is nice but the cost may be too high.

I would actually have thought that reading <ac:for/> was the best way,
both because it's concise and has semantic.

We're talking of facilitating the creation of many AntLibs with the SVN
proposal, and we'd not allow automatic cross-links between AntLibs?

> The xdoc format looks a lot easier to understand, although
> the cdata stuff does stand out like a sore thumb.

I think I need to go back to look at it again.

But I'd like to know more fundamentally what we are trying to do with
the doc. If the goal is to keep it textual, i.e. add the minimum amount
of markup (and thus semantic), to replicate what we have in HTML, then
my first attempt was overkill.

I would content that if we go that route, just adding a few <div>'s and
CSS class'es along with removing all explicit HTML formatting from the
existing doc would get that. It's only the matter of designing a good
.css and 'tagging' the HTML with CSS class's and id's.

I hope I don't sounds too disgruntled ;-)

Something that would be interesting would be for interested people to
modify the existing verbose ant.xml and come up with the markup they'd
think is acceptable. Then I and others can try to XSL that into
something.

Please keep the feedback coming. --DD

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


Mime
View raw message