-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Hello dear Ant developers,
I have a suggestion for build.xml.
I suggest adding more features for documenting build files.
Currently files are documented like this:
<project
default="full"
>
<description>
This is a simple build file for project X.
</description>
<target
name="full"
depends="init, update, checkstyle, compile, compileTests,
runTests, report"
description="build the whole thingy"
/>
<!-- ... -->
</project>
And if Ant's features for documentation are not enough, comments are used.
I suggest following the example of XML Schema and introducing an annotation
element with an appinfo and a documentation child element -
for longer descriptions next to the description element, to write build files
like this:
<project
default="full"
xmlns:html="http://www.w3.org/1999/xhtml";
xmlns="toBeSpecified"
>
<annotation>
<documentation
xml:lang="en"
>
A simple build file for project X.
<html:div>
<html:h4>Simple build file for Project X.</html:h4>
<html:p>
This build file is a simple build file for project X,
doing all neccessary work to build project X.
This includes not just compilation, but also tests, style
checking and some design metrics.
</html:p>
</html:div>
</documentation>
</annotation>
<target
name="full"
depends="init, update, compile, report"
>
<annotation>
<documentation
xml:lang="en"
>
Build the whole thingy.
<html:div>
<html:p>
Builds the whole project.
Initializes and updates the sandbox, compiles the
sources, generates the reports and executes all required
targets.
</html:p>
</html:div>
</documentation>
</annotation>
</target>
<!-- ... -->
</project>
Of course this somehow blows up build files, so no one should be forced to do
it this way. But I think it is proved to be useful to maintain source and
documentation in the same file - look at javadoc / doxygen and the
annotations in XML Schema. Someone who doesn't like bloated build.xml files
just omits the annotations.
The advantage of the new approach is that those who'd want to can write an
exhaustive documentation of their build file without maintaining two sources
(which always causes problems). That way a documentation could be generated
using XSLT.
I don't think the current approach already meets these requirements because:
- - The current approach does not support nested elements because targets are
documented as attributes. The new approach supports nested elements because
it doesn't use attributes to contain the documentation.
- - The current approach does not support documentation in more than one
language. The new approach does.
- - The current approach does not support extensive documentation (because it
doesn't support nested elements).
The current approach was, if I remember correctly, only to support some
command line advice about the usage of a certain build.xml file.
With the new approach, a build.xml could contain the required doc source
snippets in various namespaces aware languages, like DocBook or XHTML. If
taking care of < and &, one could even insert documentation in TeX / LaTeX.
I'd be glad to hear any opinions on this.
I'd also like to hear opinions on wether such a new approach should replace or
simply accompany the current "description" approach.
The new approach would not need to be directly supported by ant. The
documentation elements could live in their own namespace, being completely
ignored by ant itself.
I could also imagine three or four namespaces regarding this:
- - An Ant namespace, extracted by Ant
- - A description namespace, extracted by Ant when command line help is
requested
- - An annotation / documentation namespace, ignored by Ant, extracted by XSLT
scripts
- - A task namespace
Disclaimer:
This post just reflects the thoughts of some individual using Ant. I am not
related to Apache, Jakarta or Ant teams. I will and cannot make any
decisions. This is just a set of premature ideas for open discussion.
Bye
- --
ITCQIS GmbH
Christian Wolfgang Hujer
GeschÃftsfÃhrender Gesellschafter
Telefon: +49 (0)89 27 37 04 37
Telefax: +49 (0)89 27 37 04 39
E-Mail: [EMAIL PROTECTED]
WWW: http://www.itcqis.com/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.7 (GNU/Linux)
iD8DBQE+OZVJzu6h7O/MKZkRAn6aAJ4xtbK1qK48XSCtaTtNa4WCxR+3tgCeNjXu
TVRjCTiJKK0Br+Xw6tvg4B4=
=DlxH
-----END PGP SIGNATURE-----
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
