The first time you sign into developerWorks, a profile is created for you. Select information in your profile (name, country/region, and company) is displayed to the public and will accompany any content you post. You may update your IBM account at any time.

All information submitted is secure.

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerworks.

All information submitted is secure.

# DITA topic specialization

Analyze your content and build a specialized DTD

Bob DuCharme, a solutions architect at Innodata Isogen, was an XML "expert" when XML was a four-letter word. He's written four books and nearly one hundred online and print articles about information technology without using the word "functionality" in any of them. See http://www.snee.com/bob for more and www.snee.com/bobdc.blog for his weblog.

Summary:  Many resources are available to explain what Darwin Information Typing Architecture (DITA) topic specialization is and the syntax to implement it, but you still might wonder "I have some content that might be a candidate for topic specialization. What's next?" In this tutorial, walk through a series of steps to evaluate your content's suitability for different DITA topic types, specialize one of those types, and test your specialization using the DITA Open Toolkit.

Date:  26 Feb 2008
Level:  Intermediate PDF:  A4 and Letter (58 KB | 16 pages)Get Adobe® Reader®

Activity:  13543 views

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.

Step 8: Revise content samples to conform to specialized DTD

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:

  

You'll also want these documents to use the new element names—for example, ingredients instead of prereq. Listings 3 and 4 show the two sample documents revised to conform to the new DTD.

Listing 3. First sample content document revised to conform to recipe.dtd
  Blueberry Pie Everyone will be so impressed when you pull it out of the oven!
• 1 can blueberry pie filling

• 2 pie crusts, available at supermarket

Pour the contents of the can over one of the pie crusts. 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. Cook according to the directions that came with the pie crusts.


Listing 4. Second sample content document revised to conform to recipe.dtd
  Corned beef and cabbage A simple meal to make on St. Patrick's Day.
• 1 corned beef

• 4 peeled cloves of garlic

• 1 head of cabbage cut into 3" chunks

Rinse corned beef. Bring enough water to cover the corned beef (with a few inches left over) to a boil. Add the corned beef and garlic to the boiling water and cook for 30 minutes per pound of corned beef. Add the cabbage to the mixture fifteen minutes before the corned beef is done. Drain and serve with hot mustard. 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.


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:

  

Make sure that your revised documents validate against your new DTD. Again, xmllint is great for this.

Step 9: Test content samples with the DITA Open Toolkit

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 dishname and ingredients, it checks to see what elements they are derived from (in this case, title and 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 dishname and 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.

4 of 8

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=XML
ArticleID=290905
TutorialTitle=DITA topic specialization
publish-date=02262008
author1-email=bob@snee.com
author1-email-cc=dwxed@us.ibm.com