dims 01/08/31 04:44:13
Modified: webapp/resources/entities CatalogManager.properties
xdocs catalog.xml
Log:
Patches from David Crossley <[EMAIL PROTECTED]> for
- "entity catalogs - CatalogManager.properties"
- "entity catalogs - xdocs/catalog.xml"
Revision Changes Path
1.3 +13 -11 xml-cocoon2/webapp/resources/entities/CatalogManager.properties
Index: CatalogManager.properties
===================================================================
RCS file: /home/cvs/xml-cocoon2/webapp/resources/entities/CatalogManager.properties,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- CatalogManager.properties 2001/08/30 12:44:01 1.2
+++ CatalogManager.properties 2001/08/31 11:44:13 1.3
@@ -1,20 +1,22 @@
# CatalogManager.properties
#
-# This is the default properties file for Apache Cocoon
-# see the Apache Cocoon documentation (catalog.html)
-# Place this file somewhere accessible to your Java classpath
+# This is the default properties file for @docname@.
+#
+# See the documentation (catalog.html). Please follow the Build Notes
+# to allow the build process to put this file in a location that will be
+# available to the Java classpath and to automatically adjust the
+# "catalogs" pathname to suit your local directory structure.
# verbosity ... level of messages for status/debug
+# messages go to STDOUT
# 0 (none) .. 3 (maximum)
-# TODO: check these settings in Javadocs
#
-verbosity=3
+verbosity=1
# catalogs ... list of initial catalogs to load
# use full pathnames
-# pathname separator is always semi-colon (;) regardless of OS
-# TODO cocoon-dev: we can probably get ResolverImpl.java to load the
-# default catalog, thereby leaving this properties file for local config
+# pathname separator is always semi-colon (;) regardless of operating system
+# directory separator is always slash (/) regardless of operating system
#
[EMAIL PROTECTED]@/cocoon/resources/entities/catalog;/path/to/other/local/catalog
@@ -23,17 +25,17 @@
prefer=public
# static-catalog ... see the Sun doco
-# TODO cocoon-dev: ? what impact does this setting have for Apache Cocoon
+# TODO cocoon-dev: ? what impact does this setting have for @docname@
#
static-catalog=yes
# allow-oasis-xml-catalog-pi ... see the Sun doco
-# TODO cocoon-dev: ? what impact does this setting have for Apache Cocoon
+# TODO cocoon-dev: ? what impact does this setting have for @docname@
#
allow-oasis-xml-catalog-pi=yes
# catalog-class-name ... specify an alternate class name to use
-# Apache Cocoon does not need this setting - we have a named class
+# @docname@ does not need this setting - we already have a named class
#
# catalog-class-name=com.sun.resolver.Resolver
1.2 +84 -49 xml-cocoon2/xdocs/catalog.xml
Index: catalog.xml
===================================================================
RCS file: /home/cvs/xml-cocoon2/xdocs/catalog.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- catalog.xml 2001/08/28 12:52:23 1.1
+++ catalog.xml 2001/08/31 11:44:13 1.2
@@ -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>
----------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
