Here is the text of the conformance statement that Jeff Ogden drafted.
I've uploaded the DITA source file to the Subversion repository; you
can access it from
http://tools.oasis-open.org/version-control/browse/wsvn/dita/conformance.dita
Kris
-------------------------------
Conformance
This chapter outlines the requirements that must be met
for documents, document types, specialization modules, and processors
to be considered DITA conforming. This chapter also defines conformance
related terminology that is used throughout the DITA specifications.
Conformance to the DITA specifications allows documents and document
types that are shared within and across organizations and used with
different processors or different versions of a processor to produce
the same or similar results with little or no reimplementation.
Keywords
The capitalized words "MUST", "MUST
NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
"RECOMMENDED",
"MAY", and "OPTIONAL" in the DITA specifications are to be interpreted
as described in IETF RFC
2119. When these words are not capitalized, they should be
interpreted in their natural-language sense.
The use of these
keywords and other conformance requirements increase the level of
interoperability that is available between DITA conforming
implementations.
Their use is not meant to impose particular methods on implementers
where the method is not required for interoperability.
Conformance statement
DITA conforming implementations
MUST include a conformance statement that lists the DITA features
that are supported by the implementation and are implemented in
accordance
with the requirements of the DITA specifications together with the
version of the DITA specification. Or, if it is clearer, the statement
MAY say that the implementation includes all of the features for a
particular category of implementation together with a list of features
that are not included.
Documents, document types, specialization
modules, and processors that implement the requirements given in the
OASIS approved DITA specifications are considered conforming.
Implementations
that include some DITA features, but not others, are considered
conforming
as long as all REQUIRED features for the category of implementation
are included and all of the features that are included follow the
requirements given in the DITA specification. An implementation which
does not include a particular optional feature MUST be prepared to
interoperate with another implementation which does include the
feature,
though perhaps with reduced functionality. And, while less common,
an implementation which does include a particular optional feature
MUST be prepared to interoperate with another implementation which
does not include the feature.
Organizations and individuals
are free to impose additional constraints on their own use of DITA
that go beyond the requirements imposed by the DITA specifications,
possibly including enforcement of the constraints by their local tools,
as long as the result continues to meet the requirements given in
the DITA specifications. For example, a given user community could
impose rules on how files must be named or organized even if those
rules go beyond the requirements given in the DITA specifications.
Conformance categories
The following categories
are used to define the amount of flexibility that is available when
implementing specific requirements.
- Required and invariant
- Features that MUST be implemented exactly as defined in the DITA
specification. This classification applies primarily to the XML syntax,
DITA documents, the rules for creating DITA specializations and
document
types, and address resolution behavior. For example where a given
address must always resolve to the same object for the same input
data set.
- Required but variable
- Features that MUST be implemented and for which the effective
result MUST be consistent with rules as defined in the DITA
specification
but for which the specific expression may vary.
-
For example, any implementation of the content reference feature
MUST reflect the same effective result for the same input data set
but the way that effective result is provided can vary. The content
reference could be implemented by a pre-process step that replaces
the reference by the referenced content or by a process that generates
the functional equivalent of the content reference in the target output
(e.g., a transclusion instruction in a Wiki page).
- Variable with defaults
-
Features that MAY produce various behaviors or outputs, but
for which the DITA specification defines a default that all conforming
implementations MUST provide.
Implementations are NOT REQUIRED
to make the DITA-defined default their default. Implementations are
only REQUIRED to provide an appropriate set of options or configuration
that will provide the DITA-defined defaults.
These features
are primarily formatting defaults for elements where a default
presentation
is natural or expected, such as paragraphs, lists, and tables. An
application for a specific use domain might define default formatting
behaviors that are significantly different from the DITA-defined
defaults.
For example, an application specifically for legal information could
provide a different default presentation from an application for
technical
documentation.
- Variable without defaults
-
Features that MAY be implemented to produce various behaviors
or outputs and for which the DITA specification defines no required
default.
The DITA specification may include examples or suggested
behaviors for these features but such suggestions are informative,
not normative.
- Informative or non-normative
-
The DITA specifications include examples and other suggestions
that are informative rather than normative. While informative
information
is often very helpful, it is never a binding part of the DITA
specifications
even when the example or other information is about a feature that
is REQUIRED.
If a particular conformance category is not specified
for a feature and the appropriate category cannot be determined from
the information available in the DITA specifications the feature MUST
be considered required and invariant. Unless it is clearly stated
otherwise, examples are always informative rather than normative.
Processors and processor type categories
Processors
that implement some DITA features, but not others, are considered
conforming as long as the features that are implemented follow the
requirements given in the DITA specification for those features.
Processors
that are not DITA aware are not considered conforming, but may still
be useful when working with DITA.
The level of conformance for
a given processor can only be determined by examining the features
that the component implements and the degree to which these features
follow the requirements given in the DITA specifications.
Because
the number of possible DITA-aware processors is large, it is useful
to define several processor type categories that can be used to define
which requirements apply to which processors. A given processor may
belong to more than one category.
The DITA specifications use
the following categories of processor types in defining processor
related requirements and suggestions:
- DITA-aware processor
-
A processor that implements features defined by the DITA
specifications
including all of the required and invariant, the required but variable,
the variable with defaults, and other requirements from the DITA
specifications
for the features that it includes.
All conforming DITA processors
must be specialization aware such that they are able to process any
valid DITA document regardless of the details of its governing document
type.
- DITA editor
- An interactive application that enables the creation and
modification
of conforming DITA documents.
- Information management system
- A processor that stores and manages DITA documents in a way that
takes advantage of DITA-specific aspects of the data in order to
facilitate
the management of those documents through a development or delivery
process. Such systems may be content management systems that support
authoring workflows or they may be retrieval systems that support
delivery workflows.
- Renderer
- A processor that takes as input one or more conforming DITA
documents
and produces as output final-form renderings of those documents, such
as HTML pages, paginated PDF, compiled online help, etc. Most simply,
a DITA renderer is a processor that is directly responsible for
producing
a visual, aural, tactile, or interactive result from DITA content,
either by providing the rendition directly or by providing direct
input to the rendition delivery system (e.g., providing HTML content
to a Web browser or typesetting commands to a pagination system).
A renderer always either incorporates a source-to-source transform
within itself or uses the output of a standalone source-to-source
transformer.
- Source-to-source transformer
- A processor that takes as input one or more DITA or non-DITA
documents
and produces as output non-final-form XML documents. At least one
of the input or output documents must be a conforming DITA document,
but he output documents are NOT REQUIRED be conforming DITA documents.
Source-to-source transformers may be standalone tools or may be
inseparable
components of tools in other categories.
Rendition categories
Draft
comment:
Draft-comment:
It is unclear if some or even any of these rendition categories will
be used elsewhere in the DITA specification. If they are not used,
this section will be deleted.
Not all rendition
requirements, defaults, and suggestions are relevant to all possible
rendered outputs. The DITA specifications use the following rendition
types in defining rendition requirements and suggestions:
- HTML-based interactive media
- Renditions that use HTML markup as the primary representation,
intended to be viewed through Web browsers or similar online,
interactive
systems.
- paged media
- Renditions that produce images of physical pages intended for
printing on paper.
- Embedded "constrained format" help
- Help for use with highly constrained delivery environments such
as mobile phones and printer consoles.
- aural
- Renditions that are intended for aural consumption by human
listeners.
- interactive
- Renditions that include interactive behavior as a primary aspect
of their presentation, such as an interactive electronic technical
manual or an interactive learning application.
Conformance by feature groups
The following
summary outlines the conformance requirements for high-level groups
of features. For more detailed conformance information see the feature
descriptions contained in the DITA specifications or the summary table
in Appendix ?
Draft
comment:
Draft-comment: It is possible that
we should omit this section and just use the summary table in the
Appendix.
- Documents
-
Required but variable.
A conforming DITA document MUST
be syntactically valid with respect to a conforming XML document type
declaration (DTD) or XML schema document (XSD) and MUST otherwise
implement all content and structure requirements defined by the DITA
specifications.
Conforming DITA processors MUST be able to process
all conforming DITA documents, but they are NOT REQUIRED to support
all features that may be present in or used from those documents.
- Document types (element and attribute
definitions)
-
Required but variable.
A conforming DITA document type
MUST implement all of the syntactic and organizational requirements
for DITA document type declarations (DTDs) or schemas (XSD) as defined
by the DITA Architecture Specification.
Conforming DITA processors
MUST be able to process all conforming DITA document types, but they
are NOT REQUIRED to support all features that may be available for
use from those document types.
- Specialization modules
-
Required but variable.
A conforming DITA specialization
module MUST implement all of the syntactic and organizational
requirements
for DITA specialization modules as defined in the DITA Architecture
Specification.
Conforming DITA processors MUST be able to process
conforming DITA document types that include specialization modules,
but they are NOT REQUIRED to support all features that may be available
for use from those document types.
- Addressing
-
Required and invariant.
Addressing includes the pointers
from one DITA construct to another or from a DITA construct to a
non-DITA
construct including: href, conref, keyref, and other reference values.
Addressing
includes the syntax that MUST be used to write addresses (pointers)
as strings within DITA documents and the rules which MUST be followed
when pointers are resolved to resources. How the resource is used
once it is resolved is not covered by this feature group.
- Linking
-
Required but variable.
Includes those features that establish
relationships among abstract components, including: topicref , xref,
reltable and data-about.
For a given relationship the set of
related components and their DITA-defined roles within the relationship
are required and invariant. However, the rendition result for a given
relationship instance or type is variable with defaults for most or
all of the DITA-defined link types.
- Content reference (conref)
-
Required and invariant.
This is a special case of linking
where there is less room for variance. In particular, the effective
value of resolving a conref MUST be invariant for a given pair of
elements. However, the rendition result for a Content Reference could
vary.
- Rendition behavior
-
Variable with or without defaults.
Includes all features
that relate to how a given element looks or behaves interactively
in the context of a particular rendition type. It is mostly bound
to element types, e.g., lists must have a list nature, tables should
have tabular nature, etc. Rendition is either rendition-specific with
defaults or rendition specific.
While wide variation in rendition
is possible, there is an intent that the rendition of a given element
type be consistent with its core semantic. For example a "pre" element
SHOULD NOT be rendered as flowing text unless it can be shown that
the particular rendering is consistent with the basic semantic of
"pre". In these cases the intent of the specification is often
expressed
through definition of variable with defaults rendering effects.