Subscribe to Dr. Macro's XML Rants

NOTE TO TOOL OWNERS: In this blog I will occasionally make statements about products that you will take exception to. My intent is to always be factual and accurate. If I have made a statement that you consider to be incorrect or innaccurate, please bring it to my attention and, once I have verified my error, I will post the appropriate correction.

And before you get too exercised, please read the post, date 9 Feb 2006, titled "All Tools Suck".

Tuesday, April 24, 2007

DITA Standard Practice: Always Make Local Shells

As I started doing serious work with DITA and in particular implementing specializations, it became clear to me that the first thing anyone using DITA should do is make local copies of all the DITA-provided shell DTDs or schemas. This should just be automatic. [Note: I'm going to use the term "DTD" to mean "DTD or schema" from now on.]


DITA, like DocBook, is a generic standard designed specifically to allow controlled local configuration and extension. Anyone who uses DITA in any non-trivial way will need to do at least some configuration, if not specialization, before too long. It is the rare user of DITA who genuinely needs to use all of the topic types and domains reflected in the base DITA distribution. Even if you're not using any specializations you probably only need some of the domains DITA provides out of the box.

By "configuration" I mean adjusting the set of topic types and domains that are or are not used for a given document set. For example, if you're not documenting interactive software you probably have no use for the User Interface domain and would just as soon not have those element types available to authors. Turning off that domain for your authors is "configuration".

By "specialization" I mean new domains or topic types derived from the base DITA-defined types (see my specialization tutorial for a deeper discussion). Even if you don't develop your own specializations, it is likely that you will use specializations developed by others. This will be increasingly likely as the DITA community begins to develop more and more special-purpose specializations--this is one of the really cool things about DITA--it enables and rewards the creation of "plug-ins" that are relatively easy to create, distribute, and integrate with the base DITA document types and supporting infrastructure.

In order to do either configuration or use specializations you must create local shell DTDs that reflect the local configuration or integrate the specializations.

Since you're going to do it sooner or later, you might as well start your DITA life there and be prepared. Eat the (minor) pain up front of configuring your local environment to use your local shells and then you're set to go.

If you set up your local shells first, then as you add new DITA-aware tools to your system, you can simply configure them to use your shells from the get-go, rather than building a system of tools and a set of documents that then have to all be reconfigured later when you finally do implement local shells (or worse, you discover that your system has become such a lava flow that you can't reconfigure them meaning that you can't do any configuration or use new specializations because the cost of reconfiguration would be too high or too risky).

NOTE: when you create local shells you must give them unique global identifiers (URIs or PUBLIC IDs). You must not refer to them by the DITA-defined URIs or PUBLIC IDs. Local shells are just that, local. You create them, you own them, you name them. You should consider the DITA-defined shells and attendant module and entity files to be invariant, meaning that you should never ever modify them directly, but only use them by reference, configured using the DITA-defined configuration mechanisms (parameter entities for DTDs, named groups for schemas).

All DITA-capable tools should (dare I say "must"?) be capable of using local shells, otherwise they aren't DITA-capable, QED. Probably the biggest potential problem tool is FrameMaker, but then FrameMaker is something of a special case because it's not a true XML tool and it's design makes reconfiguration much more expensive than it is with any other XML editor you're likely to use. I'm sure it can be done but I wouldn't want to have to do it (of course, as systems integrator I might be asked to and of course I would do it but that doesn't mean I'd have to like it).

For example, I've just gone through the exercise of setting up Arbortext Editor 5.3 to support editing of heavily specialized topic types. Once you know what to do it's not too hard and is reasonably well documented in the online help. The basic process is:
  1. Put each shell DTD in its own directory, named the same as the DTD or schema file. This organization is at least suggested, if not required, by Arbortext, but it's pretty good general practice anyway (even though the base DITA distribution doesn't organize things this way, there's no reason it couldn't and I've suggested that maybe it should, just on general principles of neatness).
  2. Create an old-style (non-XML) OASIS entity catalog for mapping the URIs of your local shell DTDs to their local location. (Arbortext Editor 5.3 doesn't support XML-syntax catalogs.)
  3. For each topic or map type shell, copy the Arbortext-specific configuration and style files from the Arbortext-supplied DITA doctypes that are the closest match to your local shells. Rename as necessary per the Arbortext naming conventions.
  4. Edit the configuration files to reflect the details of your shells. This is stuff like setting the name used in the New file dialog, pointing to templates and samples, and so on. For specializations you'll need to account for new element types in the editor configuration, style sheets, and whatnot, if they require special handling.
  5. Update the Arbortext Editor catalog path to include your catalog so it can resolve the references to the DTDs.
That's it. I would expect other XML editors to require a similar process (I haven't tried setting up XMetal for these specializations yet so I don't know what its configuration details would be).

Note too that as long as you are putting your shells in your own directory structures, and not in the dtd/ directory of the DITA Open Toolkit (which you should never do), it doesn't matter what you call your shell DTDs. That is, there's no particular reason not to call your local configuration of the concept shell DTD "concept.dtd".

So if you are a new user of DITA (by which I mean somebody setting up the DITA environment for a defined set of users, not an individual author [unless you are a writing team of one, in which case you are performing both roles]) I strongly urge you to create your own local shell DTDs right now if you haven't done so already.



Blogger Unknown said...

Hi, Eliot

I really could not agree more!

A parallel example from the world of SVG. A colleauge is working with SVG, and everything seemed fine.

He downloaded a very popular DITA aware XML editor, and his svg files no longer opened!

He re-installed Adobe's SVG viewer, and everything is fine. Culprit: different versions of SVG dtd 1.1

As a newbie to 'all this', this aspect of XML publishing seems so unbelievaably fragile to the point of being wholly inexcusable!

Many thanks,
David J. B. Hollis
A&O Consultancy Ltd. & Sagentia UK

8:44 AM  
Blogger Unknown said...

Some solid, useful information here. However, I must take exception to your gratuitous shot at FrameMaker. The procedure for using local shells with FrameMaker is nearly identical to that for Arbortext, up until your fourth step (in which you edit the Arbortext configuration files).

Yes, FrameMaker can be more difficult to configure than Arbortext or XMetaL. However, when you are finished, there is no need to write any XSL-FO. This can be a big win for organizations that need customizable PDF output.

I'm also not sure where the "not a true XML tool" comment comes from. FrameMaker, Arbortext, and XMetaL parse an XML document, present a screen representation, allow the user to modify that representation, and save the XML document back to the disk. FrameMaker certainly has its quirks, but so do Arbortext and XMetaL.

I don't want to engage in an authoring tool holy war. However, in some circles I feel that XML is The Standard, and Epic is The Editor. In fact, each of the "Big Three" XML editors (Epic, XMetaL, FrameMaker) offers appropriate use cases.

9:20 PM  
Blogger Unknown said...

To "configure" FrameMaker to use a only a subset of the DITA elements:
1. Open your FrameMaker DITA template.
2. In the Elements Catalog, click Options.
3. Select Customized List and click Edit.
4. Select the elements you want to see and move them to the Show list.
5. Click Set twice.
6. Save and close your template.

2:46 PM  

Post a Comment

<< Home