> From: James Fuller [mailto:[EMAIL PROTECTED] > > 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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
