Normative statements in DITA 1.3

I ran a quick and dirty script over a monolithic HTML representation of the 1.3 spec and generated the following. It's the complete list of RFC-2119-tagged statements, and the topics in which they appear. With today's discussion about conformance, I thought it might be useful.

Chris

2.1.1: DITA terminology and notation

An XML document that conforms to the requirements of this specification. A DITA document MUST have as its root element one of the following elements: <map> or a specialization of the <map> element <topic> or a specialization of the <topic> element <dita>, which cannot be specialized, but which allows documents with multiple sibling topics

2.1.2: Basic concepts

DITA maps are documents that organize topics and other resources into structured collections of information. DITA maps specify hierarchy and the relationships among the topics; they also provide the contexts in which keys are defined and resolved. DITA maps SHOULD have .ditamap as the file extension. See DITA maps for more information.

2.1.3: File extensions

Files that contain DITA content SHOULD use the following file extensions:

2.2.2.1: Definition of DITA maps

DITA maps are documents that organize topics and other resources into structured collections of information. DITA maps specify hierarchy and the relationships among the topics; they also provide the contexts in which keys are defined and resolved. DITA maps SHOULD have .ditamap as the file extension.

2.2.2.4: DITA map attributes

Specifies whether the default rules for the cascading of metadata attributes in a DITA map apply. In addition to the following specified values, processors also MAY define additional values. cascade="merge" The metadata attributes cascade; the values of the metadata attributes are additive. This is the processing default for the @cascade attribute and was the only defined behavior for DITA 1.2 and earlier. cascade="nomerge" The metadata attributes cascade; however, they are not additive for <topicref> elements that specify a different value for a specific metadata attribute. If the cascading value for an attribute is already merged based on multiple ancestor elements, that merged value continues to cascade until a new value is encountered (that is, setting cascade="nomerge" does not undo merging that took place on ancestors). For more information, see Example: How the @cascade attribute functions.

2.2.3: Subject scheme maps and their usage

A DITA map can reference a subject scheme map by using a <mapref> element. Processors also MAY provide parameters by which subject scheme maps are referenced.

2.2.3.2: Defining controlled values for attributes

Authoring tools SHOULD use these lists of controlled values to provide lists from which authors can select values when they specify attribute values.
Authoring tools MAY give an organization a list of readable labels, a hierarchy of values to simplify selection, and a shared definition of the value.
An editor MAY support accessing and displaying the content of the subject definition resource in order to provide users with a detailed explanation of the subject.
Tools MAY produce a help file, PDF, or other readable catalog to help authors better understand the controlled values.

2.2.3.3: Binding controlled values to an attribute

If an enumeration is bound, processors SHOULD validate attribute values against the controlled values that are defined in the subject scheme map. For authoring tools, this validation prevents users from entering misspelled or undefined values. Recovery from validation errors is implementation specific.

2.2.3.4: Processing controlled attribute values

Processors SHOULD be aware of the hierarchies of attribute values that are defined in subject scheme maps for purposes of filtering, flagging, or other metadata-based categorization.
Processors SHOULD validate that the values of attributes that are bound to controlled values contain only valid values from those sets. (The list of controlled values is not validated by basic XML parsers.) If the controlled values are part of a named key scope, the scope name is ignored for the purpose of validating the controlled values.
Processors SHOULD check that all values listed for an attribute in a DITAVAL file are bound to the attribute by the subject scheme before filtering or flagging. If a processor encounters values that are not included in the subject scheme, it SHOULD issue a warning.

2.2.4.2.3: Architectural attributes

This attribute identifies the specialization hierarchy for the element type. Every DITA element (except the <dita> element that is used as the root of a ditabase document) MUST declare a @class attribute.
This attribute identifies the domain modules (and optionally the structural modules) that are used in a map or topic. Each module also declares its module dependencies. The root element of every topic and map MUST declare a @domains attribute.
This attribute identifies the version of the DITA architecture that is used by the XML grammar. The root element of every topic and map MUST declare a @DITAArchVersion attribute. The attribute is declared in a DITA namespace to allow namespace-sensitive tools to detect DITA markup.

2.2.4.3: Metadata in maps and topics

A map can override or supplement everything about a topic except its primary title and body content. All the metadata elements that are available in a topic also are available in a map. In addition, a map can provide alternate titles and a short description. The alternate titles can override their equivalent titles in the topic. The short description in the map MAY override the short description in the topic if the <topicref> element specifies a @copy-to attribute.

2.2.4.4: Cascading of metadata attributes in a DITA map

