The attached patch will update the catalog document to
reflect the new way of distributing the CatalogManager.properties
file ... i.e. the build process puts the properties file into the
directory webapps/cocoon/WEB-INF/classes/ and adjusts the
path to the default catalog to suit the local directory structure.
regards, David
Index: catalog.xml
===================================================================
RCS file: /home/cvspublic/xml-cocoon2/xdocs/catalog.xml,v
retrieving revision 1.1
diff -u -r1.1 catalog.xml
--- catalog.xml 2001/08/28 12:52:23 1.1
+++ catalog.xml 2001/08/31 06:07:36
@@ -7,7 +7,7 @@
<title>Entity resolution with catalogs</title>
<subtitle>Resolve entities to local or other resources</subtitle>
<!-- ??? what use is subtitle - it is not displayed -->
- <version>0.6</version>
+ <version>1.1</version>
<type>Technical document</type>
<authors>
<person name="David Crossley" email="[EMAIL PROTECTED]"/>
@@ -22,10 +22,6 @@
and failure-prone network retrieval of the required resources (e.g. DTDs,
character entity sets, XML sub-documents).
</p>
-
-<note>To enable catalog support, you need to edit one line of a simple
- properties file (<link href="#imp">discussed below</link>).
- </note>
</s1>
<s1 title="Overview">
@@ -68,7 +64,7 @@
- explains more detailed need and use of catalogs
</li>
<li>
- <link href="#imp">Implementation</link>
+ <link href="#imp">Implementation and Configuration</link>
- describes how support for catalogs is added to @doctitle@ and
provides the few configuration steps
</li>
@@ -77,6 +73,10 @@
- basic catalog support is now in the HEAD branch - needs minor tweaks
</li>
<li>
+ <link href="#notes">Other notes</link>
+ - assorted notes
+ </li>
+ <li>
<link href="#summ">Summary</link>
</li>
<li>
@@ -154,8 +154,8 @@
<note>TODO: briefly explain each of those declarations</note>
<p>
- (In your XML instance document you would include those entities like
- this ... <code>%ISOnum;</code>)
+ (In your XML instance document, or DTD, you would include those entities
+ like this ... <code>%ISOnum;</code>)
</p>
<p>
@@ -220,7 +220,8 @@
<p>
System identifiers can use full pathnames, filenames, relative pathnames,
- or URLs - if it is just a filename or a relative pathname, then the
+ or URLs - in fact, any method that will define and deliver the actual
+ physical entity. If it is just a filename or a relative pathname, then the
entity resolver will look for the resource relative to the location of
the catalog.
</p>
@@ -337,46 +338,66 @@
</s1>
<anchor id="imp"/>
- <s1 title="Implementation">
+ <s1 title="Implementation and Configuration">
<p>
- The SAX <code>Parser</code> interface provides an <code>entityResolver</code> hook
to allow an application to resolve the external entities. The Sun Microsystems Java
code for "<code>resolver.jar</code>" provides a CatalogManager. This is already
incorporated into @doctitle@ - all that you need to do, is to make the
-"<code>CatalogManager.properties</code>" file available on your classpath.
+ The SAX <code>Parser</code> interface provides an <code>entityResolver</code>
+ hook to allow an application to resolve the external entities. The Sun
+ Microsystems Java code for "<code>resolver.jar</code>" provides a
+ CatalogManager. This is incorporated into @doctitle@ as
+ <code>org.apache.cocoon.components.resolver</code> and configuration is
+ achieved via the <code>CatalogManager.properties</code> file.
</p>
<ul>
- <li>An example annotated <code>CatalogManager.properties</code> file is
- shipped with @doctitle@
-(<code>webapps/cocoon/resources/entities/CatalogManager.properties</code>)
- </li>
<li>A default catalog and some base entities (e.g. ISO*.pen character
- entity sets) are available at
- <code>webapps/cocoon/resources/entities/</code> ... the example properties
- file declares this default catalog.
+ entity sets) are included in the @doctitle@ distribution at
+ <code>webapps/cocoon/resources/entities/</code>
</li>
- <li>You will need to edit the properties file to provide the full pathname
- to the default catalog (and add your own too). [see dev note below]
+ <li>A default annotated <code>CatalogManager.properties</code> file is
+ included with the distribution (see the Build Notes below).
</li>
- <li>Make your properties file available on your classpath before starting
- the servlet engine.</li>
+ <li>You can add your own catalog by appending another full pathname to
+ the <code>catalogs</code> entry in the default properties file
+ (see notes inside the properties file).
+ </li>
</ul>
- <note>TODO: Later we will figure out how to load the default catalog automatically
with pathname from cocoon config, thereby leaving the properties file for loading
local catalogs.
+ <note>TODO: We need to explain the properties file here in doco (the internal
+ annotation helps for now) ... full documentation is available with the
+ Sun download.
</note>
- <note>TODO: We need to explain the properties file here in doco (annotation helps
for now) ... full documentation is avaiable with the Sun download.
- </note>
+ <s2 title="Build Notes">
+ <p>
+ Use the following options to your build command ...
+ <br/><code>-Dinclude.webapp.libs=yes</code>
+ <br/><code>-Dinstall.war=$TOMCAT_HOME/webapps install</code>
+ </p>
+
+ <p>
+ This allows the build process to copy the properties file from
+<code>$COCOON_HOME/webapp/resources/entities/CatalogManager.properties</code>
+ to
+<code>$TOMCAT_HOME/webapps/cocoon/WEB-INF/classes/CatalogManager.properties</code>
+ thereby making it available to the Java classpath. The build process will
+ also automatically adjust the full pathname for the default catalog to suit
+ your local directory structure.
+ </p>
+
+ <p>
+ If you see messages going to STDOUT when @docname@ starts
+ (<code>Cannot find CatalogManager.properties</code>) then this means that
+ the properties file is not available to the Java classpath. Please ensure
+ that you build as described above.
+ </p>
+ </s2>
</s1>
<anchor id="dev"/>
<s1 title="Development notes">
- <p>
- We are current using the tried and true catalog format - plain-text files
- OASIS Catalogs (TR 9401:1995 Entity Management). XML-based catalogs can also be
used. However, the standard is not yet settled. OASIS TR9401 catalogs will suffice.
See note below.
- </p>
-
<p>
- Assistance is required with the following development issues ...
+ Assistance is required with the following outstanding development issues ...
</p>
<ul>
@@ -384,6 +405,9 @@
file read per parse - does that matter? Perhaps there are mostly
performance improvements instead.
</li>
+ <li>5) ? What other default entities need to be shipped? We already have
+ some character entity sets (ISO*.pen).
+ </li>
</ul>
<p>
@@ -437,25 +461,32 @@
Fri, 10 Aug 2001 16:04:27 +1000
</li>
</ul>
+ </s1>
- <p>
- Other notes that still need to be added in to this document somewhere ...
- </p>
+ <anchor id="notes"/>
+ <s1 title="Other notes">
<ul>
- <li>there has been a recent flood of XML tools - unfortunately, many do not
- implement entity resolution (other than by brute-force retrieval), so
- those tools are crippled and cannot be used for serious XML processing
- </li>
<li>OASIS Catalogs (TR 9401:1995 Entity Management) are plain-text files
with a simple delimited format. There is also a new standard being
developed for XML Catalogs, using an xml-based structured plain-text file
(gee :-). Links to both standards are provided below. Both catalog formats
- can be currently used with this entity resolver.
+ can be currently used with this entity resolver. However, the latter
+ standard is not yet settled. OASIS TR9401 catalogs will suffice.
</li>
- <li>if there is no mapping for an identifier in the catalog (or in any
+ <li>There has been a recent flood of XML tools - unfortunately, many do not
+ implement entity resolution (other than by brute-force retrieval), so
+ those tools are crippled and cannot be used for serious XML processing.
+ Please ensure that you choose proper XML tools for the preparation and
+ vaildation of your XML instance documents.
+ </li>
+ <li>If there is no mapping for an identifier in the catalog (or in any
sub-ordinate catalogs), then @docname@ will carry on to retrieve the
- resource using the declared system identifier
+ resource using the declared system identifier.
+ </li>
+ <li>The default catalog that is shipped with the @docname@ distribution is
+ deliberately basic. You will need to supplement it with your own catalog
+ devised to suit your particular needs.
</li>
</ul>
</s1>
@@ -463,7 +494,7 @@
<anchor id="summ"/>
<s1 title="Summary">
<p>
- Most XML documents that we would want to serve with @docname@ are already in
existence in another information system. The XML document instances have a declaration
of their DTD Document Type Definition as an external file. This external DTD also
includes entity sets such as ISOnum, ISOlat1, etc. Also the DTD declaration has a
Formal Public Identifier and a System Identifier which points to a remote URL. These
XML instance documents cannot be changed.
+ Most XML documents that we would want to serve with @docname@ are already in
+existence in another information system. The XML document instances have a
+declaration of their DTD Document Type Definition as an external file. This external
+DTD also includes entity sets such as ISOnum, ISOlat1, etc. Also the DTD declaration
+has a Formal Public Identifier and a System Identifier which points to a remote URL.
+These XML instance documents cannot be altered to make workaround solutions like
+<code>../dtd/document-1.0.dtd</code>
</p>
<p>
@@ -487,20 +518,24 @@
<li><link href="http://www.oasis-open.org/cover/topics.html#entities";>SGML/XML
Special Topics: Entity Sets and Entity Management</link>
at the
<link href="http://www.oasis-open.org/cover/";>XML Cover Pages</link></li>
- <li><link href="http://www.oasis-open.org/cover/topics.html#fpi-fsi";>SGML/XML
Special Topics: Catalogs, Formal Public Identifiers, Formal System Identifiers</link>
+ <li><link href="http://www.oasis-open.org/cover/topics.html#fpi-fsi";>SGML/XML
+ Special Topics: Catalogs, Formal Public Identifiers, Formal System
+ Identifiers</link>
at the
<link href="http://www.oasis-open.org/cover/";>XML Cover Pages</link></li>
- <li>Arbortext column by Norm Walsh
+ <li>Arbortext column by Norman Walsh
<link href="http://www.arbortext.com/Think_Tank/think_tank.html";>Standard
Deviations from Norm</link>
- <br/> - Issue Three
+ <br/> - Issue Three:
<link
href="http://www.arbortext.com/Think_Tank/XML_Resources/Issue_Three/issue_three.html";>If
You Can Name It, You Can Claim It!</link></li>
<li>
- <link href="http://www.sun.com/xml/developers/resolver/";>XML Entity and URI
Resolvers Java classes</link> and evolution of the Arbortext article.
+ <link href="http://www.sun.com/xml/developers/resolver/";>XML Entity and
+ URI Resolvers Java classes</link> (from Sun Microsystems) and evolution
+ of the Arbortext article.
</li>
<li>XML-Deviant article 2000-11-29
- <link href="http://www.xml.com/pub/a/2000/11/29/deviant.html";>What's in a
-Name?</link></li>
+ <link href="http://www.xml.com/pub/a/2000/11/29/deviant.html";>What's in
+ a Name?</link></li>
<li>Organization for the Advancement of Structured Information Standards
(<link href="http://www.oasis-open.org/";>OASIS</link>)</li>
</ul>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]
