Tips and techniques

How can I combine several topics into a single document?

The DITA design has a unified content reuse mechanism by which an element can replace itself with the content of a like element elsewhere, either in the current topic or in a separate topic that shares the same content models. The distinction between reusable content and reusing content, often a problem for authors trying to use file and text entities, disappears: Any element with an ID, in any DITA topic, is reusable by conref.

DITA's conref "transclusion" mechanism is similar to the SGML conref mechanism, which uses an empty element as a reference to a complete element elsewhere. However, DITA requires that at least a minimal content model for the referencing element be present, and performs checks during processing to ensure that the replacement element is valid in its new context. This mechanism goes beyond standard XInclude, in that content can be incorporated only when it is equivalent: If there is a mismatch between the reusing and reused element types, the conref is not resolved. It also goes beyond standard entity reuse, in that it allows the reused content to be in a valid XML file with a DTD. The net result is that reused content gets validated at authoring time, rather than at reuse time, catching problems at their source.

Content referencing can be used at any scope of elements in a DITA document, from a keyword phrase that contains only PCDATA to a whole topic with other nested topics. Conref can cross file boundaries, using the same syntax as that of the href attribute on the xref element. If your authoring DTD allows topic nesting, you can create a set of minimal child topics and then use their conref attributes to pull in content from fully populated topics in other files.

What if my information doesn't break down into topics?

Most information can be broken down into topics (headings and content). However, if your information requires a more seamless flow of information across topic boundaries, don't use this architecture.

When should I specialize?

Create specialized topics when you have a restrictive category of topics that you want to keep consistent and that your users want to distinguish from other categories. Create specialized domains when you have a set of elements that you want available across several of your topic types. Be sure to specialize from the correct base: For example, categories of reference topics should specialize <reference>, categories of tasks should specialize <task>, and domain types should always specialize either <topic> or another domain type. If you need to allow more content structures than the base types allow, you can specialize directly from topic, or form your own base type. However, the lower down in the hierarchy that you can specialize, the better; you can then take advantage of any transforms or processes that have been developed for the more general categories that you specialize from.

How do I specialize?

You need to identify the differences between your new type of information and the more general type that you are specializing from. After you have identified the differences, you create a DTD file to declare the new elements that you require. Create another module to declare a set of mapping attributes for the new elements that point to the generic element types that they specialize. Then add import statements in the DTD file to bring in the mapping module and any ancestor modules. Finally, add a line that redefines the information types entity to include your new type. You now have a customized DTD.

When you specialize a domain, you need to first determine what elements must be specialized for the domain. Then you write an entity declaration file to list the specialized elements, along with their topic types and domain types. Next, you create a file where you define both the elements that are introduced for the domain and the specialization hierarchy. Finally, you write the shell DTD to combine the domain with topics and other domains.

• Specializing topic types in DITA
• Specializing domains in DITA

How do I extend specialization-aware transforms?

The method for extending specialization-aware transforms is described in more detail in the document, Specializing topic types in DITA.

Do I see HTML-like elements in the DITA materials?

Yes. Many writers have had at least some experience with HTML as a markup language. The base DITA declarations (DTD and XML Schema) incorporate a number of familiar, general HTML element names. Through specialization, these can always be extended into more specific forms. Generally, XSLT-based transformations from well-formed XHTML into DITA provides faster and more reliable migrations from HTML than copy/paste, although a skilled writer might be able to do so for small portions of content.

How was this FAQ produced?

This FAQ is a best-practice example of a rather direct use of DITA for nesting and aggregating topics into an information deliverable.

Each question and answer was developed as an individual DITA concept in the expectation that the concept information type may be further specialized later as a question/answer (or problem/resolution) information type. Sets of related issues were collected as child concepts of an overview concept for each category, with each category saved as a file. A dita map referenced each of these files under an introductory concept for the overall collection of categories.

The dita map was processing using the DITA Open Toolkit available from http://dita-ot.sourceforge.net// .