[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: FW: [dita] Conformation statement -- please review and discuss before the TC meeting on July 21
fyi From: Kristen James Eberlein [mailto:keberlein@pobox.com] 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 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: 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: 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. |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]