Re: Patch to readd documentation

Oliver Jowett wrote:
> I think you should be able to validate the docs at the XML level using
> just the XML libraries provided with recent JDKs (I'll check if this
> works shortly). We do need the DocBook XML DTDs available to properly
> validate the document, but that seems less onerous than needing a recent
> XSLT processor plus DocBook stylesheets.
>
> Ant has a XMLValidate task that might be useful here.

The attached patch implements this. It'll use a local copy of the
DocBook XML DTDs if present, otherwise it'll grab them from the system
URI given in pgjdbc.xml (i.e. from www.open-oasis.org). See the comments
in the patch for more details.

This works here using:

$ ant -version
Apache Ant version 1.5.4 compiled on September 22 2003

$ java -version
java version "1.4.2_03"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.2_03-b02)
Java HotSpot(TM) Client VM (build 1.4.2_03-b02, mixed mode)

-O
Index: build.xml
===================================================================
RCS file: /usr/local/cvsroot/pgjdbc/pgjdbc/build.xml,v
retrieving revision 1.42
diff -u -c -r1.42 build.xml
*** build.xml    26 Jan 2004 14:03:48 -0000    1.42
--- build.xml    27 Jan 2004 03:59:57 -0000
***************
*** 344,347 ****
--- 344,426 ----
     <delete file="${builddir}/doc/pgjdbc.html"/>
    </target>

+   <!-- Blah. Can't reference an external XML catalog until Ant 1.6.
+        So instead we copy the contents of doc/docbook-dtd/catalog.xml
+        here, in the form that Ant's xmlcatalog element wants. -->
+   <xmlcatalog id="docbook-catalog">
+     <dtd publicId="-//OASIS//DTD DocBook XML V4.2//EN"
+       location="doc/docbook-dtd/docbookx.dtd"/>
+     <entity publicId="-//OASIS//DTD DocBook CALS Table Model V4.2//EN"
+       location="doc/docbook-dtd/calstblx.dtd"/>
+     <entity publicId="-//OASIS//DTD XML Exchange Table Model 19990315//EN"
+       location="doc/docbook-dtd/soextblx.dtd"/>
+     <entity publicId="-//OASIS//ELEMENTS DocBook Information Pool V4.2//EN"
+       location="doc/docbook-dtd/dbpoolx.mod"/>
+     <entity publicId="-//OASIS//ELEMENTS DocBook Document Hierarchy V4.2//EN"
+       location="doc/docbook-dtd/dbhierx.mod"/>
+     <entity publicId="-//OASIS//ENTITIES DocBook Additional General Entities V4.2//EN"
+       location="doc/docbook-dtd/dbgenent.mod"/>
+     <entity publicId="-//OASIS//ENTITIES DocBook Notations V4.2//EN"
+       location="doc/docbook-dtd/dbnotnx.mod"/>
+     <entity publicId="-//OASIS//ENTITIES DocBook Character Entities V4.2//EN"
+       location="doc/docbook-dtd/dbcentx.mod"/>
+     <entity publicId="ISO 8879:1986//ENTITIES Diacritical Marks//EN//XML"
+       location="doc/docbook-dtd/ent/iso-dia.ent"/>
+     <entity publicId="ISO 8879:1986//ENTITIES Numeric and Special Graphic//EN//XML"
+       location="doc/docbook-dtd/ent/iso-num.ent"/>
+     <entity publicId="ISO 8879:1986//ENTITIES Publishing//EN//XML"
+       location="doc/docbook-dtd/ent/iso-pub.ent"/>
+     <entity publicId="ISO 8879:1986//ENTITIES General Technical//EN//XML"
+       location="doc/docbook-dtd/ent/iso-tech.ent"/>
+     <entity publicId="ISO 8879:1986//ENTITIES Added Latin 1//EN//XML"
+       location="doc/docbook-dtd/ent/iso-lat1.ent"/>
+     <entity publicId="ISO 8879:1986//ENTITIES Added Latin 2//EN//XML"
+       location="doc/docbook-dtd/ent/iso-lat2.ent"/>
+     <entity publicId="ISO 8879:1986//ENTITIES Greek Letters//EN//XML"
+       location="doc/docbook-dtd/ent/iso-grk1.ent"/>
+     <entity publicId="ISO 8879:1986//ENTITIES Monotoniko Greek//EN//XML"
+       location="doc/docbook-dtd/ent/iso-grk2.ent"/>
+     <entity publicId="ISO 8879:1986//ENTITIES Greek Symbols//EN//XML"
+       location="doc/docbook-dtd/ent/iso-grk3.ent"/>
+     <entity publicId="ISO 8879:1986//ENTITIES Alternative Greek Symbols//EN//XML"
+       location="doc/docbook-dtd/ent/iso-grk4.ent"/>
+     <entity publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Arrow Relations//EN//XML"
+       location="doc/docbook-dtd/ent/iso-amsa.ent"/>
+     <entity publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Binary Operators//EN//XML"
+       location="doc/docbook-dtd/ent/iso-amsb.ent"/>
+     <entity publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Delimiters//EN//XML"
+       location="doc/docbook-dtd/ent/iso-amsc.ent"/>
+     <entity publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Negated Relations//EN//XML"
+       location="doc/docbook-dtd/ent/iso-amsn.ent"/>
+     <entity publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Ordinary//EN//XML"
+       location="doc/docbook-dtd/ent/iso-amso.ent"/>
+     <entity publicId="ISO 8879:1986//ENTITIES Added Math Symbols: Relations//EN//XML"
+       location="doc/docbook-dtd/ent/iso-amsr.ent"/>
+     <entity publicId="ISO 8879:1986//ENTITIES Box and Line Drawing//EN//XML"
+       location="doc/docbook-dtd/ent/iso-box.ent"/>
+     <entity publicId="ISO 8879:1986//ENTITIES Russian Cyrillic//EN//XML"
+       location="doc/docbook-dtd/ent/iso-cyr1.ent"/>
+     <entity publicId="ISO 8879:1986//ENTITIES Non-Russian Cyrillic//EN//XML"
+       location="doc/docbook-dtd/ent/iso-cyr2.ent"/>
+   </xmlcatalog>
+
+   <!-- Validate but don't process the documentation.
+        This target expects the DocBook XML DTDs, available at
+        http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip, to be
+        present in doc/docbook-dtd. If they're not present, they will
+        be fetched on each validation from www.oasis-open.org.
+
+        Note that if the DTD fetch fails, validation fails with a fairly
+        useless error message. Run ant with -verbose to get a more useful
+        error. You'll need to set the java properties http.proxyHost and
+        http.proxyPort if you need to go via a proxy to fetch the DTDs.
+   -->
+
+   <target name="validate-doc" depends="prepare">
+     <xmlvalidate warn="true">
+       <fileset dir="doc" includes="*.xml"/>
+       <xmlcatalog refid="docbook-catalog"/>
+     </xmlvalidate>
+   </target>
+
  </project>