From ceba17b25db8d21f38bc1d10452241adfbedd5d0 Mon Sep 17 00:00:00 2001 From: Stefan Bodewig Date: Thu, 21 Mar 2002 08:58:09 +0000 Subject: [PATCH] documentation for xmlcatalog Submitted by: dion@multitask.com.au git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@271932 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/CoreTypes/xmlcatalog.html | 135 ++++++++++++++++++++++++++ docs/manual/conceptstypeslist.html | 2 +- docs/manual/credits.html | 1 + 3 files changed, 137 insertions(+), 1 deletion(-) create mode 100644 docs/manual/CoreTypes/xmlcatalog.html diff --git a/docs/manual/CoreTypes/xmlcatalog.html b/docs/manual/CoreTypes/xmlcatalog.html new file mode 100644 index 000000000..dfe4fec0e --- /dev/null +++ b/docs/manual/CoreTypes/xmlcatalog.html @@ -0,0 +1,135 @@ + + + + +XMLCatalog Type + + + + +

XMLCatalog

+

An XMLCatalog is a catalog of public resources such as DTDs or entities +that +are referenced in an XML document and are available locally.

+

This allows the XML Parser, XSL Processor or other consumer of XML +documents +to efficiently allow a local substitution for a resource available on the +web. +

+

For example, in a web.xml file, the DTD is referenced as: +

+<!DOCTYPE web-app
+  PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 
+2.2//EN"
+  "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">
+
+The XML processor, without XMLCatalog support, would need to retrieve the +DTD from +the URL specified whenever validation of the document was required. +

+

This can be very time consuming during the build process, especially +where +network throughput is limited.

+

+

XMLCatalogs can appear inside tasks +that support this feature or at the same level as target +- i.e., as children of project for reuse across different +tasks, +e.g. XML Validation and XSL Translation.

+

XMLCatalogs are specified as either a reference to another XMLCatalog, +defined +previously in a build file, or as a list of dtd or +entity locations.

+

XMLCatalog attributes

+ + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
ida unique name for an XMLCatalog, used for referencing +the + XMLCatalog's contents from another XMLCatalogNo
refidthe id of another XMLCatalog whose +contents + you would like to be used for this XMLCatalogNo
+ +

XMLCatalog nested elements

+

The dtd and entity elements used to specify +XMLCatalogs are identical in their structure

+ + + + + + + + + + + + + + + + +
AttributeDescriptionRequired
publicIdThe public identifier used when defining a dtd or +entity, + e.g. "-//Sun Microsystems, Inc.//DTD Web Application +2.2//EN" + Yes
locationThe location of the local replacement to be used for +the + public identifier specified. This may be specified as a file name, +resource + name found on the classpath, or a URL + Yes
+

Examples

+

Set up an XMLCatalog with a single dtd referenced locally in a user's +home +directory:

+
+    <xmlcatalog>
+        <dtd publicId="-//OASIS//DTD DocBook XML V4.1.2//EN"
+ location="/home/dion/downloads/docbook/docbookx.dtd"/>
+    </xmlcatalog>
+
+

Set up an XMLCatalog with a multiple dtds referenced locally in a +user's home +directory:

+
+    <xmlcatalog id="commonDTDs">
+        <dtd publicId="-//OASIS//DTD DocBook XML V4.1.2//EN"
+ location="/home/dion/downloads/docbook/docbookx.dtd"/>
+        <dtd publicId="-//Sun Microsystems, Inc.//DTD Web 
+Application 2.2//EN"
+             location="/home/dion/web-app_2_2.dtd"/>
+    </xmlcatalog>
+
+

To reference the above xmlcatalog in a style task:

+

+    <style basedir="${source.doc}"
+           destdir="${dest.xdocs}"
+           extension=".xml"
+           style="${source.xsl.converter.docbook}"
+           includes="**/*.xml"
+           force="true">
+        <xmlcatalog refid="commonDTDs"/>
+    </style>
+
+ +
+

Copyright © 2002 Apache Software Foundation. All +rights +Reserved.

+ + + diff --git a/docs/manual/conceptstypeslist.html b/docs/manual/conceptstypeslist.html index a2cbc22b8..915c590d3 100644 --- a/docs/manual/conceptstypeslist.html +++ b/docs/manual/conceptstypeslist.html @@ -21,6 +21,6 @@ FilterChains and FilterReaders
Filterset
Patternset
- +XMLCatalog
diff --git a/docs/manual/credits.html b/docs/manual/credits.html index 7a68da69c..af935a3cc 100644 --- a/docs/manual/credits.html +++ b/docs/manual/credits.html @@ -21,6 +21,7 @@
  • Tom Dimock (tad1@cornell.edu)
  • Peter Donald (donaldp@apache.org)
  • Erik Hatcher (ehatcher@apache.org)
    • +
  • dIon Gillard (dion@apache.org)
  • Diane Holt (holtdl@yahoo.com)
  • Bill Kelly (bill.kelly@softwired-inc.com)
  • Arnout J. Kuiper (ajkuiper@wxs.nl)