OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [dita] Normative statements in DITA 1.3


In case anyone is interested in the quantity comparison, there are 251 such statements in that Appendix in the MQTT spec.

mag


On Tue, Mar 26, 2019 at 10:22 AM Chris Nitchie <chris.nitchie@oberontech.com> wrote:

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.


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]