Dominique Devienne wrote:
>>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
>
>
have used <m:desc/> and <m:def/>
>>- 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.
>
>
ok....I would
a) use one namespace for Ant manual stuff, and retain the ant namespace
as well
b) allow people to use docbook/xhtml namespace if they want to use it
within <m:desc/>
c) use simple XHTML with html:div by default
>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.
>
>
yes, but why come up with another markup language for something that is
intrinsically not connected to Ant....I propose
that we add an <m:rev/> to mark out a revision section, which can
contain stuff like
<m:rev ver="2">
<dc:creator email="[EMAIL PROTECTED]"
url="http://www.ruminate.co.uk/";> Jim Fuller </dc:creator>
<dc:date>2001-06-10</dc:date>
<dc:description xmlns="http://www.w3.org/1999/xhtml";>
<ul>
<li>Added <code>file:////</code> schema.</li>
<li>Added implementation to assist in absolute blah
blahl....</li>
</ul>
</dc:description>
</m:rev>
dublin core is good at metadata about changes to the document, not the
document itself.....its easy to use and there are few elements...
>
>
>>Current namespace elements should mimic docbook simple subset of
>>elements, for future integration/mapping.
>>
>>
>
>Again, I'm not following...
>
>
>
ignore, I have opted for XHTML as your basic.
>,-
>|> 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.
>
>
its not verbosity, I have proposed using <m:elm/> or <m:att/>...or
perhaps put it into Ants namespace
<a:elem/> or <a:attr/>.
I am struggling using @since......I would have something like a:ver
relate to a specific version
also no need to put copyright directly into this file.
>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.
>
>
>
i can help here.
>>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.
>
>
ok have changed...also I need a description of what an m:section is ?
>>- 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.
>
>
but having the data itself embedded inside anywhere doesnt mean it *has*
to go into the description
<html:div>
<!-- note that un namespaced elements should inherit html:
namespace -->
<p>This can be used to build subprojects. <strong>This task must
not be used outside of a
<code>target</code> if it invokes the same build file it
is part of.</strong>
</p>
<p>When the <m:att>antfile</m:att> attribute is omitted, the
file "build.xml"; in the
supplied directory (<m:att>dir</m:att> attribute) is used.</p>
<p>If no <m:att>target</m:att>> attribute is supplied, the
default target of the new
project is used.</p>
<p>By default, all of the properties of the current project will
be available in the new
project. Alternatively, you can set the
<m:att>inheritAll</m:att> attribute to <m:false/>
and only "user" properties (i.e., those passed on the
command-line) will be passed to the
new project. In either case, the set of properties passed to
the new project will override
the properties that are set in the new project (See also the
<a href="property.html"
>property task</a>).</p>
<p>You can also set properties in the new project from the old
project by using nested
property tags. These properties are always passed to the new
project and any project
created in that project regardless of the setting of
<m:att>inheritAll</m:att>. This
allows you to parameterize your subprojects. Properties
defined on the command line cannot
be overridden by nested <m:elem>property</m:elem> elements.</p>
<m:example>
<m:snippet>
<a:mkdir dir="${dist}" />
</m:snippet>
<m:description>
Creates a directory <code>${dist}</code>.
</m:description>
</m:example>
<p>References to data types can also be passed to the new
project, but by default they are
not. If you set the inheritrefs attribute to true, all
references will be copied, but they
will not override references defined in the new project.</p>
<p>Nested <m:elem>reference</m:elem> elements can also be used
to copy references from the
calling project to the new project, optionally under a
different id. References taken from
nested elements will override existing references that have
been defined outside of
targets in the new project - but not those defined inside of
targets.</p>
</html:div>
for example the above might make sense for the task writer, but we have
control over where this example be it in a container
or wherever. In any event, I think both should be possible.
>>- 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.
>
>
ahhhh. good point re author information, right then I have shown dublin
core example...but I think then all we need is version and date on a
revision type element e.g. <m:rev/> that can update any element (for
example an example, description text, or attribute)
>>- 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.
>
>
by adding a type value to definition we make all this kinda
possible....though admittedly one for the future...and in any event I
can see this type of information coming in from java comments via xdoclet.
>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.
>
>
agreed..not suggesting changing existing antlib and XML namespace by ant.
>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 ;-)
>
>
verbosity is a problem, though in the future the xml we may recieve will
not be demarcated by file...but by namespace...and in any event having a
complex layered document with lots of information is more
compelling....though lets apply this to Ant;
a) ant would benefit by having a simple markup for task description, to
assist in manual generation...this task definition could even find its
way as javadoc tags eventually for those that want to work in code comments
b) the goal of going from the code to an xml format to a manual I think
is good
c) I think having at the end of each task a revision list is important
have included my version of markup below; hope it comes through ok...
cheers, Jim Fuller
ant.xml
-------------------------------------------------------------------
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="../manual.xsl"?>
<m:manual xmlns:m="uri:org.apache.ant:manual"
xmlns:html="http://www.w3.org/1999/xhtml";
xmlns:dc="http://purl.org/dc/elements/1.1/";
xmlns:a="antlib:org.apache.tools.ant">
<m:task name="ant" m:ver="1" a:ver="1.6.2">
<m:desc>
<m:def>Runs Ant on a supplied buildfile.</m:def>
<html:div>
<!-- note that un namespaced elements should inherit html:
namespace -->
<p>This can be used to build subprojects. <strong>This task must
not be used outside of a
<code>target</code> if it invokes the same build file it
is part of.</strong>
</p>
<p>When the <m:att>antfile</m:att> attribute is omitted, the
file "build.xml"; in the
supplied directory (<m:att>dir</m:att> attribute) is used.</p>
<p>If no <m:att>target</m:att>> attribute is supplied, the
default target of the new
project is used.</p>
<p>By default, all of the properties of the current project will
be available in the new
project. Alternatively, you can set the
<m:att>inheritAll</m:att> attribute to <m:false/>
and only "user" properties (i.e., those passed on the
command-line) will be passed to the
new project. In either case, the set of properties passed to
the new project will override
the properties that are set in the new project (See also the
<a href="property.html"
>property task</a>).</p>
<p>You can also set properties in the new project from the old
project by using nested
property tags. These properties are always passed to the new
project and any project
created in that project regardless of the setting of
<m:att>inheritAll</m:att>. This
allows you to parameterize your subprojects. Properties
defined on the command line cannot
be overridden by nested <m:elem>property</m:elem> elements.</p>
<p>References to data types can also be passed to the new
project, but by default they are
not. If you set the inheritrefs attribute to true, all
references will be copied, but they
will not override references defined in the new project.</p>
<p>Nested <m:elem>reference</m:elem> elements can also be used
to copy references from the
calling project to the new project, optionally under a
different id. References taken from
nested elements will override existing references that have
been defined outside of
targets in the new project - but not those defined inside of
targets.</p>
</html:div>
</m:desc>
<!-- The task's attributes -->
<m:attributes>
<m:attribute name="antfile">
<m:type>java.io.File</m:type>
<m:desc>
<m:def>the buildfile to use.</m:def> Defaults to "build.xml".
This file is expected to be
a filename relative to the dir attribute given. </m:desc>
<!-- example of a revision using dc -->
<m:rev ver="2" a:ver="1.5">
<dc:creator email="[EMAIL PROTECTED]"
url="http://www.ruminate.co.uk/";> Jim Fuller </dc:creator>
<dc:date>2001-06-10</dc:date>
<dc:description xmlns="http://www.w3.org/1999/xhtml";>
<ul>
<li>Added <code>file:////</code> schema.</li>
<li>Added implementation to assist in absolute blah
blahl....</li>
</ul>
</dc:description>
</m:rev>
</m:attribute>
<m:attribute name="dir">
<m:type>java.io.File</m:type>
<m:desc>
<m:def> the directory to use as a basedir for the new Ant
project. </m:def> Defaults to
the current project's basedir, unless inheritall has been set
to false, in which case it
doesn't have a default value. This will override the basedir
setting of the called
project. </m:desc>
</m:attribute>
<m:attribute name="target">
<m:type>java.lang.String</m:type>
<m:desc>
<m:def> the target of the new Ant project that should be
executed. </m:def> Defaults to
the new project's default target. </m:desc>
</m:attribute>
<m:attribute name="output">
<m:type>java.io.File</m:type>
<m:desc>
<m:def> Filename to write the ant output to. </m:def> This is
relative to the value of the
dir attribute if it has been set or to the base directory of
the current project
otherwise. </m:desc>
</m:attribute>
<m:attribute name="inheritAll">
<m:type>boolean</m:type>
<m:desc>
<m:def>Whether to inherit properties.</m:def> If <m:true/>,
pass all properties to the new
Ant project. Defaults to <m:false/>. </m:desc>
</m:attribute>
<m:attribute name="inheritRefs">
<m:type>boolean</m:type>
<m:desc>
<m:def>Whether to inherit references.</m:def> If <m:true/>,
pass all references to the new
Ant project. Defaults to <m:false/>. </m:desc>
</m:attribute>
</m:attributes>
<!-- The tasks nested-elements -->
<m:elements>
<m:element name="property">
<m:desc>
<m:def> Pass an explicit property value to the new Ant
project. </m:def>
<p>See the description of the <a:property/> task.</p>
<p>These properties become equivalent to properties you define
on the command line. These
are special properties and they will always get passed down,
even through additional
<a:ant/>, <a:antcall/>, <a:subant/> tasks with inheritAll
set to <m:false/> (see above).</p>
<p>Note that the <code>refid</code> attribute points to a
reference in the calling
project, not in the new one.</p>
</m:desc>
<!-- simpler revision example -->
<m:rev ver="2" a:ver="1.7">
<m:desc>
<m:def> This is a better description blah blah
blah......Pass an explicit property value
to the new Ant project. </m:def>
<p>See the description of the <a:property/> task.</p>
<p>These properties become equivalent to properties you
define on the command line.
These are special properties and they will always get
passed down, even through
additional <a:ant/>, <a:antcall/>, <a:subant/> tasks with
inheritAll set to <m:false/>
(see above).</p>
<p>Note that the <code>refid</code> attribute points to a
reference in the calling
project, not in the new one.</p>
</m:desc>
</m:rev>
</m:element>
<m:element name="reference">
<m:desc>
<m:def> Pass an explicit reference value to the new Ant
project. </m:def> Used to choose
references that shall be copied into the new project,
optionally changing their id. </m:desc>
<!-- The <reference> nested-element's attributes -->
<m:attributes>
<m:attribute name="refid">
<m:type>java.lang.String</m:type>
<m:required/>
<m:desc>
<m:def> The id of the reference in the <em>calling</em>
project. </m:def>
</m:desc>
</m:attribute>
<m:attribute name="torefid">
<m:type>java.lang.String</m:type>
<m:desc>
<m:def> The id of the reference in the <em>new</em>
project. </m:def> Defaults to the
value of <m:attr>refid</m:attr>. </m:desc>
</m:attribute>
</m:attributes>
</m:element>
<m:element name="propertyset" a:ver="1.6">
<m:desc> You can specify a set of properties to be copied into
the new project with
<a:propertyset/>s. </m:desc>
</m:element>
<m:element name="target" a:ver="1.6.3">
<m:desc>
<m:def>Call an explicit target.</m:def> You can specify
multiple targets using nested
<m:elem>target</m:elem> elements instead of using the target
attribute. These will be
executed as if Ant had been invoked with a single target whose
dependencies are the
targets so specified, in the order specified. </m:desc>
<!-- The <target> nested-element's attributes -->
<m:attributes>
<m:attribute name="name">
<m:type>java.lang.String</m:type>
<m:required/>
<m:desc>
<m:def>The name of the called target.</m:def>
</m:desc>
</m:attribute>
</m:attributes>
</m:element>
</m:elements>
<m:section name="Basedir of the new project">
<p>The <m:attr>basedir</m:attr>> value of the new project is
affected by the two attributes
<m:attr>dir</m:attr> and <m:attr>inheritAll</m:attr>, see the
following table for details:</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<th valign="top">dir attribute</th>
<th valign="top">inheritAll attribute</th>
<th valign="top">new project's basedir</th>
</tr>
<tr>
<td valign="top">value provided</td>
<td valign="top">true</td>
<td valign="top">value of dir attribute</td>
</tr>
<tr>
<td valign="top">value provided</td>
<td valign="top">false</td>
<td valign="top">value of dir attribute</td>
</tr>
<tr>
<td valign="top">omitted</td>
<td valign="top">true</td>
<td valign="top">basedir of calling project (the one whose
build file contains the
<code><ant></code> task).</td>
</tr>
<tr>
<td valign="top">omitted</td>
<td valign="top">false</td>
<td valign="top">basedir attribute of the
<code><project></code> element of
the new project</td>
</tr>
</table>
</m:section>
<m:examples>
<m:example>
<m:snippet>
<a:ant dir="subproject"/>
</m:snippet>
</m:example>
<m:example>
<m:snippet>
<a:ant antfile="subproject/subbuild.xml" dir="subproject"
target="compile"/>
</m:snippet>
</m:example>
<m:example>
<m:snippet>
<a:ant antfile="subproject/property_based_subbuild.xml">
<a:property name="param1" value="version 1.x"/>
<a:property file="config/subproject/default.properties"/>
</a:ant>
</m:snippet>
</m:example>
<m:example>
<m:snippet>
<a:ant inheritAll="false" antfile="subproject/subbuild.xml">
<a:property name="output.type" value="html"/>
</a:ant>
</m:snippet>
</m:example>
<m:example>
<m:snippet>
<a:ant antfile="subproject/subbuild.xml" dir="subproject"
target="compile"/>
<a:ant dir="subproject"/>
<a:ant antfile="subproject/property_based_subbuild.xml">
<a:property name="param1" value="version 1.x"/>
<a:property file="config/subproject/default.properties"/>
</a:ant>
<a:ant inheritAll="false" antfile="subproject/subbuild.xml">
<a:property name="output.type" value="html"/>
</a:ant>
</m:snippet>
<m:desc> The build file of the calling project defines some
<a:path/> elements like this:
</m:desc>
</m:example>
</m:examples>
</m:task>
</m:manual>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
