cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Martin Man <Martin....@seznam.cz>
Subject Re: [Patch] catalogs - properties and xdocs
Date Mon, 03 Sep 2001 11:44:23 GMT
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


Mime
View raw message