craigmcc 01/07/27 18:35:39
Modified: . build.xml
webapps build.xml
Added: webapps/tomcat-docs build.xml
webapps/tomcat-docs/WEB-INF web.xml
webapps/tomcat-docs/images tomcat.gif
Log:
Initial setup of a new webapp for Tomcat 4.0 documentation that is
generated (from XML files) rather than being edited directly in HTML. It
is based on the "site.xsl" stylesheet that I checked in to the
jakarta-site2 project earlier, so you will need a "site.xsl" property in
your build.properties file that points at it.
The basic thinking is that the "tomcat-docs" webapp will contain all of
the user-oriented and developer-oriented documentation relevant to Tomcat
4.0, all generated in a nice consistent style according to the stylesheet.
In addition, we can simply take the tomcat-docs.war file, and unpack it
into a convenient directory on the web site, and have the online version
of the docs instantly available (and always consistent) as well.
Over the weekend, I will be porting over some of the existing
documentation (in particular the App Developer's Guide, the server.xml
configuration stuff, and some of the developer docs) to ensure that this
approach scales well, and to offer an example of how to add new categories
of documentation to the overall docs webapp.
NOTE: When setting this up, I ran into a nasty bug in the <style> tag in
Ant 1.3 -- it treats the "style" attribute (identifying the filename of
the stylesheet to use) as relative, even if you try to specify an absolute
pathname. This was nasty, because I wanted to be able to simply point at
my checked-out copy of the jakarta-site2 repository.
To work around this, the build.xml file for the "tomcat-docs" webapp does
the following (for the moment):
- Copies the XML sources to a temporary directory
- Copyies the site.xsl file (pointed at by your property) into the
temporary directory
- Runs the XSLT transformations from the temporary directory to the
usual build directory
- Deletes the temporary directory
A side effect of this workaround is that the generation of the entire
tomcat-docs webapp happens every time, even if nothing has changed.
Therefore, creation of this webapp is *not* included in the defaults. If
you want to generate it, go to the top-level jakarta-tomcat-4.0 source
directory and type
ant tomcat-docs
or
ant dist
Revision Changes Path
1.32 +13 -1 jakarta-tomcat-4.0/build.xml
Index: build.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/build.xml,v
retrieving revision 1.31
retrieving revision 1.32
diff -u -r1.31 -r1.32
--- build.xml 2001/07/27 22:26:03 1.31
+++ build.xml 2001/07/28 01:35:38 1.32
@@ -61,6 +61,18 @@
</target>
+ <!-- ======================= SPECIAL: Tomcat Documentation ============= -->
+ <target name="tomcat-docs" depends="deploy-main">
+ <!-- The "tomcat-docs" webapp is not built by default, because the
+ workaround to an Ant bug causes the XSLT transformations to be
+ run every time. Run "ant tomcat-docs" or "ant dist" to execute
+ this target -->
+ <ant dir="./webapps" target="tomcat-docs"/>
+ <copy todir="${tomcat.build}/webapps/tomcat-docs">
+ <fileset dir="webapps/build/tomcat-docs"/>
+ </copy>
+ </target>
+
<!-- ======================= COMBO: Test All Components ================= -->
<target name="test">
<ant dir="./catalina" target="test"/>
@@ -154,7 +166,7 @@
<!-- ====================== DIST: Create Archives ======================= -->
- <target name="dist" depends="deploy-main,dist-static,dist-javadoc,dist-source">
+ <target name="dist"
depends="deploy-main,dist-static,dist-javadoc,dist-source,tomcat-docs">
<!-- Comment out until startup timing issues are resolved
<jar jarfile="${tomcat.dist}/webapps/ROOT.war"
basedir="${tomcat.build}/webapps/ROOT" includes="**"/>
1.15 +11 -1 jakarta-tomcat-4.0/webapps/build.xml
Index: build.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-4.0/webapps/build.xml,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- build.xml 2001/05/22 01:59:05 1.14
+++ build.xml 2001/07/28 01:35:39 1.15
@@ -42,6 +42,10 @@
<ant dir="${basedir}/manager" target="dist"/>
</target>
+ <target name="tomcat-docs">
+ <ant dir="${basedir}/tomcat-docs" target="dist"/>
+ </target>
+
<target name="webdav">
<ant dir="${basedir}/webdav" target="dist"/>
</target>
@@ -50,7 +54,13 @@
<!-- ================= BUILD: Compile Server Components ================= -->
<!-- Update the depends list for each subproject -->
<target name="build" depends="build-prepare,ROOT,examples,manager,webdav"/>
-
+<!-- NOTE: tomcat-docs is excluded because the workaround for the Ant
+ bug causes a rebuild every single time. Execute "ant tomcat-docs"
+ directly if you want to create it.
+-->
+<!--
+ <target name="build"
depends="build-prepare,ROOT,examples,manager,tomcat-docs,webdav"/>
+-->
<!-- ==================== BUILD: Execute Unit Tests ===================== -->
<target name="test" if="junit.present"
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/build.xml
Index: build.xml
===================================================================
<project name="tomcat-docs" default="build-main" basedir=".">
<!-- ===================== Initialize Property Values =================== -->
<property file="build.properties"/>
<property file="../build.properties"/>
<property file="../../build.properties"/>
<property file="${user.home}/build.properties"/>
<property name="build.compiler" value="classic"/>
<property name="webapps.build" value="../build"/>
<property name="webapps.dist" value="../dist"/>
<property name="webapp.name" value="tomcat-docs"/>
<!-- ================== Derived Property Values ========================= -->
<property name="site.xsl"
value="../../../jakarta-site2/xdocs/stylesheets/site.xsl"/>
<!-- =================== BUILD: Initialization ========================== -->
<target name="build-init">
<!-- Required only for the Ant Bugzilla #603 workaround -->
<tstamp/>
<property name="webapp.work"
value="${java.io.tmpdir}/${webapp.name}${DSTAMP}${TSTAMP}"/>
</target>
<!-- =================== BUILD: Create Directories ====================== -->
<target name="build-prepare" depends="build-init">
<mkdir dir="${webapps.build}"/>
<mkdir dir="${webapps.build}/${webapp.name}"/>
</target>
<!-- ================ BUILD: Copy Static Files ========================== -->
<target name="build-static" depends="build-prepare">
<!-- Top Level Static Files -->
<copy todir="${webapps.build}/${webapp.name}">
<fileset dir="../..">
<include name="BUILDING.txt"/>
<include name="README.txt"/>
<include name="RUNNING.txt"/>
</fileset>
</copy>
<!-- Images Subdirectory -->
<mkdir dir="${webapps.build}/${webapp.name}/images"/>
<copy todir="${webapps.build}/${webapp.name}/images">
<fileset dir="images"/>
</copy>
<!-- WEB-INF Subdirectory -->
<mkdir dir="${webapps.build}/${webapp.name}/WEB-INF"/>
<copy todir="${webapps.build}/${webapp.name}/WEB-INF">
<fileset dir="WEB-INF"/>
</copy>
</target>
<!-- ================= BUILD: XML-HTML Generation ======================= -->
<target name="build-main" depends="build-static">
<!-- Workaround for Ant 1.3 bug (Bugzilla #603) where the "style"
attribute is resolved relatively even if it is absolute! Copy
the source tree to a temporary directory, and interpolate the
XSLT stylesheet appropriately -->
<mkdir dir="${webapp.work}"/>
<copy todir="${webapp.work}">
<fileset dir="."/>
<fileset dir="${site2.home}/xdocs/stylesheets" includes="site.xsl"/>
</copy>
<!-- Top Level Directory -->
<style basedir="${webapp.work}"
destdir="${webapps.build}/${webapp.name}"
extension=".html"
style="site.xsl"
excludes="build.xml project.xml"
includes="*.xml">
<param name="relative-path" expression="."/>
</style>
<!-- Remove the temporary directory for the Ant bug workaround -->
<delete dir="${webapp.work}" />
</target>
<!-- ==================== BUILD: Rebuild Everything ===================== -->
<target name="all" depends="build-clean,build-main"/>
<!-- ======================= BUILD: Clean Directory ===================== -->
<target name="build-clean">
<delete dir="${webapps.build}/${webapp.name}"/>
</target>
<!-- ======================= DIST: Create Directories =================== -->
<target name="dist-prepare">
<mkdir dir="${webapps.dist}"/>
</target>
<!-- ======================= DIST: Create Distribution Files ============ -->
<target name="dist" depends="build-main,dist-prepare">
<jar jarfile="${webapps.dist}/${webapp.name}.war"
basedir="${webapps.build}/${webapp.name}" includes="**"/>
</target>
<!-- ======================= DIST: Clean Directory ====================== -->
<target name="dist-clean">
<delete dir="${webapps.dist}/${webapp.name}"/>
</target>
<!-- ====================== Convenient Synonyms ========================= -->
<target name="clean" depends="build-clean,dist-clean"/>
</project>
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/WEB-INF/web.xml
Index: web.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/j2ee/dtds/web-app_2_3.dtd";>
<web-app>
</web-app>
1.1 jakarta-tomcat-4.0/webapps/tomcat-docs/images/tomcat.gif
<<Binary file>>
