Home Forums General XMetaL Discussion Need an easy way to associate DTD and .ent files with XMetaL, working locally Reply To: Need an easy way to associate DTD and .ent files with XMetaL, working locally

Derek Read

Reply to: Need an easy way to associate DTD and .ent files with XMetaL, working locally

When you wish to associate a DTD with an XML document you specify a “Document type declaration” at the top, after the XML declaration. This is required for any XML document you wish to create that will be considered valid (in order to be considered valid the document must validate against a particular DTD and a parser needs to know where the DTD is in order to do that). Inside the declaration you should specify a PUBLIC ID, a SYSTEM ID or both.

You may wish to read the XML Recommendation here for information on this topic:

The most common method (and arguably the most compatible and flexible) is to specify both PUBLIC and SYSTEM ID, in which case the format is basically as follows:

In this case, if XMetaL Author locates a copy of “dtdname.dtd” in the same folder as the XML document (because no path has been specified) it will use that file. Failing that, it will check its catalog file for matches on PUBLIC or SYSTEM ID values. Upon finding a match it will then open the DTD located there. Failing that, the fallback is to check in the Rules folder, many of our clients simply create their Document type declaration as shown above and then place their DTD in the Rules folder. Software from other companies will function in different ways (they will not have the Rules folder for example) but will have similar look-up logic, so having both a PUBLIC and SYSTEM ID typically provides the most flexibility because most enterprise software will have some way to configure this look-up.

Note: In most cases, industry standard DTDs will specify the PUBLIC ID to use for a specific version of the DTD.

The ultimate fallback for XMetaL Author (if for whatever reason you cannot use one of the other default methods) is to override all these various look-up rules using script to force the product to use a particular DTD at a particular location. Most people do not need this capability but it is there and documented in the XMetaL Developer Programmers Guide.

I would also suggest reading the documentation in XMetaL Author's Help for these topics:

“DTDs and Schemas” and all subtopics, but specifically “Document type declarations”
“If XMetaL cannot find the DTD, Schema, or Rules file”

The following Help topic may also be useful in general and as a resource for finding other information: “Appendix A: XML basics”

The following topic explains the relationship between the DTD that is loaded and all other supporting files that make up the editing experience for documents based on that DTD: “XMetaL customizations”

For a working example you may wish to check these files related to the Journalist demo:

C:Program FilesXMetaL 6.0AuthorRulesjournalist.dtd
[code]C:Program FilesXMetaL 6.0AuthorSamplesCamerasCamerasInFocus.xml[/code] (complete sample document)
[code]C:Program FilesXMetaL 6.0AuthorTemplateJournalistArticle.xml[/code] (this file is loaded when you select File > New > Journalist {tab} > Article)

There are quite a few other files that make up the Journalist demo (forms, macros, styling, etc), but the ones above should show you how the DTD is located and how it can be declared in the XML file.

This file is the base catalog look-up file used for all DTDs (and contains entries for Journalist):
C:Program FilesXMetaL 6.0AuthorRulescatalog

Note that although you can create entries for ENT files in a catalog it is typically best practice to reference them directly from the DTD itself so that they properly resolve (which basically means using a relative path from the DTD to the ENT file). XMetaL Author loads the “main” DTD and will then attempt to resolve any files it references. Failing to do that it does perform a catalog look-up and then failing that it will prompt you to locate them manually. The journalist.dtd has an example of such an “external entity” declaration. Within the journalist.dtd search for the following text: table.ent. Most industry standard DTDs (if they are broken into multiple files) will include all the files and associate them by reference using this method. Examples of this include both DITA and DocBook.

If you are considering creating a customization for XMetaL Author to work with a specific DTD I would strongly encourage you to read the Customization Guide that comes with XMetaL Developer and that is also available here: http://na.justsystems.com/content-support-user-guides

The Customization Guide attempts to give an overview of what a customization is (in addition to the details it provides for the different parts). The Programmer's Guide may also be useful to look at but it is primarily a list of all the APIs that XMetaL Author (and XMAX) expose for customizing behaviors via script.