ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Dominique Devienne" <DDevie...@lgc.com>
Subject Prototype work on XML+XSL based Ant doc
Date Tue, 22 Mar 2005 15:33:28 GMT
I've entered this enhancement.
http://issues.apache.org/bugzilla/show_bug.cgi?id=34116 

I have several questions I was hoping could be discussed.

1) First, is there a place for such a prototype somewhere? proposals/ in
CVS? Wait for SVN/ant/sandbox? So far I've just published a zip attached
to the PR, but it's not ideal for everyone to share / study / modify.

2) Second, is the XML syntax I used too verbose? We can come up with
anything we want, but some syntaxes are easier to process using XSL than
others, and they do tend to be on the verbose side. Is what I used
already good enough? Where to improve?

For example, I've used <description><synopsis/></description> to be able
to use just the synopsis in a task overview page. Some thing for the
attributes/elements, to provide a more global overview of tasks/types.
It's useful, but it makes for some verbose doc? What are alternatives?

3) Then, is DTD/Schema support important? I've used tricks using
namespaces for short syntax to make the code more human readable and
writable. For example, two special namespaces for local attribute and
element cross-refs.

For example, <attr:dir/> means the 'dir' attribute for the current
element. Similarly <elem:classpath/> means a <classpath> nested-element
of the current element. Also, any tag with a namespace that starts with
antlib: is considered specially, to be rendered as a task name, and
later to provide a link to the task itself (I plan to rely on the
namespace to allow cross-antlib references). For example, <ac:for/> is
automatically recognized because the URI bounds to ac: starts with
antlib:.

All these tricks make it almost impossible to use DTDs or Schema (I
think). Do we want to emphasize use of reading/writing over a fixed
schema? Alternates are more verbose:
<m:attr>dir</m:attr>, <m:elem>classpath</m:elem>,
<m:xref><ac:for/></m:xref>.


I'm basically trying to avoid this work going too much further if
there's no buy in and support right at the start. So far we've mostly
discussed options, but with this initial 'implementation', I'd rather
get a feel whether it's a dead end or not.

Thanks, --DD

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


Mime
View raw message