Test your work
To make sure that the new DTD does all that it's supposed to, you want to create sample documents that conform to that DTD and then check whether DITA-aware software can read the DTD and the sample documents and do something useful with them without error messages.
The recipe documents that conformed to the standard DITA DTD were a step on the way to a specialized recipe DTD. Now that you have that specialized DTD, you can make copies of those documents that conform to the new DTD so you can properly test your new DTD.
The documents need a DOCTYPE declaration that points to the new DTD, like this:
<!DOCTYPE recipe PUBLIC "-//SNEE//DTD Recipe//EN" "recipe.dtd">
Listing 3. First sample content document revised to conform to recipe.dtd
<!DOCTYPE recipe PUBLIC "-//SNEE//DTD Recipe//EN" "recipe.dtd"> <recipe id="r1"> <dishname>Blueberry Pie</dishname> <shortdesc>Everyone will be <i>so</i> impressed when you pull it out of the oven!</shortdesc> <recipebody> <ingredients> <ul> <li><p>1 can blueberry pie filling</p></li> <li><p>2 pie crusts, available at supermarket</p></li> </ul> </ingredients> <steps> <step> <cmd>Pour the contents of the can over one of the pie crusts.</cmd> </step> <step> <cmd>Put the other crust on top of that. Press down around the edges of the top crust with a fork to mush it onto the outer edge of the bottom crust. Poke a few holes in the top crust with the fork to let steam escape while cooking.</cmd> </step> <step> <cmd>Cook according to the directions that came with the pie crusts.</cmd> </step> </steps> </recipebody> </recipe>
Listing 4. Second sample content document revised to conform to recipe.dtd
<!DOCTYPE recipe PUBLIC "-//SNEE//DTD Recipe//EN" "recipe.dtd"> <recipe id="r2"> <dishname>Corned beef and cabbage</dishname> <shortdesc>A simple meal to make on St. Patrick's Day.</shortdesc> <recipebody> <ingredients> <ul> <li><p>1 corned beef</p></li> <li><p>4 peeled cloves of garlic</p></li> <li><p>1 head of cabbage cut into 3" chunks</p></li> </ul> </ingredients> <steps> <step> <cmd>Rinse corned beef.</cmd> </step> <step> <cmd>Bring enough water to cover the corned beef (with a few inches left over) to a boil.</cmd> </step> <step> <cmd>Add the corned beef and garlic to the boiling water and cook for 30 minutes per pound of corned beef.</cmd> </step> <step> <cmd>Add the cabbage to the mixture fifteen minutes before the corned beef is done.</cmd> </step> <step> <cmd>Drain and serve with hot mustard.</cmd> </step> </steps> <result>Your mother would have put in the cabbage a lot sooner, but that turns it into a pasty mush, which is what makes a lot of people hate cabbage. </result> </recipebody> </recipe>
If you have many samples—and you really should—you'll find it quicker to create versions that conform to your topic specialization DTD with an XSLT stylesheet that does the renaming with template rules like this:
<xsl:template match="prereq"> <ingredients> <xsl:apply-templates select="@*|node()"/> </ingredients> </xsl:template>
Make sure that your revised documents validate against your new DTD. Again, xmllint is great for this.
The real beauty of DITA specialization is that if a DITA processor such as the
DITA Open Toolkit doesn't recognize elements names such as
ingredients, it checks to see what elements they are derived from (in this case,
prereq) to see how to treat them. When you tell the DITA Open Toolkit
to create XHTML from these recipes, it will then convert the
dishname element to an
h1 header at the top of the XHTML page, just as it would with a
title element. It will convert the
ingredients list into a bulleted list, even if it had never seen the
ingredients elements before.
Well, it should. This is the step where you find out. If not, review the DTD files and samples to make sure that all the pieces fit together properly as described in the earlier steps of this tutorial. (Sample versions of working DTD modules and the recipes from this article are available for download. See Download.)
For a really quick DITA Open Toolkit transformation, I prefer to invoke it from the command line instead of creating new ant files to specify all the details of the transformation. (For more information on this, see "Easy command line processing with the DITA Open Toolkit" in Resources.) To convert the file CornedBeefAndCabbage.xml to CornedBeefAndCabbage.html, enter this:
java -jar \dot\path\dost.jar /i:CornedBeefAndCabbage.xml /transtype:xhtml
This assumes that you have the DITA Open Toolkit set up properly. Replace \dot\path with the path to your Toolkit's dost.jar file. See the Toolkit installation instructions for information on which environment variables you must set for it to find everything it needs.