Using Catalog Entity Resolver for local DTDs
- General configuration notes
- Configuring specific tools
- Further information and resources
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.
General configuration notes
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).
Configuring specific tools
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:
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
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.
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"
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 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.
Further information and resources
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.