Chapter 3. Document Type Shell Tutorial

Goal: Define a document type shell that omits domains you don't want and integrates a third-party domain you do want.

Most, if not all, production uses of DITA require the creation of document type shells. Fortunately, it's easy to do.

Document type shells serve to integrate vocabulary and constraint modules into a working DTD or XSD document that can be used to validate documents that should conform to the document type.

Often the only thing you need to do to configure your DITA environment is create document type shells, at least initially. For example, it is likely your writers do not need all the domains defined by the DITA standard and included in the OASIS-provied document type shells. You may also want to allow the nesting of different topic types or similar configurations that do not, themselves, require new specialization or constraint modules.

In a production DITA environment (meaning one where you will be doing real work as opposed to simply evaluating DITA technology) you should always create local shells even if you have no immediate need to impose constraints, adjust domain usage, or do specialization.

The reason for this requirement to create local document type shells is that as soon as you do need to do any of these things (and you will, sooner rather than later), you must have local document type shells. If you have not created local shells in advance, then any existing documents will have to be modified to point to the new shells you must now create. That could be a very disruptive change depending on how your documents are managed and which tools you are using to manage and author them.

Much better to set up your local shells first, get the configuration and deployment details worked out, and then you don't have to worry about future requirements that will require changes to the shells because you can modify the shells themselves without the need to modify existing documents (because the DTD or XSD pointers in the documents don't need to change in that case).

The overall process for creating a document type shell is:
  1. Find an existing shell that is close to what you want to end up with and copy it to a new location.
  2. Add or remove references to constraint or vocabulary modules as needed.
  3. Assign an appropriate public identifier or URN for the new shell.
  4. Deploy the new shell so that it is available to authors and processing components

The details of public ID or URN assignment and deployment depend on what specific tools you are using. In the case of the Open Toolkit, the best thing to do is to package the shell as part of a Toolkit plugin that contains an entity resolution catalog entry for the shell (which serves to assign the public identifier) and integrates the catalog into the Toolkit's master catalog (which serves to deploy the shell, making it available to anything that uses the Toolkit, including the Toolkit itself).

(There is an implicit message here, which is that tools that depend on the Toolkit tend to simplify the overall task of DITA system configuration and maintenance by limiting the number of system components that have to be created or updated to reflect a change to vocabulary components. This is one reason that OxygenXML, in particular, serves as an effective DITA development and authoring environment: it uses the Toolkit directly to access all DITA-related vocabulary components. This, coupled with Oxygen's built-in specialization awareness, means that you can deploy your local shells, constraint modules, and vocabulary modules to one place and all DITA editing and processing through Oxygen just works.)