Implementers MAY define their own custom, implementation-specific tokens. To avoid name conflicts between implementations or with future additions to the standard, implementation-specific tokens SHOULDconsist of a prefix that gives the name or an abbreviation for the implementation followed by a colon followed by the token or method name.
The predefined values for the @cascade attribute MUST precede any implementation-specific tokens, for example, cascade="merge appToken:audience".
When determining the value of an attribute, processors MUST evaluate each attribute on each individual element in a specific order; this order is specified in the following list. Applications MUST continue through the list until a value is established or until the end of the list is reached (at which point no value is established for the attribute). In essence, the list provides instructions on how processors can construct a map where all attribute values are set and all cascading is complete.
For example, in the case of <topicref toc="yes">, applications MUST stop at item 2 in the list; a value is specified for @toc in the document instance, so @toc values from containing elements will not cascade to that specific <topicref> element. The toc="yes" setting on that <topicref> element will cascade to contained elements, provided those elements reach item 5 below when evaluating the @toc attribute.
For attributes within a map, the following processing order MUST occur:
The processing-supplied default values do not cascade to other maps. For example, most processors will supply a default value of toc="yes" when no @toc attribute is specified. However, a processor-supplied default of toc="yes" MUST not override a value of toc="no" that is set on a referenced map. If the toc="yes" value is explicitly specified, is given as a default through a DTD, XSD, RNG, or controlled values file, or cascades from a containing element in the map, it MUST override a toc="no" setting on the referenced map. See Map-to-map cascading behaviors for more details.

2.2.4.5: Reconciling topic and map metadata elements

Processors MAY or MAY NOT implement this behavior.

2.2.4.6.3: Cascading of roles from map to map

Alternatively, the <mapref> element in the mapgroup domain is a convenience element; the top-level <topicref> elements in the map referenced by a <mapref> element MUST NOT be processed as if they are <mapref> elements. The @class attribute from the <mapref> element ("+ map/topicref mapgroup-d/mapref ") does not cascade to the referenced map.
In some cases, preserving the role of the referencing element might result in out-of-context content. For example, a <chapter> element that references a bookmap might pull in <part> elements that contain nested <chapter> elements. Treating the <part> element as a <chapter> will result in a chapter that nests other chapters, which is not valid in bookmap and might not be understandable by processors. The result is implementation specific; processors MAY choose to treat this as an error, issue a warning, or simply assign new roles to the problematic elements.
The <part> element is processed as it were a chapter element. Nested <chapter> elements might not be understandable by processors; applications MAY recover as described above.

2.3.1: ID attribute

Within a map document, the values of the @id attributes for all elements SHOULD be unique. When two elements within a map have the same value for the @id attribute, processors MUST resolve references to that ID to the first element with the given ID value in document order.

2.3.3: URI-based (direct) addressing

