Entity resolution with catalogs

Return-Path: Delivered-To: apmail-xml-cocoon-dev-archive@xml.apache.org Received: (qmail 3478 invoked by uid 500); 3 Sep 2001 11:44:10 -0000 Mailing-List: contact cocoon-dev-help@xml.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: list-post: Reply-To: cocoon-dev@xml.apache.org Delivered-To: mailing list cocoon-dev@xml.apache.org Received: (qmail 3464 invoked from network); 3 Sep 2001 11:44:09 -0000 Date: Mon, 3 Sep 2001 13:44:23 +0200 To: David Crossley Cc: cocoon-dev@xml.apache.org Subject: Re: [Patch] catalogs - properties and xdocs Message-ID: <20010903134422.B2981@funny.localnet> References: <01090321335400.00935@localhost.localdomain> Mime-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Disposition: inline In-Reply-To: <01090321335400.00935@localhost.localdomain> User-Agent: Mutt/1.3.20i From: Martin Man X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N 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 @@ > >

> Entity resolution with catalogs > - Resolve entities to local or other resources > - > - 1.1 > + Resolve external entities to local or other resources > + 1.3 > Technical document > > > @@ -64,13 +63,19 @@ > - explains more detailed need and use of catalogs > >

> - Implementation and Configuration > - - describes how support for catalogs is added to @doctitle@ and > - provides the few configuration steps > + Implementation and default configuration > + - describes how support for catalogs is added to @docname@ and > + explain the default configuration (which should work out-of-the-box) >

> + Local configuration > + - explains how to extend the default configuration for your local > + system reqirements and provides an example > +

> +

> Development notes > - - 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 >

> Other notes > @@ -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@.) >

> > TODO: ensure that the link to samples works OK > @@ -338,7 +344,7 @@ > > > > - > + >

> The SAX Parser interface provides an entityResolver > hook to allow an application to resolve the external entities. The Sun > @@ -356,10 +362,7 @@ >

A default annotated CatalogManager.properties file is > included with the distribution (see the Build Notes below). >

> -

You can add your own catalog by appending another full pathname to > - the catalogs entry in the default properties file > - (see notes inside the properties file). > -

> +

The automatic default configuration should work out-of-the-box

> > > TODO: We need to explain the properties file here in doco (the internal > @@ -367,6 +370,13 @@ > Sun download. > > > +

> + If you suspect problems, then you can raise the level of the > + verbosity 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. > +

> + > >

> Use the following options to your build command ... > @@ -385,14 +395,81 @@ >

> >

> - If you see messages going to STDOUT when @docname@ starts > + If you see an error message going to STDOUT when @docname@ starts > (Cannot find CatalogManager.properties) 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. >

> > > > + > + > +

> + You can add your own catalog by appending another full pathname to > + the catalogs property in the default properties file > + (see notes inside the properties file). > +

> + > +

> + The actual "catalog" files have a powerful set of directives. > + For example, the CATALOG directive facilitates the > + inclusion of a sub-ordinate catalog. The list of resources below will > + lead to further information about catalog usage. > +

> + > + > +

> + 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. > +

> + > +

> + downloaded a recent copy of the Simplified DocBook DTD distribution > + and unpacked it at > + /usr/local/sgml/docbook/simple/ > +
> + created a catalog file at > + /usr/local/sgml/docbook/simple/sdocbook.cat > + with a single entry for the Simplified DocBook XML DTD > +
> + appended the full pathname to the catalogs property in the > + CatalogManager.properties file > +

> + > + +-- 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 -- > +]]> > + > +

> + 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 catalogs > + property. > +

> + > +

> + There are a few important starting points for > + further information about using and configuring > + the DocBook DTDs. > +

> + > + > + > + > > > > @@ -401,12 +478,13 @@ >

> >

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. > +
5) ? What other default entities need to be shipped with the @docname@ > + distribution? We already have some character entity sets (ISO*.pen). >
5) ? What other default entities need to be shipped? We already have > - some character entity sets (ISO*.pen). > +
6) Future: It would be nice to have the > + org.apache.cocoon.components.resolver classes > + automatically load the default catalog, thereby leaving the > + properties config file totally free for local use. >

> > @@ -417,10 +495,12 @@ >

Linux Red Hat 7.1, java.vm.version=Blackdown-1.3.1-FCS, > Tomcat 3.2.2 ... OK
Macintosh ... looking for a test platform
Windows ... looking for a test platform
Other UNIX ... looking for a test platform
Other JDK versions ... looking for a test platform
Win2K, Tomcat 3.3 ... OK
Windows 2000 Professional, Tomcat 3.2.3 and Tomcat 3.2.1 ... OK
Macintosh ... looking for success story
Other Windows ... looking for success story
Other UNIX ... looking for success story
Other JDK versions ... looking for success story

> >

> @@ -438,29 +518,6 @@ > > > > -

> - Some relevant past discussion on @docname@ mailing lists ... > -

> - > -

> - Re: DTD PUBLIC ID resolution > -Fri, 04 Aug 2000 09:20:15 +1000 > -
> - Re: DTD PUBLIC ID resolution > -Sat, 05 Aug 2000 20:58:50 +0200 > -
> - [Fwd: Re: C2: Sitemaps and DTD's] > -Thu, 03 May 2001 09:41:24 -0400 > -
> - proposal: entity resolution capability > -Fri, 10 Aug 2001 16:04:27 +1000 > -

> > > > @@ -534,8 +591,17 @@ > of the Arbortext article. > >

XML-Deviant article 2000-11-29 > - What's in > - a Name?

> + What's in > + a Name? > +

DocBook: > + The Definitive Guide > + - Section 2.3 Public Identifiers, System Identifiers, and Catalog Files > +

> +

OASIS is the official > + home of the DocBook DTDs > + (see also DocBook Open > + Repository project at SourceForge) > +

Organization for the Advancement of Structured Information Standards > (OASIS)

> > --------------------------------------------------------------------- > 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