← Prev in month ← Prev in thread

Next in thread → Next in month →

Re: [dita] Normative statements in DITA 1.3

From: Kristen James Eberlein <>
Date: 2019-03-26T17:51:45+00:00
ID
Thread: Re: [dita] Normative statements in DITA 1.3

Thank you! This is very useful.

Best,

Kris

Kristen James Eberlein

Chair, OASIS DITA Technical Committee

Principal consultant, Eberlein Consulting

www.eberleinconsulting.com

+1 919 622-1501; kriseberlein (skype)

On 3/26/2019 1:22 PM, Chris Nitchie
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

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.

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>

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:

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 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:

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.

View original preserved HTML → View on OASIS Connected Community →

← Prev in month ← Prev in thread

Next in thread → Next in month →