ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Peter Reilly <peterrei...@apache.org>
Subject Re: Prototype work on XML+XSL based Ant doc
Date Tue, 22 Mar 2005 18:29:33 GMT
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: dev-unsubscribe@ant.apache.org
>For additional commands, e-mail: dev-help@ant.apache.org
>
>
>
>  
>


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


Mime
View raw message