ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Herr Christian Wolfgang Hujer <Christian.Hu...@itcqis.com>
Subject Ant 2 Suggesion for build.xml
Date Thu, 30 Jan 2003 21:12:41 GMT
-----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: Christian.Hujer@itcqis.com
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: ant-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: ant-dev-help@jakarta.apache.org


Mime
View raw message