-
Notifications
You must be signed in to change notification settings - Fork 28
Style guidelines for the DITA specification
This page covers our practices for ensuring editorial consistency in the DITA specification. We improved consistency greatly in DITA 1.3 and hope to improve it further in DITA 2.0.
Use complete sentences (in short descriptions, when describing code samples, and elsewhere).
Revision values are controlled with a subject scheme map. For 1.3, the values in use are:
- "DITA1.2-errata" is used to mark up changes that have been reported to the TC and are considered errata in the 1.2 specification.
- "DITA1.3" is used to mark any substantive change made in 1.3, either due to cleanup or to changes made in response to proposals.
- "proposal-x" (where "x" is the proposal number) is used to mark up changes made in response to a specific proposal.
- "review-2" is used to mark significant changes made in response to review #2.
When using key words such as "MUST" or "SHOULD" in a normative context, write them in upper case, and mark them up as in the following: "The primary language of the map <term outputclass="RFC-2119 rev="terminology">SHOULD</term> ..."
Normative language is not needed when explaining the syntax of an attribute or element, or when describing how an element is used. Example, do not use "An image element MUST specify an href attribute, a keyref attribute, or both." Instead, use "An image element specifies an <xmlatt>href</xmlatt> attribute, a <xmlatt>keyref</xmlatt> attribute, or both."
XML elements should be marked up with <xmlelement>. Do not add extra brackets (this is done during publishing). Example: "Use the <xmlelement>shortdesc</xmlelement> to ..."
If an element name is used in the normal English context, it should not be marked up. Example - only mark the first instance of "topic" here: '"The element type topic is the base topic type from which all other topic types are specialized."'
XML attributes should be marked up with <xmlatt>. Do not add the @ symbol. Example: "The <xmlatt>href</xmlatt> attribute references ..."
Both elements and attributes should be marked anywhere they appear, apart from code samples (including titles, <dt>, and in normal text).
Sample inline markup, including attribute samples, should use <codeph>. Example: "Topics referenced with the attribute <codeph>toc="no"</codeph>..."
File names should be marked up with <filepath>. Example: "In this sample, <filepath>bats.ditamap</filepath> demonstrates..."
Inline, partial code samples must be marked up with <codeph>. These do not need to be complete; for example, a <codeph> element may contain a sample start tag, with no end tag.
Complete code samples must be marked up with <codeblock>. They must show a useful instance of the markup in question. Markup in the code block must be valid DITA XML; an author must be able to paste it into a DITA editor. This means that elements which start must also end, and required attributes / sub-elements must be present. Use two characters for each level of indentation.
Some samples start or end with "..." characters to indicate that the sample appears inside other markup. This is acceptable, though generally unnecessary. If "..." is used in the middle of a sample, either it must be used in a context where text is valid, or it must be placed inside comment tags: <!-- ... -->
If the example uses a large amount of required markup in order to highlight a single element, the <b> element may be used to highlight that element's start and end tag.
Authors or editors inserting <draft-comment> elements must use the @author and @time attributes. Draft comments will be deleted when they are resolved or no longer germane.
Complex examples belong in the Architectural Specification. The Language Reference topics should include a short example that illustrates the usage of the element. If the element has processing implications, the example should elucidate them.
Examples should be contained within <example> elements. If an entire topic is used for an example, the <title> should use the following format: "Example: X".
Example paragraphs within the Architectural Specification should:
- Begin with the phrase "For example,"
- Be marked with
outputclass="example".
Every <example> should set the ID attribute. In the language specification, for consistency, the first or only <example> always uses id="example". Additional examples in a language specification topic may use any valid ID.
Index term entries must only be in the prolog. Kris and Robert are planning to meet about developing a long-term plan for indexing; other TC members are welcome to participate.
Submaps must have <title> elements. If the <map> element has a @navtitle attribute, remove it.