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.

 

 

The content of this email and any attached files are intended for the recipient specified in this message only. It may contain information that is confidential, proprietary, privileged, and/or exempt from disclosure under applicable law. It is strictly forbidden
 to share any part of this message with any third party or rely on any of its contents, without the written consent of the sender. If you received this message by mistake, please reply to this message and follow with deletion of the original message, any copies
 and all attachments, so that we can ensure such a mistake does not occur in the future.