Using Catalog Entity Resolver for local DTDs

This is a collection of notes for configuring the Catalog Entity Resolver with your favourite XML tools (validating parsers and editors).

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.

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 the tools.

If you have any other configuration tips for a particular tool, then please send them to the forrest-dev mailing list.

The Forrest DTDs and supporting resources are in the Forrest distribution at main/webapp/resources/schema/

Usually all that is required is to direct your tool to the "catalog" supplied by Forrest at either: $FORREST_HOME/main/webapp/resources/schema/catalog.xcat (for XML Catalog) or $FORREST_HOME/main/webapp/resources/schema/catalog (for TR 9401 Catalog).

Operating system catalog

Some operating systems already provide a system-wide catalog that is used by many tools. This is usually located at /etc/xml/catalog or at /usr/share/sgml/catalog files.

For an XML Catalog, add this line:

<nextCatalog
catalog="/usr/local/svn/forrest/main/webapp/resources/schema/catalog.xcat"/>
        
        

For a TR 9401 Catalog, add this line:

CATALOG \
"/usr/local/svn/forrest/main/webapp/resources/schema/catalog"
        
        

Actually you probably do not want to touch that system catalog, so rather create your own catalog file in your home directory which refers to both the Forrest catalog and your system catalog.

xmllint validating parser

"xmllint" is part of the "libxml2" package. It is very fast and powerful, with are many facilities. It can validate whole directories of files at once. Set the SGML_CATALOG_FILES environment variable.

export SGML_CATALOG_FILES=$SGML_CATALOG_FILES:\
$FORREST_HOME/main/webapp/resources/schema/catalog
xmllint --valid --catalogs --noout mydoc.xml
        

Vim

The following .vimrc entries are useful:

au FileType xml set efm=%A%f:%l:\ %.%#error:\ %m,%-Z%p^,%-C%.%#
au FileType xml set makeprg=xmllint\ --noout\ --valid\ --catalogs\ %
        

See other notes about using Vim as XML editor.

Emacs

See nXML mode and FAQ.

onsgmls validating parser

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

SGMLDECL "/usr/share/sgml/xml.dcl"
CATALOG \
"/usr/local/svn/forrest/main/webapp/resources/schema/catalog"
        

Then point the parser at it:

onsgmls -c path/to/my-catalog -wall -wxml -s mydoc.xml
        

jEdit - Open Source programmer's text editor

Select the menu:
Utilities > Global Options > Plugins:XML > Catalogs
Select the "+" button, and use the "File System Browser"
to specify the TR9401 Catalog file:
"forrest/main/webapp/resources/schema/catalog"
        
        

On version 4.2. Select the menu:
Plugins > Plugins Options > Plugins:XML > Catalogs
Select the "+" button, and use the "File System Browser"
to specify the TR9401 Catalog file:
"forrest/main/webapp/resources/schema/catalog"
        
        

oXygen XML Editor

Select the menu:
Options > Preferences > XML Catalog
Specify the XML Catalog file:
"forrest/main/webapp/resources/schema/catalog.xcat"
        
        

xmlspy

Add the following entry to the file CustomCatalog.xml
(located in XMLSpy install directory):

<nextCatalog
catalog="file://localhost/C:/apache/forrest/main/webapp/
resources/schema/catalog.xcat"/>
        
        

XMLmind XML Editor (XXE)

XXE v2.5p2 or older

Select the menu:
Options > Options > Schema > Add File
Specify the XML Catalog file:
"forrest/main/webapp/resources/schema/catalog.xcat"
        
          

XXE v2.5p3+

XXE supports catalogs by automatic detection via configuration files. Download the XXE Forrest Config files from splike.com; this also add support for WYSIWYG editing of forrest documents. Note: This configuration suite has recently been added to the Forrest scratchpad.

Forrest and Cocoon use the Catalog Entity Resolver that is provided by the Apache XML Commons project. The resolver is packaged with the Forrest distribution at lib/core/xml-commons-resolver-x.y.jar

Other Forrest documentation has some notes about configuring the entity resolver for your own DTDs. See XML Validation.

Cocoon has extensive documentation about the entity resolver. See Entity resolution with catalogs.