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 Fri, 25 Mar 2005 14:59:45 GMT
> From: James Fuller [mailto:jim.fuller@ruminate.co.uk]
> 
> a few ruminations;
> 
> - replace <m:synopsis> with <m:brief/> or <m:abstract/>, easier on
the
eye

Sounds good. I also thought of <m:def> for definition. Even shorter
while still explicit enough (?). And after Peter's comments on
verbosity, I've also thought of skipping <m:description> altogether, but
haven't experimented with it, and I'm not sure I can pull it off.

> - description / section text should be free to use
> 
> XHTML: xmlns:x=""
> Docbook: xmlns:db=""
> Dublin Core xmlns:dc=""

Here you're loosing me. I'm not a hard-core XML guy... Un-namespaced
elements are already passed thru as-is to use embedded HTML within the
text, and I don't see what Docbook or Dublin Core have to do with the
Ant docs.

The ad-hoc XML vocab I prototyped is to not use Docbook. And Dublin Core
is for very verbose embedded meta-data for machine processing, no?
Exactly what we don't want for Ant, verbosity.

My goal is not to hit all the XML buzz acronyms, but to have something
easy to author as text for humans.

> Current namespace elements should mimic docbook simple subset of
> elements, for future integration/mapping.

Again, I'm not following...

,-
|> then within <m:attributes/> define with <m:attribute>, note I think
|> this element should have an attribute of data type.
`---> I don't understand what you mean.

> - I would suggest adding the <attr/> and <elem/> element to current
> namespace, e.g. <snip/>
> and remove the whole attr/elem namespaces thing...XML namespaces are
> good at namespace collision not for implementing some sort of
> logic....though I understand the concept, I dont see much value...

If there's resistance about the attr/elem magic namespace, I'll switch
back to the more verbose <m:attr> and <m:elem>, depending on what the
majority decides.

I don't get what you mean by 'add to the current namespace' though, if
that doesn't mean that the attr and elem are part of the Ant manual NS.

> what would be interesting is to obviously bring in the java code
comments
> that relate to attributes/elements...though perhaps its little steps
> to get there. Then perhaps a 2 stage XSLT can match such things....

This is already planned. Or maybe I should say is that I planned to
extract the Javadoc and type information with custom code, spit out XML
for it in a similar XML vocab as the doc itself, and merge the two. I
find merging XML files with XSL rather difficult, but hopefully with
outside help it should be fine.

as
> long as retain correct elem/attr name as key.
> 
> - simplify m:nested-elements to purely <m:elements/>

Sounds good. I hesitated myself. Although again to assuage Peter I was
thinking of dropping the <m:attributes> and <m:elements> elements
altogether to make things less verbose. Again, only if I can pull it
off.

> - no need to isolate examples, embed them in a m:description or
> m:section, reduce to either m:snippet

Here I disagree! It is currently an readability issue that you can't
really tell in the HTML doc which snippet goes with which description. I
*want* to have examples better separated. This also helps generate a TOC
for the page.

As I said before, it's not because I replicated the existing look of the
HTML pages that we don't have to enhance the manual now that we have
semantic. And knowing how many examples we have, with possible titles,
is important semantic.

> - I would suggest that *all* version and author information should be
> part of dublin core, I would also suggest creating an example that
> shows a task through time...with added comments / changes /
> amends...even if you are extracting version based on SCM, u still want
> to know when a particular comment/amend occured with what version.

I don't think so, because (1) it sounds very verbose, and would make
reading the XML text quite confusing I think, and (2) Apache has moved
to more 'anonymous' ways where the Contributors' file is the only place,
beside the SCM, where we keep author information.

Version information is already accessible at the task/attribute/element
level, which is enough IMHO.

> - Schemas are so easy to make these days that not having one would be
> a shame, with this type of information <antstructure/> should be able
> to extract a simple schema that is usable as well.

I'm not too sure how <antstructure> relates to the Ant manual XML vocab?
We're talking whether an DTD/Schema is desired for this vocab, not for
writing Ant build files.

As I said above, I'm willing to drop the <attr:dir/> syntax, but not the
<ac:for/> one, as this is the most natural and readable way to have
AntLib cross-references.

If one can accommodate the fact that antlib:* type URI can appear
anywhere in the text in a schema, great, if not, well too bad IMHO.

Ant as already taken liberties with the XML rules in build files
themselves, where a custom task from an AntLib finds its nested elements
even when not in its own NS, as initially coded. Please complained it
was too verbose ;-)

> in general, I for one think this is the right next step.

Thanks. A lot of my reticence to what you propose/suggest above Jim is
probably due to my ignorance of more advanced XML technologies. I think
your proposals would be a lot easier to understand if you actually took
ant.xml and modified it to show what you mean. Inside XHTML, Docbook,
Dublin Core, etc... markup in there, change the structure as you propose
in a concrete fashion for all to see, and we'll have a more productive
discussion I'm sure.

Thank you for the feedback. --DD

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


Mime
View raw message