At BMC we are dusting off some DITA specializations that we did about two years ago. We were using the non-OASIS release of DITA at the time, and our XML guru discovered that where the DITA dtd, mod, and entity files once said “IBM,” they now say “OASIS.” So all of our specializations had to be changed so that the entity declarations had //OASIS// instead of //IBM//.
But even with those changes, I still couldn’t get ant to build my DITA map files. No matter what relative path I put in my topic file, pointing to the DTD, nor where I would put the topic XML files relative to the DTD directory, ant refused to find the DTDs, giving me errors like “Cannot find \dtd\tBasicConcept.dtd” or “Cannot find C:\DITA-OT1.2.2\projects\dtd\tBasicConcept.dtd.” Originally, I thought that the problem was that ant looks relative from the ant basedir directory (it’s set to C:\DITA-OT1.2.2 on my machine) instead of relative from the topic file itself. However, I learned that public identifiers are your friends and you can avoid these relative path problems via the DITA catalog file in the DITA Open Toolkit.
Using Public IDs
I didn’t actually discover this helpful method of tracking DTD references. Our XML guru and information architect discovered that we needed to have entries in the catalog-dita.xml file in order for ant to find the specializations. That addition allows us to use public IDs instead of absolute or relative paths to the DTDs in our topic XML files. Whew!
So, in my topic files, I can refer to our specialized Concept topic, “tBasicConcept.dtd” (no relative or absolute file path) and as long as the catalog-dita.xml file has these entries for the publicIds, the DITA Open Toolkit finds the DTD and builds happily.
Here are examples of the catalog entries:
<public publicId="-//BMC//DTD DITA topic BMC Basic Concept//EN" uri="bmcproc/tBasicConcept.dtd"></public> <public publicId="-//BMC//ELEMENTS DITA topic BMC Basic Concept//EN" uri="bmcproc/tBasicConcept.mod"></public>
Here are examples of the referrer in the XML topic file:
<!DOCTYPE basicConcept PUBLIC "-//BMC//DTD DITA topic BMC Basic Concept//EN" "tBasicConcept.dtd">
Woops, the catalog can be overwritten
After a little searching on the dita-users Yahoo Group, I did find the following caveat for altering your catalog-dita.xml file directly. From Deborah Pickett in this message “Note: catalog-dita.xml is a generated file. It is overwritten when you run the “integrator” task. If you find your changes are being removed, put them in catalog-dita_template.xml instead.” I think you only run the integrator task when you are installing plug-ins, and so far we haven’t installed plug-ins in our Open Toolkit environment. So our modified catalog file is safe for now.
Separating your authoring environment from your processing environment
Now, if you were really paying attention to the catalog entries, you’d notice we’re using a “bmcproc” directory for our specializations. In our environment, we have two sets of specializations by design. One is a processing specialization, and that is the one I’m using for the ant builds. The other set of specializations is a “bmcauth” directory, and we have slightly stricter authoring standards in that set of specializations. But, we want the processing to work with the out-of-the-box transforms supplied by the Open Toolkit, so we designed more DITA-specific processing specializations.
An example of the difference between our authoring environment and the processing environment is that our BMC definition of a section is more restrictive to disallow a mixed PCDATA content model (which non-specialized DITA allows). This stricter definition prevents you from writing a section without tagged markup in our authoring environment. Where DITA allows: “#PCDATA | %basic.ph; | %basic.block; | %title; | %txt.incl;” BMC allows just: “%title;, (%basic.block; | %txt.incl;)+” and hopefully our content will be more semantically tagged because of it.