For DITA resources, fragment identifiers can be used with the URI to address individual elements. The fragment identifier is the part of the URI that starts with a number sign (#), for example, #topicid/elementid. URI references also can include a query component that is introduced with a question mark (?). DITA processors MAY ignore queries on URI references to DITA resources. URI references that address components in the same document MAY consist of just the fragment identifier.

2.3.4.6: Processing key references

If both @keyref and @href attributes are specified on an element, the @href value MUST be used as a fallback address when the key name is undefined. If both @conkeyref and @conref attributes are specified on an element, the @conref value MUST be used as a fallback address when the key name is undefined.
The effective key definitions for a key space might be affected by conditional processing (filtering). Processors SHOULD perform conditional processing before determining the effective key definitions. However, processors might determine effective key definitions before filtering. Consequently, different processors might produce different effective bindings for the same map when there are key definitions that might be filtered out based on their filtering attributes.
If a topic that contains key references is reused in multiple key scopes within a given root map such that its references resolve differently in each use context, processors MUST produce multiple copies of the source topic in resolved output for each distinct set of effective key definitions that are referenced by the topic. In such cases, authors can use the @copy-to attribute to specify different source URIs for each reference to a topic.
If a referencing element contains a key reference with an undefined key, it is processed as if there were no key reference, and the value of the @href attribute is used as the reference. If the @href attribute is not specified, the element is not treated as a navigation link. If it is an error for the element to be empty, an implementation MAY give an error message; it also MAY recover from this error condition by leaving the key reference element empty.

2.3.4.8: Processing key references on <topicref> elements

The effective resource bound to the <topicref> element is determined by resolving all intermediate key references. Each key reference is resolved either to a resource addressed directly by URI reference in an @href attribute, or to no resource. Processors MAY impose reasonable limits on the number of intermediate key references that they will resolve. Processors SHOULD support at least three levels of key references.

2.3.4.9: Processing key references to generate text or link text

When the effective content for a key reference element results in invalid elements, those elements SHOULD be generalized to produce a valid result. For example, <linktext> in the key definition might use a domain specialization of <keyword> that is not valid in the key reference context, in which case the specialized element should be generalized to <keyword>. If the generalized content is also not valid, a text equivalent should be used instead. For example, <linktext> might include <ph> or a specialized <ph> in the key definition, but neither of those are valid as the effective content for a <keyword>. In that case, the text content of the <ph> should be used.

2.4.2.2: Processing conrefs

Except where allowed by weak constraints, a conref processor MUST NOT permit resolution of a reuse relationship that could be rendered invalid under the rules of either the reused or reusing content.
In both cases, processors resolving conrefs SHOULD tolerate specializations of valid elements and generalize elements in the pushed or pulled content fragment as needed for the resolving context.

2.4.2.3: Processing attributes when resolving conrefs

The token -dita-use-conref-target is defined by the specification to enable easier use of @conref on elements with required attributes. The only time the resolved element would include an attribute whose specified value is "-dita-use-conref-target" is when the referenced element had that attribute specified with the "-dita-use-conref-target" value and the referencing element either had no specification for that attribute or had it also specified with the "-dita-use-conref-target" value. If the final resolved element (after the complete resolution of any conref chain, as explained below) has an attribute with the "-dita-use-conref-target" value, that element MUST be treated as equivalent to having that attribute unspecified.

2.4.2.4: Processing xrefs and conrefs within a conref

When the address is a direct URI reference of any form other than a same-topic fragment identifier, processors MUST resolve it relative to the source document that contains the original URI reference.
When the address is a same-topic fragment identifier, processors MUST resolve it relative to the location of the content reference (referencing context).
When the address is a key reference, processors MUST resolve it relative to the location of the content reference (referencing context).

2.4.3: Conditional processing (profiling)

Processors SHOULD be able to perform filtering and flagging using the attributes listed above. The @props attribute can be specialized to create new attributes, and processors SHOULD be able to perform conditional processing on specializations of @props.

2.4.4.1: Overview of branch filtering

In addition to filtering, applications MAY support flagging at the branch level based on conditions that are specified in referenced DITAVAL documents.

2.4.4.4: Branch filtering: Impact on resource and key names

It is an error if <ditavalref>-driven branch cloning results in multiple copies of a topic that have the same resolved name. Processors SHOULD report an error in such cases. Processors MAY recover by using an alternate naming scheme for the conflicting topics.
In rare cases, a single topic might appear in different branches that set different conditions, yet still produce the same result. For example, a topic might appear in both the admin and novice copies of a branch but not contain content that is tailored to either audience; in that case, the filtered copies would match. A processor MAY consider this form of equivalence when determining if two references to the same resource should be reported as an error.

2.4.4.5: Branch filtering: Implications of processing order

Because the branch filtering process can result in new or renamed keys, key scopes, or URIs, the full effects of the branch filtering process MUST be calculated by processors before they construct the effective map and key scope structure.

2.4.5.1: Using the @chunk attribute

When specified on a <topicref> that contains a title but no target, this indicates that processors MUST generate a title-only topic in the rendered result, along with any topics referenced by child <topicref> elements of this <topicref>. The rendition address of the generated topic is determined as defined for the @copy-to attribute. If the @copy-to attribute is not specified and the <topicref> has no @id attribute, the address of the generated topic is not required to be predictable or consistent across rendition instances.
Some tokens or combinations of tokens might not be appropriate for all output types. When unsupported or conflicting tokens are encountered during output processing, processors SHOULD produce warning or error messages. Recovery from such conflicts or other errors is implementation dependent.
If an entire map is used to generate a single chunk (by placing to-content on the <map> element), the resource name SHOULD be taken from the resource name of the map.
If the @copy-to attribute is specified, the resource name MUST taken from the @copy-to attribute.
If the @copy-to attribute is not specified and one or more keys are specified on the <topicref>, the resource name SHOULD be constructed using one of the keys.
If @copy-to and @keys are not specified and the by-topic policy is in effect, the resource name SHOULD be taken from the @id attribute of the topic.
If @copy-to and @keys are not specified and the by-document policy is in effect, the resource name SHOULD be taken from the resource name of the referenced document.
When following these steps results in resource name clashes, processors MAY recover by generating alternate resource identifiers. For example, when two chunked topics use the same @id attribute, a processor could recover by combining the original resource name with the @id value instead of using only the @id value.
Implementers MAY define their own custom, implementation-specific tokens. To avoid name conflicts between implementations or with future additions to the standard, implementation-specific tokens SHOULDconsist of a prefix that gives the name or an abbreviation for the implementation followed by a colon followed by the token or method name.

2.4.6.1: The @xml:lang attribute

The @xml:lang attribute SHOULD be explicitly set on the root element of each map and topic.
Setting the @xml:lang attribute in the DITA source ensures that processors handle content in a language- and locale-appropriate way. If the @xml:lang attribute is not set, processors assume a default value which might not be appropriate for the DITA content. When the @xml:lang attribute is specified for a document, DITA processors MUST use the specified value to determine the language of the document.
If the root element of a map or a top-level topic has no value for the@xml:lang attribute , a processor SHOULD assume a default value. The default value of the processor can be either fixed, configurable, or derived from the content itself, such as the @xml:lang attribute on the root map.
When a DITA topic contains more than one language, set the @xml:lang attribute on the highest-level element to specify the primary language and locale that applies to the topic. If part of a topic is written in a different language, authors should ensure that the part is enclosed in an element with the @xml:lang attribute set appropriately. This method of overriding the default document language applies to both block and inline elements that use the alternate language. Processors SHOULD style each element in a way that is appropriate for its language as identified by the @xml:lang attribute.
The primary language for the map SHOULD be set on the <map> element. The specified language remains in effect for all child <topicref> elements, unless a child specifies a different value for the @xml:lang attribute.
When a @conref or @conkeyref attribute is used to include content from one element into another, the processor MUST use the effective value of the @xml:lang attribute from the referenced element, that is, the element that contains the content. If the referenced element does not have an explicit value for the @xml:lang attribute, the processor SHOULD default to using the same value that is used for topics that do not set the @xml:lang attribute.

2.4.6.2: The @dir attribute

Directionality is either explicitly specified via the @xml:lang attribute in combination with the @dir attribute on the highest level element (topic or derived peer for topics, map for ditamaps) or assumed by the processing application. If used, the @dir attribute SHOULD be specified on the highest level element in the topic or document element of the map.
Applications that process DITA documents, whether at the authoring, translation, publishing, or any other stage, SHOULD fully support the Unicode bidirectional algorithm to correctly implement the script and directionality for each language that is used in the document.
Applications SHOULD ensure that the root element in every topic document and the root element in the root map has values for the @dir and @xml:lang attributes.

2.4.7: Processing documents with different values of the @domains attribute

When copying content from one DITA document to another, processors SHOULD determine if the data being copied (the copy source) requires modules that are not required by the document into which the data is to be copied (the copy target). Such a copy operation is always safe if the copy source requires a subset of the modules that are required by the copy target. Such a copy is unsafe if the copy source requires modules that are not required by the copy target.
When a copy operation is unsafe, processors MAY compare the copy source to the copy target to determine if the copy source satisfies the constraints of the copy target. If the copy source meets the copy target constraints, the copy operation can proceed. Processors SHOULD issue a warning that the copy was allowed but the constraints are not compatible. If the copy source does not meet the constraints of the copy target, processors MAY apply generalization until the generalized result either satisfies the copy target constraints or no further generalization can be performed. If the copy operation can be performed following generalization, the processor SHOULD issue a warning that the constraints are not compatible and generalization had to be performed in order to complete the copy operation.

2.4.8: Sorting

Each element to be sorted must have some inherent text on which it will be sorted. This text is the base sort phrase for the element. For elements that have titles, the base sort phrase usually is the content of the <title> element. For elements that do not have titles, the base sort phrase might be literal content in the DITA source, or it might be generated or constructed based on the semantics of the element involved; for example, it could be constructed from various attribute or metadata values. Processors that perform sorting SHOULD explicitly document how the base sort phrase is determined for a given element.
When a <sort-as> element is specified, processors that sort the containing element MUST construct the effective sort phrase by prepending the content of the <sort-as> element to the base sort phrase. This ensures that two items with the same <sort-as> element but different base sort phrases will sort in the appropriate order.

2.5.2.2: Rules for document-type shells

While the DITA specification only defines coding requirements for DTD, RELAX NG, and XML Schema documents, conforming DITA documents MAY use other document-type constraint languages, such as Schematron.
With two exceptions, a document-type shell MUST NOT directly define element or attribute types; it only includes and configures vocabulary and constraint modules. The exceptions to this rule are the following:
Document type shells that are not provided by OASIS MUST have a unique public identifier, if public identifiers are used.
Document type shells that are not provided by OASIS MUST NOT indicate OASIS as the owner; the public identifier or URN for such document-type shells SHOULD reflect the owner or creator of the document-type shell.

2.5.3.3: Vocabulary modules

Structural modules based on topic MAY define additional topic types that are then allowed to occur as subordinate topics within the top-level topic. However, such subordinate topic types MAY NOT be used as the root elements of conforming DITA documents. For example, a top-level topic type might require the use of subordinate topic types that would only ever be meaningful in the context of their containing type and thus would never be candidates for standalone authoring or aggregation using maps. In that case, the subordinate topic type can be declared in the module for the top-level topic type that uses it. However, in most cases, potential subordinate topics should be defined in their own vocabulary modules.
Domain elements intended for use in topics MUST ultimately be specialized from elements that are defined in the topic module. Domain elements intended for use in maps MUST ultimately be specialized from elements defined by or used in the map module. Maps share some element types with topics but no map-specific elements can be used within topics.

2.5.3.6: @class attribute rules and syntax

When the @class attribute is declared in an XML grammar, it MUST be declared with a default value. In order to support generalization round-tripping (generalizing specialized content into a generic form and then returning it to the specialized form) the default value MUST NOT be fixed. This allows a generalization process to overwrite the default values that are defined by a general document type with specialized values taken from the document being generalized.
A vocabulary module MUST NOT change the @class attribute for elements that it does not specialize, but simply reuses by reference from more generic levels. For example, if <task>, <bctask>, and <guitask> use the <p> element without specializing it, they MUST NOT declare mappings for it.
Authors SHOULD NOT modify the @class attribute.

2.5.3.7: @domains attribute rules and syntax

Each domain and constraint module MUST provide a value for use by the @domains attribute. Each structural vocabulary module SHOULD provide a value for use by the @domains attribute, and it MUST do so when it has a dependency on elements from any module that is not part of its specialization ancestry.
Structural modules can directly reference or specialize elements from modules that are outside of their specialization ancestry. They also can define specialized elements that reference specialized attributes. In these cases the structural module has a dependency on the non-ancestor module, and the structural module contribution to the value of the @domains attribute MUST include the names of each dependent, non-ancestor module.

2.5.4.1: Overview of generalization

When generalizing for migration, the @class attribute and @domains attribute should be absent from the generalized instance document, so that the default values in the document-type shell are used. When generalizing for round-tripping, the @class attribute and @domains attribute SHOULD retain the original specialized values in the generalized instance document.

2.5.4.3: Processor expectations when generalizing elements

A generalization processor SHOULD be able to handle cases where it is given:
When renaming elements during round-trip generalization, the generalization processor SHOULD preserve the values of all attributes. When renaming elements during one-way or migration generalization, the process SHOULD preserve the values of all attributes except the @class and @domains attribute, both of which should be supplied by the target document type.

2.5.4.4: Attribute generalization

DITA provides a syntax to generalize attributes that have been specialized from the @props or @base attribute. Specialization-aware processors SHOULD process both the specialized and generalized forms of an attribute as equivalent in their values.
A single element MUST NOT contain both generalized and specialized values for the same attribute. For example, the following <p> element provides two values for the @jobrole attribute, one in a generalized syntax and the other in a specialized syntax:

2.5.4.5: Generalization with cross-specialization dependencies

When possible, generalizing processes SHOULD detect invalid generalization target combinations and report them as errors.

2.5.5.2: Constraint rules

Each constraint that is integrated into a DITA document type MUST be declared in the @domains attribute for each structural type that is integrated into the document type. For DTDs, the contribution for the @domains attribute is specified in the constraint module file; for XSD and RELAX NG, the contribution to the @domains attribute is specified directly in the document type shell.

2.5.5.3: Constraints, processing, and interoperability

A constrained document type allows only a subset of the possible instances of the unconstrained document type. Thus, for a processor to determine whether a document instance is compatible with another document type, the document instance MUST declare any constraints on the document type.

2.5.5.4: Weak and strong constraints

Processors MAY perform constraint compatibility checking.
If processors perform constraint compatibility checking, they SHOULD enforce strict compatibility for strong constraints.
Processors MAY have an option for configuring whether all constraints are treated as strong constraints.

2.6.3.4: DTD: Coding requirements for structural modules

The last position in the content model defined for the root element of a topic type SHOULD be the topictype-info-types parameter entity. A document-type shell then can control how topics are allowed to nest for this specific topic type by redefining the topictype-info-types entity for each topic type. If default nesting rules reference the info-types parameter entity, a shell can efficiently create common nesting rules by redefining the info-types entity.

2.6.4.1: RELAX NG: Overview of coding requirements

RELAX NG grammars for DITA document-type shells, vocabulary modules, and constraint modules MAY do the following:
Include embedded Schematron rules or any other foreign vocabulary. Processors MAY ignore any foreign vocabularies within DITA grammars that are not in the http://relaxng.org/ns/compatibility/annotations/1.0 or http://dita.oasis-open.org/architecture/2005/ namespaces.
DITA practitioners can author DITA modules using one RELAX NG syntax, and then use tools to generate modules in the other syntax. The resulting RELAX NG modules are conforming if there is a one-to-one file correspondence. Conforming RELAX NG-based DITA modules MAY omit the annotations and foreign elements that are used in the OASIS grammar files to enable generation of other XML grammars, such as DTDs and XML Schema. When such annotations are used, conversion from one RELAX NG syntax to the other might lose the information, as processors are not required to process the annotations and information from foreign vocabularies.

2.6.4.4: RELAX NG: Coding requirements for structural modules

In the declaration of the root element of a topic type, the last position in the content model SHOULD be the topictype-info-types pattern. For example, the <concept> element places the pattern after <related-links>:<div> <a:documentation>LONG NAME: Concept</a:documentation> <define name="concept.content">  <optional> <ref name="related-links"/> </optional> <zeroOrMore> <ref name="concept-info-types"/> </zeroOrMore> </define> </div>

2.6.5.1: XML Schema: Overview and limitations of coding requirements

You MAY modify OASIS-provided XSD modules to refactor content models if required by your constraint. You SHOULD notify the DITA Technical Committee (TC) of your constraint requirements, so the TC can consider adding the required refactoring to the OASIS-provided XSDs.

2.6.5.6: XML Schema: Coding requirements for constraint modules

When constraining a list of elements provided by a domain, there must be a group that lists the subset of domain elements in a constraints module. The group name SHOULD be named "qualifier domain-c-tagname" where qualifier is a description for the constraint module, domain is the name of the domain, map, or topic being constrained, and tagname is the name of the extension element being restricted.

3.2.1.5: <navtitle>

When both a <navtitle> element and a @navtitle attribute are specified, the <navtitle> element SHOULD be used.

3.2.1.6: <shortdesc>

The content of the <shortdesc> element SHOULD be rendered as the initial paragraph of the topic.
When processors generate link previews that are based on the map context, they SHOULD use the content of the <shortdesc> that is located in the map rather than the <shortdesc> that is located in the DITA topic. However, processors SHOULD use the content of the <shortdesc> element in the DITA topic when they render the topic itself, unless the @copy-to attribute is specified on the topic reference to the element.

3.2.2.4: <desc>

Provides a description of the target; processors MAY choose to display this text as hover help for a link.

3.2.2.7: <dl>

Rendering of definition lists will vary by application and by display format. Processors MIGHT render the second example as follows.

3.2.2.11: <draft-comment>

Processing systems SHOULD provide a mechanism that causes the content of this element to be rendered in draft output only. By default, processors SHOULD strip them out to prevent publishing internal comments by mistake.

3.2.2.17: <image>

Indicates the vertical dimension for the resulting image display. If necessary, the image SHOULD be scaled to the specified size. The value of this attribute is a real number (expressed in decimal notation) optionally followed by a unit of measure from the set of pc, pt, px, in, cm, mm, em (picas, points, pixels, inches, centimeters, millimeters, and ems respectively). The default unit is px (pixels). Possible values include: "5", "5in", and "10.5cm". If a height value is specified and no width value is specified, the width SHOULD be scaled by the same factor as the height. If both a height value and width value are specified, implementations MAY ignore one of the two values when they are unable to scale to each direction using different factors.
Indicates the horizontal dimension for the resulting image display. If necessary, the image SHOULD be scaled to the specified size. The value of this attribute is a real number (expressed in decimal notation) optionally followed by a unit of measure from the set of pc, pt, px, in, cm, mm, em (picas, points, pixels, inches, centimeters, millimeters, and ems respectively). The default unit is px (pixels). Possible values include: "5", "5in", and "10.5cm". If a width value is specified and no height value is specified, the height SHOULD be scaled by the same factor as the width. If both a height value and width value are specified, implementations MAY ignore one of the two values when they are unable to scale to each direction using different factors.

3.2.2.25: <object>

Indicates the vertical dimension for the resulting object display. If necessary, the object is scaled to the specified size. The value of this attribute is a real number (expressed in decimal notation) optionally followed by a unit of measure from the set of pc, pt, px, in, cm, mm, em (picas, points, pixels, inches, centimeters, millimeters, and ems respectively). The default unit is px (pixels). Possible values include: "5", "5in", and "10.5cm". If a height value is specified and no width value is specified, the width will be scaled by the same factor as the height. If both a height value and width value are specified, implementations MAY ignore one of the two values when they are unable to scale to each direction using different factors.
Indicates the horizontal dimension for the resulting object display. If necessary, the object is scaled to the specified size. The value of this attribute is a real number (expressed in decimal notation) optionally followed by a unit of measure from the set of pc, pt, px, in, cm, mm, em (picas, points, pixels, inches, centimeters, millimeters, and ems respectively). The default unit is px (pixels). Possible values include: "5", "5in", and "10.5cm". If a width value is specified and no height value is specified, the height will be scaled by the same factor as the width. If both a height value and width value are specified, implementations MAY ignore one of the two values when they are unable to scale to each direction using different factors.

3.2.2.31: <q>

Authors should not add quote punctuation manually when using the <q> element. Processors that render the <q> element SHOULD add appropriate styling, such as locale-specific quotation marks.

3.2.4.2: <linklist>

The <linklist> element defines an author-arranged group of links. When rendering the links, processors SHOULD preserve the order of links specified within a <linklist> element.

3.3.1.10: <relcolspec>

Ignoring the headers for a moment, the <reltable> here would ordinarily define a two-way relationship between debug_login.dita and login_error1.dita. This will typically be expressed as a link from each to the other. An application MAY render the link with a language-appropriate heading such as "Related reference", indicating that the target of the link is a reference topic.

3.3.2.4: <topicgroup>

Beginning with DITA 1.2, you are able to specify a <navtitle> element within the <topicmeta> element inside of a <topicgroup>. The <topicgroup> element is meant as a non-titled grouping element, so adding a <navtitle> element to the <topicgroup> element has no defined purpose, and processors MUST ignore the title. Processors MAY issue a message when ignoring the title.

3.3.2.5: <topichead>

Beginning with DITA 1.2, the navtitle can be specified by using a <navtitle> element within the <topicmeta> element, so the <topichead> element no longer requires the @navtitle attribute. In order to ensure backward compatibility with earlier versions of DITA, the new <navtitle> element is not required. However, a <topichead> element must contain either a @navtitle attribute or a <topicmeta> element that contains a <navtitle> element. DITA processors SHOULD generate a warning if a navigation title is not specified.

3.3.2.7: <topicsetref>

For situations that do not support reusing a topic set as an independent unit, such as a rendered PDF, applications MAY resolve the <topicsetref> element as for other <topicset> (or <topicref>) elements that have the @format attribute set to "ditamap".

3.4.2.1: <indexterm>

It is an error if an <indexterm> containing no <indexterm> children contains both an <index-see> and an <index-see-also>. (Note: <index-see> and <index-see-also> elements within <indexterm> elements that do contain <indexterm> children are ignored.) In the case of this error condition, an implementation MAY give an error message, and might recover by treating all such <index-see> elements as <index-see-also> elements.

3.4.2.3: <index-see>

An implementation MAY give an error message when it encounters this condition, and MAY recover from this error condition by treating the <index-see> as an <index-see-also>.

3.4.2.5: <index-sort-as>

When an <index-sort-as> element is specified, processors that sort the containing index term MUST construct the effective sort phrase by prepending the content of the <index-sort-as> element to the textual content of its parent <indexterm> element. This ensures that two index entries with the same <index-sort-as> element but different base sort phrases will sort in the appropriate order, and will not merge into a single index entry.

3.5.1.3: <hazardsymbol>

Indicates the vertical dimension for the resulting image display. If necessary, the image SHOULD be scaled to the specified size. The value of this attribute is a real number (expressed in decimal notation) optionally followed by a unit of measure from the set of pc, pt, px, in, cm, mm, em (picas, points, pixels, inches, centimeters, millimeters, and ems respectively). The default unit is px (pixels). Possible values include: "5", "5in", and "10.5cm". If a height value is specified and no width value is specified, the width SHOULD be scaled by the same factor as the height. If both a height value and width value are specified, implementations MAY ignore one of the two values when they are unable to scale to each direction using different factors.
Indicates the horizontal dimension for the resulting image display. If necessary, the image SHOULD be scaled to the specified size. The value of this attribute is a real number (expressed in decimal notation) optionally followed by a unit of measure from the set of pc, pt, px, in, cm, mm, em (picas, points, pixels, inches, centimeters, millimeters, and ems respectively). The default unit is px (pixels). Possible values include: "5", "5in", and "10.5cm". If a width value is specified and no height value is specified, the height SHOULD be scaled by the same factor as the width. If both a height value and width value are specified, implementations MAY ignore one of the two values when they are unable to scale to each direction using different factors.

3.5.3.5: <sort-as>

Processors SHOULD expect to encounter <sort-as> elements in the above locations. Processors that sort SHOULD use the following precedence rules:
When a <sort-as> element is specified, processors that sort the containing element MUST construct the effective sort phrase by prepending the content of the <sort-as> element to the base sort phrase. This ensures that two items with the same <sort-as> element but different base sort phrases will sort in the appropriate order.

3.5.4.1: <ditavalref>

Processors MAY recover by using an alternate naming scheme for the conflicting copies.
Format of the target document, which MUST be a DITAVAL document. The default value for this element is "ditaval". See The @format attribute for more information.

3.7.4: <foreign>

Processors should attempt to display <foreign> content unless otherwise instructed. If the processor cannot render the content, it MAY issue a warning.

3.9.3: <prop>

A <prop> element with no @att attribute specified sets a default action for every <prop> element. It is an error to use more than one <prop> element with no attribute in a single document. Recovery from this error is implementation dependent; in such cases processors MAY provide an error or warning message.
A <prop> element with an @att attribute but no @val attribute sets a default action for that specific attribute or attribute group. For each specific attribute, it is an error to use more than one <prop> element with that attribute and no value in a single document. Recovery from this error is implementation dependent; in such cases processors MAY provide an error or warning message.
A <prop> element with an @att attribute and a @val attribute sets an action for that value within that attribute or attribute group. It is an error to use more than one <prop> element with the same attribute and value. Recovery from this error is implementation dependent; in such cases processors MAY provide an error or warning message.
If flag has been set, the color to use to flag text. Colors can be entered by name or code. Processors SHOULD support the color names listed under the heading "<color>" in http://www.w3.org/TR/2006/REC-xsl11-20061205/#datatype and for the 6 digit hex code form (#rrggbb, case insensitive). If flag has not been set, this attribute is ignored.
If flag has been set, the text styles to use for flagged text. This attribute can contain multiple space-delimited tokens. The following tokens SHOULD be processed by all DITAVAL processors:
In addition, processors might support other proprietary tokens for different types of styling. Such tokens SHOULD have a processor-specific prefix to identify them as proprietary. If a processor encounters an unsupported style token, it MAY issue a warning, and MAY render content flagged with such a style token using some default formatting.

3.9.4: <revprop>

It is an error to include more than one <revprop> element with the same @val attribute setting. Recovery from this error is implementation dependent; in such cases processors MAY provide an error or warning message.
If flag has been set, the color to use to flag text. Colors can be entered by name or code. Processors SHOULD support the color names listed under the heading "<color>" in http://www.w3.org/TR/2006/REC-xsl11-20061205/#datatype and for the 6 digit hex code form (#rrggbb, case insensitive). If flag has not been set, this attribute is ignored.
If flag has been set, the text styles to use for flagged text. This attribute can contain multiple space-delimited tokens. The following tokens SHOULD be processed by all DITAVAL processors:
In addition, processors might support other proprietary tokens for different types of styling. Such tokens SHOULD have a processor-specific prefix to identify them as proprietary. If a processor encounters an unsupported style token, it MAY issue a warning, and MAY render content flagged with such a style token using some default formatting.

3.10.2: Architectural attribute group

Indicates the specialized domains that are included in the DTD or Schema. This attribute is defined with the XML data type CDATA, and each new document type SHOULD specify a default. The value will differ depending on what domains are included in the current DTD or Schema; a sample value is "(topic ui-d) (topic hi-d) (topic pr-d) (topic sw-d) (topic ut-d) (topic indexing-d)".

3.10.3: Attributes common to many map elements

Controls how metadata attributes cascade within a map. There are two defined values that should be supported: "merge" and "nomerge". If no value is set, and no value cascades from an ancestor element, processors SHOULD assume a default of "merge". See Cascading of metadata attributes in a DITA map for more information about how this attribute interacts with metadata attributes.

3.10.4: Complex-table attribute group

Indicates whether the entries in the respective column SHOULD be considered row headers. Allowable values are: firstcol Indicates that entries in the first column of the table are functionally row headers (analogous to the way that a <thead> element provides column headers). Applies when @rowheader is used on the <table> element. headers Indicates that entries of a column described using the <colspec> element are functionally row headers (for cases with more than one column of row headers). Applies when @rowheader is used on the <colspec> element. norowheader Indicates that entries in the first column have no special significance with respect to column headers. Applies when @rowheader is used on the <table> element. -dita-use-conref-target See Using the -dita-use-conref-target value for more information. Note This attribute is not part of the OASIS Exchange Table model upon which DITA tables are based. Some DITA processors or output formats might not support all values. The @rowheader attribute is available on the following table elements: <table> and <colspec>.

3.10.12: Topicref element attributes group

Use the @copy-to attribute on the <topicref> element to provide a different resource name for a particular instance of a resource referenced by the <topicref> (for example, to separate out the different versions of the topic, rather than combining them on output). If applicable, the @copy-to value can include path information. The links and navigation associated with that instance will point to a copy of the topic with the file name you specified. Applications MAY support @copy-to for references to local non-DITA resources. The @copy-to attribute is not supported for references to resources where the effective value for @scope is "peer" or "external". Use the <linktext> and <shortdesc> in the <topicref>'s <topicmeta> to provide a unique name and short description for the new copy.

3.10.13.1: The @href attribute

The value of a DITA @href attribute must be a valid URI reference [RFC 3986]. It is an error if the value is not a valid URI reference. An implementation MAY generate an error message; it MAY recover from this error condition by attempting to convert the value to a valid URI reference. Note that the path separator character in a URI is the forward slash (â/â); the backward slash character (â\â) is not permitted unescaped within URIs.

3.10.13.6: The @conaction attribute

It is an error for two source topics to replace the same element. Applications MAY warn users if more than one element attempts to replace a single target.

3.10.13.7: The @conrefend attribute

The start and end elements of a range MUST be of the same type as the referencing element or generalizable to the referencing element. For example, @conref and @conrefend attributes on an <li> element might reference other <li> elements, or they might reference specializations of <li> such as <step>.
The start and end elements in a range MUST share the same parent, and the start element MUST precede the end element in document order.
The parent of the referencing element MUST be the same as the parent of the referenced range or generalizable to the parent of the referencing element. For example, it is possible to pull a range from <conbody> into <body>, because <conbody> is generalizable to <body>. It is not possible to pull a range from <body> into <conbody>, because the result might not be valid in <conbody>.

3.10.13.8: The @conkeyref attribute

When the key name specified by the @conkeyref attribute is not defined and the element also specifies a @conref attribute, the @conref attribute is used to determine the content reference relationship. If no @conref attribute is specified there is no content reference relationship. Processors SHOULD issue a warning when a @conkeyref reference cannot be resolved and there is no @conref attribute to use as a fallback. Processors MAY issue a warning when a @conkeyref cannot be resolved to an element and a specified @conref is used as a fallback.

3.10.13.9: The @type attribute

If not explicitly specified on an element, the @type attribute value cascades from the closest ancestor element. If there is no explicit value for the @type attribute on any ancestor, a default value of âtopicâ is used. During output processing for references to DITA topics (format="dita"), it is an error if the actual type of a DITA topic and the explicit, inherited, or default value for the @type attribute are not the same as or a specialization of the @type attribute value. In this case, an implementation MAY give an error message, and MAY recover from this error condition by using the @type attribute value. During output processing for references to non-DITA objects (that is, either scope is âexternal" or format is neither âditaâ nor âditamapâ) or other cases where the type of the referenced item cannot be determined from the item itself, the explicit, inherited, or default value for the @type attribute is used without any validation. When a referencing element is first added to or updated in a document, DITA aware editors MAY set the @type attribute value based on the actual type of a referenced DITA topic.
For example, if the value is set to type="topic", the link could be to a generic topic, or any specialization of topic, including concept, task, and reference. Applications MAY issue a warning when the specified or inherited @type attribute value does not match the target (or a specialization ancestor of the target).

3.10.13.10: The @format attribute

If the actual format of the referenced content differs from the effective value of the @format attribute, and a processor is capable of identifying such cases, it MAY recover gracefully and treat the content as its actual format, but SHOULD also issue a message.

3.10.13.11: The @scope attribute

Processors can consider additional URI schemes as "external" by default. Processors MUST always consider relative URIs as "local" by default.

Chapter 4: Conformance

Conforming DITA implementations MUST include a conformance statement that gives the version of the DITA specification that is supported. The conformance statement must include one of the following:
An implementation that does not include a particular optional feature MUST be prepared to interoperate with other implementations that do include the feature, though perhaps with reduced functionality. An implementation that does include a particular optional feature MUST be prepared to interoperate with other implementations that do not include the feature.
If using non-DITA-conforming grammar files for conforming DITA documents, those grammar files MUST NOT be structured in a way that affects the ability of processors to process those documents. The use of non-conforming document types or schemas might impede interchange or interoperation of those documents with tools that expect or require the use of conforming DITA document types or schemas.
A processor that implements all required processing relevant to the vocabulary modules that it claims to support. A DITA-aware processor MUST support at least one map or topic type, whether defined by the DITA standard or defined as a custom vocabulary module.
For processors that produce final form output, all features that are relevant to the type of processing that the processor performs MUST be implemented, with the exception of features that are vocabulary-specific. In particular, such processors MUST implement address resolution and content reference resolution. Such processors SHOULD implement filtering.
Processors that store, manage, or edit DITA documents might not implement specific features that would be required for final-form processing. However, such processors MUST enable the creation or storage of DITA documents that use all DITA features, even if the processor is not aware of the DITA semantics for those features.

dita message