org.aspectj/docs/build.xml

<!-- -*- Mode: SGML; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-     -->
<!-- ========================================================================= -->
<!-- Copyright (c) 2002 Palo Alto Research Center, Incorporated (PARC).        -->
<!-- All rights reserved.                                                      -->
<!-- This program and the accompanying materials are made available            -->
<!-- under the terms of the Common Public License v1.0                         -->
<!-- which accompanies this distribution and is available at                   -->
<!-- http://www.eclipse.org/legal/cpl-v10.html                                 -->
<!--                                                                           -->
<!-- Contributors:                                                             -->
<!--     Xerox/PARC     initial implementation                                 -->
<!-- ========================================================================= -->

<!-- 

Using this:
  - default target (dist) creates deployment-like dir in build output dir
  - target download.files deploys locally and creates installers
  - individual targets build pieces (api, etc.)
  - clean only cleans the build directory

Understanding this:

  The documentation output structure is (ignoring alpha order):

  aspectj/
    README-DOC.html
    style.css
    examples/
    doc/
      index.html
      changes.html
      porting.html
      oldversions/
      faq.html
      quickref.html

      devguide.pdf
      progguide.pdf
      quickref.pdf
    
      api/
      progguide/
      devguide/

  The input structure is

  aspectj/
    README-DOC.html
    style.css
    examples/
    doc/
      index.html
      changes.html
      porting.html
      oldversions/
      faq/faq.html

      devGuideDB/  to devguide/ devguide.pdf
      progGuideDB/ to progguide/ progguide.pdf
      ?? to quickref.pdf quickref.html  
   src/org/aspectj/lang/*.java          | to api
   src/org/aspectj/lang/reflect/*.java  |

data flow and operations (in terms of script names):
  - input -           - target -          - output -
  ${docs.src.dir}      dist                ${docs.dist.dir}
  ${docs.src.dir}        api               ${docs.dist.dir}
  ${docs.src.dir}        faq               ${docs.dist.dir}
  ${docs.src.dir}        examples          ${docs.dist.dir}
  ${docs.src.dir}        devguide          ${docs.dist.dir}
  ${docs.src.dir}        progguide         ${docs.dist.dir}
  ${docs.src.dir}        allTheRest        ${docs.dist.dir}
  ${docs.dist.dir}    web.deploy           ${web.doc.dir}
  ${aj.release.dir}/.. download.push      (ajpush)

XXX no update to avoid builds in this script
 -->

<!DOCTYPE project [
<!ENTITY build-properties SYSTEM "file:../build/build-properties.xml">
]>
<project name="build-docs" default="dist" basedir=".">
  <!-- todo: download.files requires build-installer -->
  <property name="project.name" value="build-docs"/>

    <target name="quicklook"      depends="dist"/>
    <target name="product"        depends="local-dist"/>
    <target name="download.files" depends="dist"/>
    <target name="clean" 
         depends="clean-directories,clean-doc-directories"/>

    <!-- ===================================================================== -->
    <!-- Init                                                                  -->
    <!-- ===================================================================== -->

    &build-properties;

    <target name="init" depends="init-properties,init-directories">
       
      <property name="docs.src.dir"       
            location="${aspectj.modules.docs.dir}"/>

      <property name="docs.dist.dir"      location="${aj.dist.dir}/docs"/>
      <property name="docs.temp.dir"      location="${aj.temp.dir}/doc"/>
      <property name="web.doc.dir"        location="${aj.webDeploy.dir}/documentation/dist"/>

      <property name="docs.product.name" 
               value="aspectj-docs-${build.version}"/>

      <property name="docs.product.zip"  
            location="${aj.dist.dir}/${docs.product.name}.zip"/>
      <!-- must specify (not *.gif) to not delete other gifs during build-in-place -->
      <!-- to find refs: gp ax imagedata | sed -n 's|.*\=\"\(..*\)\".*|\1|p' -->
      <property name="devguide.icons.dir" 
            location="${aspectj.modules.dir}/ajde/src/org/aspectj/ajde/resources/actions"/>
      <property name="include.devguide.icons"
                 value="startAjde.gif,build.gif,openConfig.gif,browseroptions.gif,jbuilder-build.gif" />

      <!-- callers of xml-html use these by default -->
      <property name="chunk.xsl.source" 
            location="${aspectj.modules.lib.dir}/docbook/docbook-xsl/html/chunk.xsl"/>
      <property name="nochunk.xsl.source" 
            location="${aspectj.modules.lib.dir}/docbook/docbook-xsl/html/docbook.xsl"/>
      <!-- default xml-html nochunking file (0-length dummy created when chunking) -->
      <property name="xml-target-file" 
            location="${docs.temp.dir}/xml-target-file.dummy"/>
      <!-- default value for xml-html copying (copy all graphics) -->
      <property name="xml-html-copy" value="*.gif,*.png" />
      <property name="binary.pattern" 
               value="**/*.gif,**/*.png,**/*,**/*.doc,**/*.pdf"/>
      <uptodate property="local.dist.uptodate"
              targetfile="${docs.dist.dir}/faq.html"> <!-- use faq as tag file -->
         <srcfiles dir="${docs.src.dir}"/>
      </uptodate>

      <uptodate property="dist.uptodate"
             targetfile="${docs.product.zip}"> <!-- use zip as tag file -->
         <srcfiles dir="${docs.src.dir}"/>
         <srcfiles dir="${docs.dist.dir}"/>
      </uptodate>

    </target>

    <target name="clean-doc-directories" depends="init"
     description="clean build dirs (including local deploy dir)">
        <delete quiet="on">
            <fileset dir="${docs.dist.dir}" />
            <fileset dir="${docs.jar.dir}" />
            <fileset dir="${docs.temp.dir}" />
        </delete>
    </target>

    <target name="dist" depends="init,local-dist"
     description="create doc distribution zip"
          unless="dist.uptodate">
        <delete file="${docs.product.zip}"/>
        <zip zipfile="${docs.product.zip}"
             basedir="${docs.dist.dir}"/>

        <echo message="find doc zip in ${docs.product.zip}"/>                     
    </target>

    <target name="web.deploy.faqonly" depends="init,faq"
     description="deploy docs.dist.dir faq to web.doc.dir">
     <copy todir="${web.doc.dir}" filtering="on">
       <fileset dir="${docs.dist.dir}/doc" includes="faq.html"/>
     </copy>
     <stripnonbodyhtml srcdir="${web.doc.dir}" 
                     includes="faq.html" />
     <echo message="do link check on index and faq before release"/>
    </target>

    <target name="web.deploy.faqindex" depends="init,dist"
     description="deploy built faq and index to web.doc.dir">
     <copy todir="${web.doc.dir}" filtering="on">
       <fileset dir="${docs.dist.dir}/doc"
            includes="faq.html,index.html"/>
     </copy>
     <stripnonbodyhtml srcdir="${web.doc.dir}" 
                     includes="faq.html,index.html" />
     <echo message="do link check on index and faq before release"/>
    </target>

    <target name="web.deploy" depends="web.deploy.README-11" />

    <target name="web.deploy.README-11" depends="init"
     description="deploy README-11.html to the web site">
     <property name="readme11.dir"
           location="${web.doc.dir}/documentation/readme11"/>
     <mkdir dir="${readme11.dir}"/>
     <delete file="${readme11.dir}/index.html"/>
     <mkdir dir="${readme11.dir}"/>
     <copy tofile="${readme11.dir}/index.html"
             file="${aspectj.products.dir}/tools/dist/README-11.html"
       filtering="on"/>
     <stripnonbodyhtml srcdir="${readme11.dir}" 
                     includes="index.html" />
    </target>

    <target name="web.deploy.old" depends="init"
     description="deploy built docs to the web site">
     <mkdir dir="${web.doc.dir}"/>
     <delete dir="${web.doc.dir}"/>
     <mkdir dir="${web.doc.dir}"/>
     <copy todir="${web.doc.dir}">
       <fileset dir="${docs.dist.dir}/doc"/>
     </copy>
     <stripnonbodyhtml srcdir="${web.doc.dir}" 
                     includes="**/*.html" />
    </target>

    <!-- ============================================================ -->
    <!-- build all doc products                                       -->
    <!-- ============================================================ -->
    <target name="local-dist" depends="init"
          unless="local.dist.uptodate" >
       <antcall target="do-local-dist"/>
    </target>
    <target name="do-local-dist" 
         depends="init,init-filters,api,faq,devguide,progguide"
          unless="local.dist.uptodate"
      description="finish products by copying dist files">
        <copy todir="${docs.dist.dir}" filtering="on">
            <fileset dir="${docs.src.dir}/dist" 
                excludes="${binary.pattern}"/>
        </copy>
        <copy todir="${docs.dist.dir}" filtering="off">
            <fileset dir="${docs.src.dir}/dist" 
                includes="${binary.pattern}"/>
        </copy>
    </target>

    <target name="api" depends="init"
       description="javadoc for AspectJ lang and lang.reflect">
        <delete dir="${docs.dist.dir}/doc/api"/>
        <mkdir dir="${docs.dist.dir}/doc/api"/>
        <javadoc sourcepath="${aspectj.modules.dir}/runtime/src"
                    destdir="${docs.dist.dir}/doc/api"
                windowtitle="AspectJ(tm) runtime API"
                       link="http://java.sun.com/j2se/1.4/docs/api/index.html"
               packagenames="org.aspectj.lang,org.aspectj.lang.reflect" />
               <!-- note: link ineffective at avoiding see tag warning -->
    </target>

    <target name="faq" depends="init">
        <antcall target="xml-html">
            <param name="xml-source-dir" 
                  value="${docs.src.dir}/faq"/>
            <param name="xml-source-root" 
                  value="faq.xml"/>
            <param name="xsl-source-file" 
                  value="${nochunk.xsl.source}"/>
            <param name="xml-target-dir" 
                  value="${docs.dist.dir}"/>
            <param name="xml-target-file" 
                  value="${docs.dist.dir}/doc/faq.html"/>
        </antcall>
    </target>

    <!-- experimental targets collapse guide-making (lose individual targets) -->
    <target name="progguide" depends="init">
      <antcall target="build-guide">
        <param name="guide.dir" value="progGuideDB"/>
        <param name="guide.name" value="progguide"/>
      </antcall>
    </target>

    <target name="devguide" depends="init">
      <copy todir="${docs.src.dir}/devGuideDB" filtering="off" >
         <fileset dir="${aspectj.modules.dir}/ajde/src/org/aspectj/ajde/resources/actions"
             includes="${include.devguide.icons}" />
        </copy>
      <antcall target="build-guide">
        <param name="guide.dir" value="devGuideDB"/>
        <param name="guide.name" value="devguide"/>
      </antcall>
      <delete quiet="on"> <!-- clean icons for build-in-place -->
        <fileset dir="${docs.src.dir}/devGuideDB" 
           includes="${include.devguide.icons}" />
      </delete>
    </target>

    <target name="build-guide" depends="init"
     description="build prog or dev guide, using guide.dir and guide.name">
        <!-- chunked -->
        <antcall target="xml-html">
            <param name="xml-source-dir" 
                  value="${docs.src.dir}/${guide.dir}"/>
            <param name="xml-source-root" 
                  value="${guide.name}.xml"/>
            <param name="xsl-source-file" 
                  value="${chunk.xsl.source}"/>
            <param name="xml-target-dir" 
                  value="${docs.dist.dir}/doc/${guide.name}"/>
        </antcall>
        <!-- single -->
        <antcall target="xml-html">
            <param name="xml-source-dir" 
                  value="${docs.src.dir}/${guide.dir}"/>
            <param name="xml-source-root" 
                  value="${guide.name}.xml"/>
            <param name="xsl-source-file" 
                  value="${nochunk.xsl.source}"/>
            <param name="xml-target-dir" 
                  value="${docs.dist.dir}/doc/${guide.name}"/>
            <param name="xml-target-file" 
                  value="${docs.dist.dir}/doc/${guide.name}/printable.html"/>
        </antcall>
        <!-- pdf - enable when it works 
        <antcall target="xml-pdf">
            <param name="xml-source-dir" 
                  value="${docs.src.dir}/doc/${guide.dir}"/>
            <param name="xml-source-root" value="${guide.name}.xml"/>
            <param name="xml-target-file" 
                  value="${docs.dist.dir}/doc/${guide.name}.pdf"/>
        </antcall>
        -->
    </target>
    <!-- end of experimental targets -->

   <!-- XML conversion stuff -->

   <!-- todo xml-pdf broken; when fixed, see xml-html for example -->
    <target name="xml-pdf">
        <delete file="${xml-target-file}"/>
        <touch file="${xml-target-file}"/>
        <java classname="com.icl.saxon.StyleSheet"
              fork="yes">
            <classpath>
                <pathelement location="${saxon.dir}/saxon.jar"/>
            </classpath>
            <arg value="-o"/>
            <arg value="${xml-source-dir}/index.fo"/>
            <arg value="${xml-source-dir}/${xml-source-root}"/>
            <arg value="${docbook.dir}/docbook-xsl/fo/docbook.xsl"/>
        </java>            
    </target>

   <target name="xml-html"
    description="antcall(xml-source-dir, xml-source-root, xml-target-dir, xml-target-file)
     convert xml to html using docbook. parameters: 
     xml-source-dir  # base directory of source 
     xml-source-root # base file of source (relative to xml-source-dir)
     xsl-source-file # xsl transform to apply (use chunk.xsl.source by default) 
     xml-target-dir  # target directory for output (used as xsl param base.dir)
     xml-target-file # full path to output file in xml-source-dir, ignored when chunking
     xml-html-copy   # copy files to target (defaults to *.gif,*.png">

     <mkdir dir="${xml-target-dir}"/>
        <copy todir="${xml-target-dir}">
            <fileset dir="${xml-source-dir}" 
                includes="${xml-html-copy}"/>
        </copy>
        <java classname="com.icl.saxon.StyleSheet"
              classpath="${aspectj.modules.lib.dir}/saxon/saxon.jar"
                   fork="yes" 
            failonerror="yes"> <!-- todo: establish failure policy -->
            <arg value="-o"/>
            <arg value="${xml-target-file}"/>
            <arg value="${xml-source-dir}/${xml-source-root}"/>
            <arg value="${xsl-source-file}"/>
            <arg value="base.dir=${xml-target-dir}/"/>
        </java>            
    </target>

  <target name="info" 
     description="misc info for writing and building docbook">
