I do not want to be too negative but...
Dominique Devienne wrote:
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.
I think that the PR is the correct place.
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?
The xml looks very verbose. I would drop description and synopsis. I would make "type" and "required" be attributes and not elements.
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.
Adding in cross-refernces etc, is nice but the cost may be too high.
The xdoc format looks a lot easier to understand, although the cdata stuff does stand out like a sore thumb.
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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
