cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From m...@apache.org
Subject cvs commit: xml-cocoon2/xdocs catalog.xml
Date Mon, 03 Sep 2001 11:41:07 GMT
mman        01/09/03 04:41:07

  Modified:    webapp/resources/entities CatalogManager.properties
               xdocs    catalog.xml
  Log:
  patch from David Crossley <crossley@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


Mime
View raw message