[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]