Documenting XML DTDs

The power of TechWriter comes from its ability to leverage information from your XML schema. In this topic we will show you how to document XML DTDs by including comments directly within the DTD itself as an alternative to creating annotations within TechWriter. Comments can include simple text descriptions or richly formatted content depending on the comment model you wish to use.

Documenting Elements

To create element descriptions within a DTD, locate the element within the DTD using your favorite editor and place a comment using the following syntax directly above the element definition:

<!--  comment text -->

Here is a complete example of a DTD element definition that includes a description:

<!-- Name of the employee -->
<!ELEMENT EmployeeName %NameType; >

Documenting Attributes

There is currently no method for documenting attributes directly within the DTD. You will need to use TechWriter annotations to document your attributes.

Documenting Types

To create type descriptions within a DTD, locate the type entity within the DTD using your favorite editor and place a comment using the following syntax directly above the entity definition:

<!--  comment text -->

Here is a complete example of a DTD type definition that includes a description:

<!-- The name of a person -->
<!ENTITY % NameType "(FirstName, MiddleName, LastName)">

Formatting Options

In some instances, you may want to format your comments with multiple paragraphs, lists, links and other formatting options that are available when using TechWriter's Annotation editor. By using one of TechWriter's supported comment models, such as XHTML, you can apply formatting to the text using comment tags. In order to use comment tags you must select the proper comment model for your DTD from the Schema Settings dialog that is displayed when you add or edit a DTD for the project.