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] Conformation statement -- please review and discuss beforethe TC meeting on July 21


You also might want to be familiar with OASIS guidelines for writing 
conformance clauses

http://docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html

Kris

Kristen James Eberlein wrote:
> 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 <http://www.ietf.org/rfc/rfc2119.txt>. 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.
>
> --------------------------------------------------------------------- 
> To unsubscribe from this mail list, you must leave the OASIS TC that 
> generates this mail. Follow this link to all your TCs in OASIS at: 
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php 




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