forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject cvs commit: xml-forrest/src/documentation/content/xdocs catalog.xml faq.xml
Date Thu, 15 Jan 2004 08:52:47 GMT
crossley    2004/01/15 00:52:47

  Modified:    src/documentation/content/xdocs faq.xml
  Added:       src/documentation/content/xdocs catalog.xml
  Log:
  Add new doc and FAQ for "Using Catalog Entity Resolver for local DTDs"
  to assist configuration of the editing tools.
  
  Revision  Changes    Path
  1.61      +15 -1     xml-forrest/src/documentation/content/xdocs/faq.xml
  
  Index: faq.xml
  ===================================================================
  RCS file: /home/cvs/xml-forrest/src/documentation/content/xdocs/faq.xml,v
  retrieving revision 1.60
  retrieving revision 1.61
  diff -u -r1.60 -r1.61
  --- faq.xml	10 Jan 2004 04:00:13 -0000	1.60
  +++ faq.xml	15 Jan 2004 08:52:47 -0000	1.61
  @@ -294,6 +294,20 @@
         </answer>
       </faq>
   
  +    <faq id="catalog">
  +      <question>
  +        How do i configure my favourite XML editor or parser to find the
  +        local Forrest DTDs?
  +      </question>
  +      <answer>
  +        <p>
  +          Notes are provided for various tools at
  +          <link href="catalog.html">Using Catalog Entity Resolver for
  +          local DTDs</link>.
  +        </p>
  +      </answer>
  +    </faq>
  +
       <faq id="xsp">
         <question>How do I enable <acronym title="eXtensible Server Pages">XSP</acronym>
processing?</question>
         <answer>
  
  
  
  1.1                  xml-forrest/src/documentation/content/xdocs/catalog.xml
  
  Index: catalog.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "http://apache.org/forrest/dtd/document-v12.dtd">
  <document>
    <header>
      <title>Using Catalog Entity Resolver for local DTDs</title>
      <authors>
        <person name="David Crossley" email="crossley@apache.org"/>
      </authors>
    </header>
    <body>
      <section id="overview">
        <title>Overview</title>
        <p>
          This is a collection of notes for configuring the Catalog Entity
          Resolver with your favourite XML tools (validating parsers and
          editors).
        </p>
        <p>
          All XML documents declare their ruleset - the Document Type Definition
          (DTD). When Forrest processes the documents it uses the Resolver to
          find Forrest's local copies of the DTDs, rather than trundling out
          onto the network.
        </p>
        <p>
          Many Java-based XML tools already have an entity resolver, probably
          the same one that Forrest uses. Many non-Java tools also have an
          entity resolver. To use these tools with documents based on the
          Forrest DTDs, you need to configure them.
        </p>
        <note>
          The information provided here is not intended to endorse any
          particular tool.
        </note>
        <p>
          If you have any other configuration tips for a particular tool, then
          please send them to the forrest-dev mailing list.
        </p>
      </section>
  
      <section id="config">
        <title>General configuration notes</title>
        <p>
          The Forrest DTDs and supporting resources are in the Forrest
          distribution at <code>src/core/context/resources/schema/</code>
        </p>
        <p>
          Usually all that is required is to direct your tool to the "catalog"
          supplied by Forrest at
          <code>$FORREST/src/core/context/resources/schema/catalog.xcat</code>
          (for XML Catalog) or
          <code>$FORREST/src/core/context/resources/schema/catalog</code>
          (for TR 9401 Catalog).
        </p>
      </section>
  
      <section id="tools">
        <title>Configuring specific tools</title>
  
        <section id="system">
          <title>Operating system catalog</title>
          <p>
            Some operating systems already provide a system-wide catalog that
            is used by many tools. This is usually located at
            <code>/etc/xml/catalog</code> or at
            <code>/usr/share/sgml/catalog</code> files.
          </p>
          <p>
            For an XML Catalog, add this line:
          </p>
          <source><![CDATA[
  <nextCatalog
  catalog="/usr/local/cvs/xml-forrest/src/core/context/resources/schema/catalog.xcat"/>
          ]]></source>
          <p>
            For a TR 9401 Catalog, add this line:
          </p>
          <source><![CDATA[
  CATALOG \
  "/usr/local/cvs/xml-forrest/src/core/context/resources/schema/catalog"
          ]]></source>
          <p>
            Actually you probably do not want to touch that system catalog,
            so rather create your own catalog file in yor home directory
            which refers to both the Forrest catalog and your system catalog.
          </p>
        </section>
  
        <section id="xmllint">
          <title>xmllint validating parser</title>
          <p>
            "xmllint" is part of the "libxml2" package.
            Set the SGML_CATALOG_FILES environment variable.
          </p>
          <source>
  export SGML_CATALOG_FILES=$FORREST/src/core/context/resources/schema/catalog
  xmllint --valid --catalogs --noout mydoc.xml
          </source>
        </section>
  
        <section id="onsgmls">
          <title>onsgmls validating parser</title>
          <p>
            "onsgmls" is part of the "Open SP" package.
            You need to also tell it where to find an "SGML declaration".
            The easiest way is to create your own little "my-catalog" file,
            containing this:
          </p>
          <source>
  SGMLDECL "/usr/share/sgml/xml.dcl"
  CATALOG \
  "/usr/local/cvs/xml-forrest/src/core/context/resources/schema/catalog"
          </source>
          <p>
            Then point the parser at it:
          </p>
          <source>
  onsgmls -c path/to/my-catalog -wall -wxml -s mydoc.xml
          </source>
        </section>
  
      </section>
  
      <section id="info">
        <title>Further information and resources</title>
        <p>
          Forrest and Cocoon use the
          <link href="http://xml.apache.org/commons/components/resolver/">Catalog
          Entity Resolver</link>
          that is provided by the
          <link href="http://xml.apache.org/commons/">Apache XML Commons</link>
          project. The resolver is packaged with the Forrest distribution at
          <code>lib/core/xml-commons-resolver-x.y.jar</code>
        </p>
        <p>
          Other Forrest documentation has some notes about configuring the
          entity resolver for your own DTDs. See
          <link href="site:validation">XML Validation</link>.
        </p>
        <p>
          Cocoon has extensive documentation about the entity resolver. See
          <link href="ext:cocoon/catalogs">Entity resolution with catalogs</link>.
        </p>
      </section>
  </body>
  </document>
  
  
  

Mime
View raw message