You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by David Crossley <cr...@indexgeo.com.au> on 2001/09/03 13:33:54 UTC
[Patch] catalogs - properties and xdocs
Please find two attached patches for entity catalogs.
---------
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
regards, David Crossley
Re: [Patch] catalogs - properties and xdocs
Posted by Martin Man <Ma...@seznam.cz>.
hi david,
patch applied, please check that everyting works well.
rgds,
martin
On Mon, Sep 03, 2001 at 09:33:54PM +1000, David Crossley wrote:
> Please find two attached patches for entity catalogs.
>
> ---------
> 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
>
> regards, David Crossley
> Index: CatalogManager.properties
> ===================================================================
> RCS file: /home/cvspublic/xml-cocoon2/webapp/resources/entities/CatalogManager.properties,v
> retrieving revision 1.3
> diff -u -r1.3 CatalogManager.properties
> --- CatalogManager.properties 2001/08/31 11:44:13 1.3
> +++ CatalogManager.properties 2001/09/03 10:59:11
> @@ -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
> #
> Index: catalog.xml
> ===================================================================
> RCS file: /home/cvspublic/xml-cocoon2/xdocs/catalog.xml,v
> retrieving revision 1.2
> diff -u -r1.2 catalog.xml
> --- catalog.xml 2001/08/31 11:44:13 1.2
> +++ catalog.xml 2001/09/03 10:59:56
> @@ -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>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
> For additional commands, email: cocoon-dev-help@xml.apache.org
--
-------------------------------------------------------------------------------
"Only dead fish swims with a stream" Malcolm Muggeridge
gpg_key_available: http://globales.cz/~mman/martin.man.gpg
gpg_key_fingerprint: 2CC0 4AF6 92DA 5CBF 5F09 7BCB 6202 7024 6E06 0223
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org