You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by mm...@apache.org on 2001/09/03 13:41:07 UTC
cvs commit: xml-cocoon2/xdocs catalog.xml
mman 01/09/03 04:41:07
Modified: webapp/resources/entities CatalogManager.properties
xdocs catalog.xml
Log:
patch from David Crossley <cr...@indexgeo.com.au>
---------
webapp/resources/entities/CatalogManager.properties.diff
- raise default verbosity level to 2
- explain messages at each verbosity level
---------
xdocs/catalog.xml.diff
- explain how to extend the default properties to suit local needs
- show example local configuration for Simplified DocBook
and full DocBook DTDs
- list of platforms with reports of successful usage
Revision Changes Path
1.4 +9 -4 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.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- CatalogManager.properties 2001/08/31 11:44:13 1.3
+++ CatalogManager.properties 2001/09/03 11:41:07 1.4
@@ -7,18 +7,23 @@
# 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
+# verbosity ... level of messages for status/debug (messages go to STDOUT)
# 0 (none) .. 3 (maximum)
+# The following messages are provided ...
+# 0 = none
+# 1 = ?
+# 2 = 1+, Loading catalog, Resolved public, Resolved system
+# 3 = 2+, Catalog does not exist, resolvePublic, resolveSystem
+# TODO cocoon-dev: determine all messages at each level
#
-verbosity=1
+verbosity=2
# catalogs ... list of initial catalogs to load
# use full pathnames
# pathname separator is always semi-colon (;) regardless of operating system
# directory separator is always slash (/) regardless of operating system
#
-catalogs=@install.war@/cocoon/resources/entities/catalog;/path/to/other/local/catalog
+catalogs=@install.war@/cocoon/resources/entities/catalog
# prefer ... we prefer to use Public Identifiers for entity resolution
#
1.3 +115 -49 xml-cocoon2/xdocs/catalog.xml
Index: catalog.xml
===================================================================
RCS file: /home/cvs/xml-cocoon2/xdocs/catalog.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- catalog.xml 2001/08/31 11:44:13 1.2
+++ catalog.xml 2001/09/03 11:41:07 1.3
@@ -5,9 +5,8 @@
<document>
<header>
<title>Entity resolution with catalogs</title>
- <subtitle>Resolve entities to local or other resources</subtitle>
-<!-- ??? what use is subtitle - it is not displayed -->
- <version>1.1</version>
+ <subtitle>Resolve external entities to local or other resources</subtitle>
+ <version>1.3</version>
<type>Technical document</type>
<authors>
<person name="David Crossley" email="crossley@indexgeo.com.au"/>
@@ -64,13 +63,19 @@
- explains more detailed need and use of catalogs
</li>
<li>
- <link href="#imp">Implementation and Configuration</link>
- - describes how support for catalogs is added to @doctitle@ and
- provides the few configuration steps
+ <link href="#imp">Implementation and default configuration</link>
+ - describes how support for catalogs is added to @docname@ and
+ explain the default configuration (which should work out-of-the-box)
</li>
<li>
+ <link href="#config">Local configuration</link>
+ - explains how to extend the default configuration for your local
+ system reqirements and provides an example
+ </li>
+ <li>
<link href="#dev">Development notes</link>
- - basic catalog support is now in the HEAD branch - needs minor tweaks
+ - default catalog support is now in the 2.1-dev branch
+ - needs to confirm operation on all major platforms
</li>
<li>
<link href="#notes">Other notes</link>
@@ -238,7 +243,8 @@
role, and each included external entity reports how it came into being.
This example builds upon the example provided by the Walsh article.
(Tip: To see the error message that would result from not using a catalog,
- simply rename the properties file before starting @docname@.)
+ simply rename the default properties file or default catalog file before
+ starting @docname@.)
</p>
<note>TODO: ensure that the link to samples works OK</note>
@@ -338,7 +344,7 @@
</s1>
<anchor id="imp"/>
- <s1 title="Implementation and Configuration">
+ <s1 title="Implementation and default 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
@@ -356,10 +362,7 @@
<li>A default annotated <code>CatalogManager.properties</code> file is
included with the distribution (see the Build Notes below).
</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>
+ <li>The automatic default configuration should work out-of-the-box</li>
</ul>
<note>TODO: We need to explain the properties file here in doco (the internal
@@ -367,6 +370,13 @@
Sun download.
</note>
+ <p>
+ If you suspect problems, then you can raise the level of the
+ <code>verbosity</code> property (to 2 or 3) and watch the messages going
+ to stdout when @docname@ starts and operates. You would also do this to
+ detect any misconfiguration of your own catalogs.
+ </p>
+
<s2 title="Build Notes">
<p>
Use the following options to your build command ...
@@ -385,14 +395,81 @@
</p>
<p>
- If you see messages going to STDOUT when @docname@ starts
+ If you see an error message 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.
+ that you build as described above, or edit and move the properties file
+ into place manually.
</p>
</s2>
</s1>
+ <anchor id="config"/>
+ <s1 title="Local configuration">
+ <p>
+ You can add your own catalog by appending another full pathname to
+ the <code>catalogs</code> property in the default properties file
+ (see notes inside the properties file).
+ </p>
+
+ <p>
+ The actual "catalog" files have a powerful set of directives.
+ For example, the <strong>CATALOG</strong> directive facilitates the
+ inclusion of a sub-ordinate catalog. The list of resources below will
+ lead to <link href="#info">further information</link> about catalog usage.
+ </p>
+
+ <s2 title="Example local configuration for Simplified DocBook">
+ <p>
+ We use the Simplified DocBook XML DTD for some of our documentation.
+ Here are the few steps that we followed to configure @docname@ to be able
+ to process our XML instances.
+ </p>
+
+ <ul>
+ <li>
+ downloaded a recent copy of the Simplified DocBook DTD distribution
+ and unpacked it at
+ <code>/usr/local/sgml/docbook/simple/</code>
+ </li>
+ <li>
+ created a catalog file at
+ <code>/usr/local/sgml/docbook/simple/sdocbook.cat</code>
+ with a single entry for the Simplified DocBook XML DTD
+ </li>
+ <li>
+ appended the full pathname to the <code>catalogs</code> property in the
+ <code>CatalogManager.properties</code> file
+ </li>
+ </ul>
+
+<source><![CDATA[
+-- Catalog file (sdocbook.cat) for Simplified DocBook --
+-- See www.oasis-open.org/docbook/ --
+
+-- Driver file for the Simplified DocBook XML DTD --
+PUBLIC "-//OASIS//DTD Simplified DocBook XML V4.1.2.5//EN"
+ "sdocbook.dtd"
+
+-- end of catalog file for Simplified DocBook --
+]]></source>
+
+ <p>
+ We could similarly configure @docname@ for the full DocBook XML DTD and
+ related entities. In fact, the DocBook distribution already contains a
+ catalog file. We need only append the pathname to our <code>catalogs</code>
+ property.
+ </p>
+
+ <p>
+ There are a few important starting points for
+ <link href="#info">further information</link> about using and configuring
+ the DocBook DTDs.
+ </p>
+
+ </s2>
+ </s1>
+
<anchor id="dev"/>
<s1 title="Development notes">
@@ -401,12 +478,13 @@
</p>
<ul>
- <li>4) ? Is there any negative impact on performance? I can see one extra
- file read per parse - does that matter? Perhaps there are mostly
- performance improvements instead.
+ <li>5) ? What other default entities need to be shipped with the @docname@
+ distribution? We already have some character entity sets (ISO*.pen).
</li>
- <li>5) ? What other default entities need to be shipped? We already have
- some character entity sets (ISO*.pen).
+ <li>6) Future: It would be nice to have the
+ <code>org.apache.cocoon.components.resolver</code> classes
+ automatically load the default catalog, thereby leaving the
+ <code>properties</code> config file totally free for local use.
</li>
</ul>
@@ -417,10 +495,12 @@
<ol>
<li>Linux Red Hat 7.1, java.vm.version=Blackdown-1.3.1-FCS,
Tomcat 3.2.2 ... OK</li>
- <li>Macintosh ... looking for a test platform</li>
- <li>Windows ... looking for a test platform</li>
- <li>Other UNIX ... looking for a test platform</li>
- <li>Other JDK versions ... looking for a test platform</li>
+ <li>Win2K, Tomcat 3.3 ... OK</li>
+ <li>Windows 2000 Professional, Tomcat 3.2.3 and Tomcat 3.2.1 ... OK</li>
+ <li>Macintosh ... looking for success story</li>
+ <li>Other Windows ... looking for success story</li>
+ <li>Other UNIX ... looking for success story</li>
+ <li>Other JDK versions ... looking for success story</li>
</ol>
<p>
@@ -438,29 +518,6 @@
</li>
</ul>
- <p>
- Some relevant past discussion on @docname@ mailing lists ...
- </p>
-
- <ul>
- <li>
- <link href="http://mailman.real-time.com/pipermail/cocoon-devel/2000-August/000940.html">Re: DTD PUBLIC ID resolution</link>
-Fri, 04 Aug 2000 09:20:15 +1000
- <br/>
- <link href="http://mailman.real-time.com/pipermail/cocoon-devel/2000-August/000964.html">Re: DTD PUBLIC ID resolution</link>
-Sat, 05 Aug 2000 20:58:50 +0200
- </li>
-
- <li>
- <link href="http://mailman.real-time.com/pipermail/cocoon-devel/2001-May/thread.html#7236">[Fwd: Re: C2: Sitemaps and DTD's]</link>
-Thu, 03 May 2001 09:41:24 -0400
- </li>
-
- <li>
- <link href="http://mailman.real-time.com/pipermail/cocoon-devel/2001-August/thread.html#10365">proposal: entity resolution capability</link>
-Fri, 10 Aug 2001 16:04:27 +1000
- </li>
- </ul>
</s1>
<anchor id="notes"/>
@@ -534,8 +591,17 @@
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><link href="http://www.oasis-open.org/docbook/">DocBook</link>:
+ <link href="http://www.docbook.org/">The Definitive Guide</link>
+ - Section 2.3 Public Identifiers, System Identifiers, and Catalog Files
+ </li>
+ <li>OASIS is the <link href="http://www.oasis-open.org/docbook/">official
+ home</link> of the DocBook DTDs
+ (see also <link href="http://docbook.sourceforge.net/">DocBook Open
+ Repository</link> project at SourceForge)
+ </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: webmaster@xml.apache.org
To unsubscribe, e-mail: cocoon-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: cocoon-cvs-help@xml.apache.org