nbbuild/javadoctools/template.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--

    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.

-->

<!DOCTYPE someant  [
  <!ENTITY links SYSTEM "links.xml">
  <!ENTITY links8 SYSTEM "links8.xml">
  <!ENTITY links11 SYSTEM "links11.xml">
  <!ENTITY properties SYSTEM "properties.xml">
  <!ENTITY replacesjdk SYSTEM "replacesjdk.xml">
  <!ENTITY replaces SYSTEM "replaces.xml">
  <!ENTITY disallowed-links SYSTEM "disallowed-links.xml">
]>

<project name="template" default="die" basedir="." xmlns:if="ant:if" xmlns:unless="ant:unless">

    <import file="../default-properties.xml"/>

    <description><![CDATA[
Templated targets:

------------------------------ javadoc ------------------------
${javadoc.base}       top dir of module, e.g. "${nb_all}/foo" ("." from your build script)
${javadoc.name}       name of docs folder, e.g. "org-netbeans-modules-foo"
${javadoc.title}      display title of docs, e.g. "Foo API"
${javadoc.packages}   list of packages to build, e.g. "org.netbeans.api.foo,org.netbeans.spi.foo"
${javadoc.classpath}  classpath for source files (probably same as what you use for <javac>)
Optional:
${javadoc.files}      selector describing which files to build
${javadoc.main.page}  link to main page, e.g. org/netbeans/api/foo/doc-files/api.html
${javadoc.docfiles}   doc-files directory such as ${javadoc.base}/api/doc; default none
${javadoc.apichanges} API change list XML file; default no change list
${javadoc.arch}       architecture summary of the module; default a dummy summary
${javadoc.overview}   Overview HTML file; default a generic page
${javadoc.check.external.links}  set to "true" to check external HTTP links
${javadoc.header}     Special header text.
${javadoc.web.root}   Base URL for online Javadoc for linking; default http://www.netbeans.org/download/dev/javadoc

To call this script you MUST use the form of <ant> with the 'dir' attribute. This
script expects that its basedir is the directory containing it. If you use only
the 'antfile' attribute the basedir will be copied from your script, which will
cause it to fail.
]]></description>

    <target name="die">
        <fail>Use this script only from other scripts, to call templated targets.</fail>
    </target>

    <!-- javadoc -->

    <target name="javadoc-init" >

        <!-- Output dir (will create ${javadoc.name}/ and ${javadoc.name}.zip beneath this): -->
        <property name="javadoc.out" location="${netbeans.javadoc.dir}"/>
        <property name="javadoc.out.dir" location="${javadoc.out}/${javadoc.name}"/>
        <property name="javadoc.out.zip" location="${javadoc.out}/${javadoc.name}.zip"/>
        <!-- Source files: -->
        <property name="javadoc.src" location="${javadoc.base}/src"/>
        <!-- Extra HTML files, normally in **/doc-files/*.html: -->
        <property name="javadoc.docfiles" location="no-doc-files"/>
        <condition property="javadoc.overview.generate.generic">
            <not>
                <isset property="javadoc.overview" />
            </not>
        </condition>
        <property name="javadoc.overview" location="../build/tmp/overview/${javadoc.name}-overview-generic.html"/>
        <mkdir dir="${javadoc.overview}/../" />
        <property name="javadoc.apichanges" location="apichanges-empty.xml"/>
        <property name="javadoc.arch" location="arch-empty.xml"/>

        <!-- Docs to link to: -->
        <property name="javadoc.web.root" value="http://root/"/>
        <condition property="javadoc.docs.jdk" value="https://docs.oracle.com/en/java/javase/11/docs/api/">
            <not>
                <isset property="javaapidocurl"/>
            </not>
        </condition>
        <property name="javadoc.docs.jdk" value="${javaapidocurl}"/>
        &properties;
        <!-- add more here as needed... -->
        <property name="javadoc.css.dir" location="."/>
        <property name="javadoc.css.main" location="${javadoc.css.dir}/javadoc.css"/>
        <fileset id="javadoc.css.files" dir="${javadoc.css.dir}">
            <include name="*.css"/>
        </fileset>
        <property name="javadoc.resources.dir" location="resources"/>
        <fileset id="javadoc.resources.files" dir="${javadoc.resources.dir}">
            <include name="**/*"/>
            <exclude name="**/*.xcf"/> <!-- GIMP versions of the images -->
        </fileset>
        <property name="javadoc.check.external.links" value="false"/>
        <property name="javadoc.header" value="&amp;nbsp;"/>

        <!-- Determine API stability -->
        <mkdir dir="../build/tmp/javadoc-colors"/>
        <delete file="../build/tmp/javadoc-colors/${javadoc.name}.txt" failonerror="false"/>
        <arch answers="${javadoc.arch}" xsl="export2color.xsl" output="../build/tmp/javadoc-colors/${javadoc.name}.txt" />
        <property file="../build/tmp/javadoc-colors/${javadoc.name}.txt"/>
        <property name="javadoc.stability.label" value="&lt;span style='font-style:normal; font-size:medium; font-weight:normal; background-color:${stability.color};'&gt;&lt;a href='${stability.definition.url}' target='_blank'&gt;${stability.title}&lt;/a&gt;&lt;/span&gt;"/>

        <condition property="nb-docs.css" value="nb-docs-stability.css">
            <isset property="stability.image"/>
        </condition>
        <condition property="nb-docs.css" value="nb-docs.css">
            <not>
                <isset property="stability.image"/>
            </not>
        </condition>

        <mkdir dir="${javadoc.out.dir}"/>

        <condition property="javadoc.files.provided">
            <isset property="javadoc.files" />
        </condition>

        <!-- default value for javadoc-files -->
        <selector id="all-java-files" >
            <filename name="**/*.java" />
        </selector>
        <property name="javadoc.files" value="all-java-files" />

        <property file="../build.properties" />

        <condition property="javadoc.reference.generated" >
            <isset property="javadoc.docs.${javadoc.name}" />
        </condition>
        <!-- generate a javac.source for javadoc task that prioritize javac.release over javac.source -->
        <condition property="javac.sourcerelease" value="${javac.release}" else="${javac.source}" >
            <not>
                <equals arg1="${javac.release}" arg2="" trim="true"/>
            </not>
        </condition>
    </target>

    <target name="javadoc-generate-references" depends="javadoc-init" unless="javadoc.reference.generated" >
        <!-- Add these files to the generated ones -->
        <concat append="true" destfile="properties.xml" ><![CDATA[<property name="javadoc.docs.${javadoc.name}" value="$${javadoc.web.root}/${javadoc.name}"/>]]>
        </concat>
        <concat append="true" destfile="links.xml" ><![CDATA[<link href="$${javadoc.docs.${javadoc.name}}" offline="true" packagelistloc="${javadoc.out.dir}"/>]]>
        </concat>
        <concat append="true" destfile="replaces.xml" ><![CDATA[<replacefilter token="@${javadoc.name}@" value="$${javadoc.docs.${javadoc.name}}"/>]]>
        </concat>

        <replace
            token="${netbeans.javadoc.dir}"
            value="$${netbeans.javadoc.dir}"
            file="links.xml"
        />

        <!-- set the property for use in this script -->
        <property name="javadoc.docs.${javadoc.name}" value="${javadoc.web.root}/${javadoc.name}" />
    </target>

    <target name="javadoc-generate-overview" depends="javadoc-init,javadoc-check-timestamps" unless="javadoc.overview.should.not.be.generated" >
        <delete file="${javadoc.overview}" />

        <property file="${export.interfaces}/properties/all.properties" />
        <arch xsl="exportOverview.xsl" answers="${javadoc.arch}" output="${javadoc.overview}" stylesheet="prose.css"
              apichanges="${javadoc.apichanges}" project="${javadoc.project}"
        >
            <!--
            <param name="changes-since-year" expression="${previous.release.year}"/>
            <param name="changes-since-day" expression="${previous.release.day}"/>
            <param name="changes-since-month" expression="${previous.release.month}"/>
            -->
        </arch>
    </target>

    <target name="javadoc-check-timestamps" depends="javadoc-init">
        <uptodate targetfile="${javadoc.out.zip}" property="javadoc.up.to.date">
            <srcfiles dir="${javadoc.src}" erroronmissingdir="false">
                <or>
                    <and>
                        <selector refid="${javadoc.files}" />
                        <filename name="**/*.java"/>
                    </and>
                    <!-- Can have inline docs too: -->
                    <filename name="**/package.html"/>
                    <filename name="**/doc-files/"/>
                </or>
            </srcfiles>
            <srcfiles dir="${javadoc.docfiles}"/>
            <srcfiles refid="javadoc.css.files"/>
            <srcfiles refid="javadoc.resources.files"/>
            <srcfiles dir=".">
                <include name="apichanges.xsl"/>
            </srcfiles>
            <srcfiles file="${javadoc.apichanges}"/>
            <srcfiles file="${javadoc.arch}"/>
            <srcfiles file="${javadoc.overview}"/>
            <srcfiles file="exportOverview.xsl"/>
        </uptodate>
        <condition property="javadoc.should.not.be.generated" >
            <or>
                <isset property="javadoc.up.to.date" />
                <not>
                    <isset property="javadoc.packages" />
                </not>
                <equals arg1="${javadoc.packages}" arg2="" />
            </or>
        </condition>
        <condition property="javadoc.interfaces.should.not.be.generated" >
            <or>
                <isset property="javadoc.up.to.date" />
                <not>
                    <isset property="export.interfaces" />
                </not>
            </or>
        </condition>
        <condition property="javadoc.apichanges.should.not.be.generated" >
            <or>
                <isset property="javadoc.up.to.date" />
                <not>
                    <isset property="export.apichanges" />
                </not>
            </or>
        </condition>
        <condition property="javadoc.overview.should.not.be.generated" >
            <or>
                <isset property="javadoc.up.to.date" />
                <not>
                    <isset property="javadoc.overview.generate.generic" />
                </not>
            </or>
        </condition>
        <condition property="javadoc23.or.later">
            <javaversion atleast="23"/>
        </condition>
        <condition property="javadoc8.or.sooner">
            <javaversion atmost="8"/>
        </condition>
        <echo level="verbose">javadoc.up.to.date=${javadoc.up.to.date} javadoc.should.not.be.generated=${javadoc.should.not.be.generated} javadoc.packages=${javadoc.packages}</echo>
    </target>

    <target name="javadoc-make-plain-title" unless="javadoc.main.page">
        <property name="javadoc.hyperlinked.title" value="${javadoc.title}"/>
    </target>

    <target name="javadoc-make-hyperlinked-title" if="javadoc.main.page">
        <!-- <property name="javadoc.hyperlinked.title" value='&lt;a href="@TOP@${javadoc.main.page}"&gt;${javadoc.title}&lt;/a&gt;'/> -->
        <property name="javadoc.hyperlinked.title" value="${javadoc.title}"/>
    </target>

    <target name="javadoc-stage-alternative" depends="javadoc-init,javadoc-check-timestamps" if="javadoc.should.not.be.generated" unless="javadoc.up.to.date" >
        <!-- if no packages are specified, this is used to generate index.html from the overview page -->
        <copy file="${javadoc.overview}" tofile="${javadoc.out.dir}/index.html" />
    </target>

    <target name="javadoc-stage-main" depends="javadoc-init,javadoc-check-timestamps,javadoc-exec-files,javadoc-exec-packages" unless="javadoc.should.not.be.generated" >
        <tstamp>
            <format property="YEAR" pattern="yyyy"/>
        </tstamp>
        <copy todir="${javadoc.out.dir}/resource-files">
            <fileset refid="javadoc.css.files"/>
        </copy>
        
        <replace dir="${javadoc.out.dir}" >
            <include name="**/javadoc*.css"/>
            <include name="nb-docs-stability.css"/>
            <replacefilter token="@CSS_TIMESTAMP@" value="Built on ${TODAY}. Copyright 2017-${YEAR} The Apache Software Foundation. All Rights Reserved." />
            <replacefilter token="@nb-docs-css@" value="${nb-docs.css}"/>
            <replacefilter token="@api-stability-image@" value="${stability.image}"/>
        </replace>
        <mkdir dir="${javadoc.out.dir}/resources"/>
        <mkdir dir="${javadoc.out.dir}/resource-files/resources"/>
        <copy file="${javadoc.out.dir}/resource-files/glass.png" todir="${javadoc.out.dir}/resource-files/resources" />
        <copy file="${javadoc.out.dir}/resource-files/x.png" todir="${javadoc.out.dir}/resource-files/resources" />
          
        <copy todir="${javadoc.out.dir}/resources">
            <fileset refid="javadoc.resources.files"/>
        </copy>
    </target>

    <target name="javadoc-exec-condition" depends="javadoc-check-timestamps" >
        <condition property="javadoc.exec.packages">
            <or>
                <isset property="javadoc.files.provided"/>
                <isset property="javadoc.should.not.be.generated"/>
                <not>
                    <available file="${javadoc.src}"/>
                </not>
            </or>
        </condition>
    </target>

    <target name="-javadoc-set-footer">
        <!-- Timestamp is handled in javadoc.css to avoid too many commits on generated HTML files. -->
        <property name="javadoc.footer" value='&lt;span class="footnote"&gt;&lt;/span&gt;&lt;!-- See javadoc.css for timestamp information --&gt;'/>
    </target>

    <condition property="apidoc.check" value="true" else="false">
        <isset property="apidocfullcheck"/>
        <!-- CI parameter -->
        <!-- fail on error and warning as error means no javadoc content and missing page on bits.netbeans.org -->
    </condition>

    <target name="javadoc-exec-packages" depends="javadoc-init,javadoc-generate-references,javadoc-generate-overview,javadoc-exec-condition,javadoc-check-timestamps,javadoc-make-plain-title,javadoc-make-hyperlinked-title,javadoc-exec-condition,-javadoc-set-footer" unless="javadoc.exec.packages">
        <javadoc source="${javac.sourcerelease}" failonerror="${apidoc.check}" failonwarning="false" author="false" destdir="${javadoc.out.dir}" packagenames="${javadoc.packages}" stylesheetfile="${javadoc.css.main}" windowtitle="${javadoc.title}" overview="${javadoc.overview}" splitindex="true" use="true" version="false" useexternalfile="true" encoding="UTF-8">
            <sourcepath>
                <pathelement location="${javadoc.docfiles}"/>
                <pathelement location="${javadoc.src}"/>
                <pathelement location="${javadoc.src}/../build/classes-generated"/>
            </sourcepath><!--
            <doclet
                name="org.apidesign.javadoc.codesnippet.Doclet"
                path="${nb_all}/nbbuild/external/codesnippet-doclet-1.0.jar"
            >
                <param name="-snippetpath" value="${javadoc.base}/src"/>
                <param name="-snippetpath" value="${javadoc.base}/test/unit/src"/>
                <param name="-maxLineLength" value="240"/> <!- - 120 was too short - ->
                <param name="-snippetmode" value="jep413"/>
            </doclet>
            -->
            <classpath path="${javadoc.classpath}"/>
            <!-- XXX note, this does not support more than one group -->
            <group packages="${javadoc.packages}">
                <title>${javadoc.hyperlinked.title}</title>
            </group>
            <!-- jdk 8 backward -->
            &links8;
            <!-- jdk modular apidoc -->
            &links11;
            <!-- other links -->
            &links;
            <doctitle>${javadoc.title}&lt;br/&gt;${javadoc.stability.label}</doctitle>
            <header>${javadoc.header}</header>
            <bottom>${javadoc.footer}</bottom>
            <!-- Avoid timestamp comments in _all_ html generated files, to reduce unnecessary git commits -->
            <arg value="-notimestamp" />
            <!-- codebase has many occurrences of '///' which were never meant to appear in javadoc
            this disables JDK 23+ "line doc comments" for now  -->
            <arg value="--disable-line-doc-comments" if:true="${javadoc23.or.later}" />
            <arg value="-Xdoclint:all" />
            <arg value="-Xdoclint:-missing" />
            <arg value="--allow-script-in-comments" if:true="${javadoc23.or.later}" />
            <arg value="--snippet-path ${javadoc.base}/test/unit/src:${javadoc.base}/src" if:true="${javadoc23.or.later}" />
            <arg value="--no-fonts" if:true="${javadoc23.or.later}" />
        </javadoc>
    </target>

    <target name="javadoc-exec-files" depends="javadoc-init,javadoc-generate-references,javadoc-generate-overview,javadoc-exec-condition,javadoc-check-timestamps,javadoc-make-plain-title,javadoc-make-hyperlinked-title" if="javadoc.files.provided,-javadoc-set-footer" unless="javadoc.up.to.date">
        <javadoc source="${javac.sourcerelease}" author="false" destdir="${javadoc.out.dir}" packagenames="${javadoc.packages}" stylesheetfile="${javadoc.css.main}" windowtitle="${javadoc.title}" overview="${javadoc.overview}" splitindex="true" use="true" version="false" useexternalfile="true" encoding="UTF-8">
            <fileset dir="${javadoc.docfiles}"/>
            <fileset dir="${javadoc.src}" >
                <and>
                    <selector refid="${javadoc.files}" />
                    <filename name="**/*.java" />
                </and>
            </fileset>
            <classpath path="${javadoc.classpath}"/>
            <!-- XXX note, this does not support more than one group -->
            <group packages="${javadoc.packages}">
                <title>${javadoc.hyperlinked.title}</title>
            </group>
            <!-- jdk 8 backward -->
            &links8;
            <!-- jdk modular apidoc -->
            &links11;
            <!-- other links -->
            &links;
            <doctitle>${javadoc.title}&lt;br/&gt;${javadoc.stability.label}</doctitle>
            <header>${javadoc.header}</header>
            <bottom>${javadoc.footer}</bottom>
            <!-- codebase has many occurrences of '///' which were never meant to appear in javadoc
            this disables JDK 23+ "line doc comments" for now  -->
            <arg value="--disable-line-doc-comments" if:true="${javadoc23.or.later}" />
            <arg value="-Xdoclint:all" />
            <arg value="-Xdoclint:-missing" />
        </javadoc>
    </target>

    <target name="javadoc-stage-apichanges" depends="javadoc-init,javadoc-check-timestamps,javadoc-stage-export-apichanges" unless="javadoc.up.to.date">
        <available file="${javadoc.out.dir}/deprecated-list.html" property="hasdeprecated"/>
        <xslt in="${javadoc.apichanges}" out="${javadoc.out.dir}/apichanges.html" style="apichanges.xsl">
            <xmlcatalog refid="nbantextcatalog" />
            <param name="javadoc-url-base" expression="."/>
            <param name="javadoc-header" expression="${javadoc.header}" />
            <param name="deprecated" expression="${hasdeprecated}" />
        </xslt>
    </target>

    <target name="javadoc-stage-export-apichanges" depends="javadoc-init,javadoc-check-timestamps,javadoc-stage-init-apichanges" unless="javadoc.apichanges.should.not.be.generated">
        <fail message="Need to specify the date of branching of previous.release.year: ${previous.release.year}" unless="previous.release.year" />
        <fail message="Need to specify the date of branching of previous.release.month: ${previous.release.month}" unless="previous.release.month" />
        <fail message="Need to specify the date of branching of previous.release.day: ${previous.release.day}" unless="previous.release.day" />

        <xslt in="${javadoc.apichanges}" out="${export.apichanges}/${javadoc.name}" style="export-apichanges.xsl">
            <xmlcatalog refid="nbantextcatalog" />
            <param name="changes-since-url" expression="${javadoc.name}/apichanges.html"/>
            <param name="changes-since-year" expression="${previous.release.year}"/>
            <param name="changes-since-day" expression="${previous.release.day}"/>
            <param name="changes-since-month" expression="${previous.release.month}"/>
        </xslt>
    </target>

    <target name="javadoc-stage-init-apichanges" depends="javadoc-init,javadoc-check-timestamps" unless="javadoc.up.to.date">
        <xmlvalidate file="${javadoc.apichanges}" failonerror="true">
            <xmlcatalog refid="nbantextcatalog" />
        </xmlvalidate>
    </target>

    <target name="javadoc-stage-arch" depends="javadoc-init,javadoc-check-timestamps" unless="javadoc.up.to.date">
        <taskdef name="arch" classname="org.netbeans.nbbuild.Arch">
            <classpath>
                <pathelement location="${nbantext.jar}"/>
            </classpath>
        </taskdef>
        <!-- Warn about incorrect question version, but do not make build fail: -->
        <property name="arch.warn" value="true"/>
        <available file="${javadoc.out.dir}/deprecated-list.html" property="hasdeprecated"/>
        <arch answers="${javadoc.arch}"
              output="${javadoc.out.dir}/architecture-summary.html"
              stylesheet="prose.css"
              overviewlink="overview-summary.html"
              footer="@FOOTER@"
              project="${javadoc.project}"
              header="${javadoc.header}"
              deprecatedmenu="${hasdeprecated}"
        />
    </target>

    <target name="javadoc-stage-export-interfaces" depends="javadoc-init,javadoc-check-timestamps" unless="javadoc.interfaces.should.not.be.generated">
        <taskdef name="arch" classname="org.netbeans.nbbuild.Arch">
            <classpath>
                <pathelement location="${nbantext.jar}"/>
            </classpath>
        </taskdef>
        <!-- Warn about incorrect question version, but do not make build fail: -->
        <property name="arch.warn" value="true"/>
        <property name="arch.target" value="${javadoc.name}" />
        <mkdir dir="${export.interfaces}"/>
        <arch xsl="exportInterfaces.xsl" answers="${javadoc.arch}" output="${export.interfaces}/architecture-summary.html" stylesheet="prose.css"/>
        <move file="${export.interfaces}/architecture-summary.html" tofile="${export.interfaces}/${javadoc.name}" />
        <mkdir dir="${export.interfaces}/properties" />
        <xslt style="exportInterfaceProperties.xsl" in="${export.interfaces}/${javadoc.name}" out="${export.interfaces}/properties/${javadoc.name}" >
            <param name="code.name.base" expression="${javadoc.name}" />
        </xslt>
        <concat destfile="${export.interfaces}/properties/all.properties" >
            <fileset dir="${export.interfaces}/properties/">
                <include name="*" />
                <exclude name="all.properties" />
            </fileset>
        </concat>
    </target>

    <target name="javadoc-stage-replace-apichanges" depends="javadoc-stage-main,javadoc-generate-references,javadoc-stage-alternative,javadoc-stage-apichanges,javadoc-stage-arch,javadoc-stage-export-interfaces" unless="javadoc.up.to.date" if="export.apichanges" >
        <replace dir="${export.apichanges}" >
            <include name="${javadoc.name}"/>
            &replacesjdk;
            <replacefilter token="@FOOTER@" value="${javadoc.footer}"/>
            <replacefilter token="@TOP@/" value="@TOP@" />
            <replacefilter token="@TOP@" value="${javadoc.name}/" />
            &replaces;
        </replace>
    </target>
    <target name="javadoc-stage-replace-interfaces" depends="javadoc-stage-main,javadoc-generate-references,javadoc-stage-alternative,javadoc-stage-apichanges,javadoc-stage-arch,javadoc-stage-export-interfaces" unless="javadoc.up.to.date" if="export.interfaces" >
        <replace dir="${export.interfaces}" >
            <include name="${javadoc.name}"/>
            &replacesjdk;
            <replacefilter token="@FOOTER@" value="${javadoc.footer}"/>
            <replacefilter token="@TOP@/" value="@TOP@" />
            <replacefilter token="@TOP@" value="${javadoc.name}/" />
            &replaces;
        </replace>
    </target>

    <target name="javadoc-stage-replace" depends="javadoc-stage-main,javadoc-generate-references,javadoc-stage-alternative,javadoc-stage-apichanges,javadoc-stage-arch,javadoc-stage-export-interfaces,javadoc-stage-replace-interfaces,javadoc-stage-replace-apichanges" unless="javadoc.up.to.date">
        <!-- need to cleanup href for allclasses as starting jdk21 javadoc this file take also description -->
        <replaceregexp match="href=&quot;.*\@org" replace="href=&quot;\@org" flags="g" >
            <fileset dir="${javadoc.out.dir}" includes="allclasses-index.html"/>
        </replaceregexp>
        
        <replace dir="${javadoc.out.dir}">
            <include name="**/*.html"/>
            &replacesjdk;
            &replaces;
            <replacefilter token="@FOOTER@" value="${javadoc.footer}"/>
        </replace>

        <replace dir="${javadoc.out.dir}">
            <include name="**/*.html"/>
            <replacefilter token="http://root/" value="@TOP@.." />
        </replace>
        <replace dir="${javadoc.out.dir}">
            <include name="**/*.html"/>
            <replacefilter token="http://top/" value="@TOP@" />
        </replace>
        <replace dir="${javadoc.out.dir}" token="@TOP@/" value="@TOP@">
            <include name="**/*.html"/>
        </replace>
        <replaceregexp match="href=&quot;.*\@TOP\@" replace="href=&quot;\@TOP\@" flags="g" >
            <fileset dir="${javadoc.out.dir}" includes="index-files/**/*.html"/>
        </replaceregexp>
        <replaceregexp match="href=&quot;.*\@TOP\@" replace="href=&quot;\@TOP\@" flags="g" >
            <fileset dir="${javadoc.out.dir}" includes="**/**/deprecated-list.html"/>
        </replaceregexp>
        <replaceregexp match="href=&quot;.*\@TOP\@" replace="href=&quot;\@TOP\@" flags="g" >
            <fileset dir="${javadoc.out.dir}" includes="**/**/class-use/*.html"/>
        </replaceregexp>


        <replace dir="${javadoc.out.dir}">
            <replacetoken><![CDATA[<ul id="navbar-top-firstrow" class="nav-list" title="Navigation">]]></replacetoken>
            <replacevalue><![CDATA[<ul id="navbar-top-firstrow" class="nav-list" title="Navigation"><li><a href="@TOP@apichanges.html">API Changes</a></li><li><a href="@TOP@architecture-summary.html">Architecture Summary</a></li>]]></replacevalue>
            <include name="**/*.html"/>
            <exclude name="**/**/architecture-summary.html"/>
            <exclude name="**/**/apichanges.html"/>
        </replace>
        <replace dir="${javadoc.out.dir}" token="@TOP@" value="">
            <include name="*.html"/>
        </replace>
        <replace dir="${javadoc.out.dir}" token="@TOP@" value="../">
            <include name="*/*.html"/>
        </replace>
        <replace dir="${javadoc.out.dir}" token="@TOP@" value="../../">
            <include name="*/*/*.html"/>
        </replace>
        <replace dir="${javadoc.out.dir}" token="@TOP@" value="../../../">
            <include name="*/*/*/*.html"/>
        </replace>
        <replace dir="${javadoc.out.dir}" token="@TOP@" value="../../../../">
            <include name="*/*/*/*/*.html"/>
        </replace>
        <replace dir="${javadoc.out.dir}" token="@TOP@" value="../../../../../">
            <include name="*/*/*/*/*/*.html"/>
        </replace>
        <replace dir="${javadoc.out.dir}" token="@TOP@" value="../../../../../../">
            <include name="*/*/*/*/*/*/*.html"/>
        </replace>
        <replace dir="${javadoc.out.dir}" token="@TOP@" value="../../../../../../../">
            <include name="*/*/*/*/*/*/*/*.html"/>
        </replace>
        <replace dir="${javadoc.out.dir}" token="@TOP@" value="../../../../../../../../">
            <include name="*/*/*/*/*/*/*/*/*.html"/>
        </replace>
        <replace dir="${javadoc.out.dir}" token="@TOP@" value="../../../../../../../../../">
            <include name="*/*/*/*/*/*/*/*/*/*.html"/>
        </replace>
        <replace dir="${javadoc.out.dir}" token="@TOP@" value="../../../../../../../../../../">
            <include name="*/*/*/*/*/*/*/*/*/*/*.html"/>
        </replace>
    </target>

    <target name="javadoc-stage-check" depends="javadoc-stage-replace" unless="javadoc.up.to.date">
        <taskdef name="checklinks" classname="org.netbeans.nbbuild.CheckLinks">
            <classpath>
                <pathelement location="${nbantext.jar}"/>
            </classpath>
        </taskdef>
        <checklinks basedir="${javadoc.out.dir}" checkexternal="${javadoc.check.external.links}"
                    report="${javadoc.out.dir}/checklinks-errors-${javadoc.name}.xml" checkspaces="false">
            <include name="overview-summary.html"/>
            <include name="apichanges.html"/>
            <include name="architecture-summary.html"/>
            <include name="**/package-summary.html"/>
            <!--<include name="**/doc-files/**/*.html"/>-->
            <include name="**/*.html"/>
            <!-- XXX why are not all **/*.html checked? Would then need to allow e.g. http://blogs.sun.com/geertjan/entry/swing_outline_component from OutlineView.html -->
            <!-- Make hyperlinks point to the source files, not the copied files: -->
            <!-- XXX but line numbers are wrong in several cases! -->
            <!-- checking all html file for now on -->
            <mapper type="glob" from="${javadoc.out.dir}/overview-summary.html" to="${javadoc.arch}"/>
            <mapper type="glob" from="${javadoc.out.dir}/*/package-summary.html" to="${javadoc.docfiles}/*/package.html"/>
            <mapper type="glob" from="${javadoc.out.dir}/*/package-summary.html" to="${javadoc.src}/*/package.html"/>
            <mapper type="glob" from="${javadoc.out.dir}/apichanges.html" to="${javadoc.apichanges}"/>
            <mapper type="glob" from="${javadoc.out.dir}/architecture-summary.html" to="${javadoc.arch}"/>
            <mapper type="glob" from="${javadoc.out.dir}/*.html" to="${javadoc.docfiles}/*.html"/>
            <mapper type="glob" from="${javadoc.out.dir}/*.html" to="${javadoc.src}/*.html"/>

						&disallowed-links;
        </checklinks>
        <!-- XXX run doctorj (doctorj.sf.net) if it is installed? -->
    </target>

    <target name="javadoc" depends="javadoc-stage-check" unless="javadoc.up.to.date" description="Build Javadoc and associated documentation for a module.">
        <zip zipfile="${javadoc.out.zip}" basedir="${javadoc.out.dir}"/>
    </target>
</project>