<echo>
---- misc info for writing and building docbook
- link tag linkend attribute takes an id 
  - xsl converts as needed during output
  - do NOT use ulink; this will be converted to ""
    (but see param citerefentry-link: might enable this)

- to use sensible names for the files produced, 
  - use an xsl wrapper to add/modify features
  - set flag to use the id of the top-level element in the output
    file as the filename.  
    xsl:param name="use.id.as.filename" select="1"
  - fyi, other related parameters: html-ext, root-filename
  - In this example, the top-level element in the output file
    is the refentry, so set ids which become the basename of the file:
    refentry id="aspectj-mode"          # in aspectj-mode.xml, produces aspecj-mode.html
    refentry id="ajdee"                 # in ajdee.xml, produces ajdee.html

-- fyi
- related parameters: 
  html-ext, root-filename
- these tags did not work for me:
 dbhtml filename="foo.htm"
 dbhtml prefix="foo-"

- resources 
  - the dtd reference for docbook
    http://www.oreilly.com/catalog/docbook/chapter/book/docbook.html
  - the stylesheet reference for docbook xsl
    http://docbook.sourceforge.net/projects/dsssl/doc/html.html
- todo
  - fyi, generate.reference.titlepage appears not to be respected.
    tried to add if statement to html/refentry.xsl, but file still gen'd
</echo>
  </target>

</project>