[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [dita] Conformance and Feature Optionality/Flexibility
|
Eliot,
Your note from three weeks or so ago seems like a good start on pulling together an approach to a conformance statement. It also seems that over time it will lead us to feature specific answers about what is or isn't required by the DITA specification.
At the end of your note, you said: > It might be useful to take some the various forms of processing variance > that have been discussed or people think they might want and try to see > where they fall within this category matrix--if this set of categories > is useful then we should be able to quickly distinguish allowable or > allowed variances from disallowed variances, or at least be able to > focus our discussion when there is not consensus about whether a given > variance should be allowed.
I'd like to take some sections of "Inheritance of attributes and metadata in maps" and "Topic properties in topics and map" from Chapter 3 on “DITA markup” in the DITA 1.1 Architectural Specification and see how they fit into this approach.
In particular the specification says:
“Some of the attributes and metadata in a map can be inherited based on the structures in the map. Inheritance is additive except where this would cause a conflict. When there is a conflict, the value defined closest (most specifically) to the topicref takes effect.”
[There is a list of the specific attributes and metadata elements are inheritable.]
“You can associate topic metadata with a topic or branch of topics in a map. By default metadata in the map supplements or overrides metadata in the topic. If the lockmeta attribute is set to ″no″, then the metadata in the map will not take precedence over the metadata in the topic, and conflicts will be resolved in favor of the topic.”
The above statements describe behaviors that fit into the “element type and attribute definitions” feature category.
The behaviors are mostly of concern to “renderers”, but could also apply to “editors”, “information management systems”, and “source-to-source transformers”.
I’m less sure about which “defined processing requirements” category the behavior falls into, but suggest “required but variable” as the best fit. I can imagine that some may feel that “rendition-defined with defaults” is the better fit. I don’t think either “required and invariant” or “rendition-defined” without defaults are appropriate for this case.
Am I approaching this is the right way?
Did I pick the right “feature” and “processor type” categories?
Which processing requirements category is the right one for this case?
Are the terms and categories outlined in Eliot’s note a good match for what we need to pin down in the DITA specification?
-Jeff
> -----Original Message----- > From: Eliot Kimber [mailto:ekimber@reallysi.com] > Sent: Tuesday, January 15, 2008 3:00 PM > To: dita@lists.oasis-open.org > Subject: [dita] Conformance and Feature Optionality/Flexibility > > I'd like to see if I can define some categories and definitions that > will let us clearly distinguish between invariant and variant processing > and better characterize the conditions under which a given DITA-aware > processor conforms to the DITA specification. > > A general statement: Users are always allowed to limit features as a > matter of local policy. For example, you might impose a policy that all > conrefs must be to resources in a particular place in your storage > system. That sort of constraint has no effect on the processing result, > it only constrains what authors are allowed to do. However, this type of > constraint is a matter of local policy that users choose to impose on > themselves. If a tool, inadvertently or by design, imposes a constraint > that is not inherent in the spec, it must at least clearly document that > constraint. That suggests there needs to be a conformance category like > "conforming with limits" meaning that the processor can correctly > process only a subset of all possible valid DITA documents. The most > likely example would be constraints on what things can be addressed. > > Thus, for the specific case of addressing, there is a fundamental > difference between implementing addressing as defined in the spec, but > for a subset of possible addresses, as opposed to implementing > addressing in a way that is completely different from the spec. The > first case is fine, the second case is bad. It also suggests that > systems that implement such constraints should clearly distinguish > errors that are violations of the spec and errors that are violations of > policy. For example, say you bring in a new document that violates the > conref location policy but the address used to create the conref is > otherwise correct. In that case it would be inappropriate to report the > document as just "invalid" but it would be appropriate to report that > the conref target location policy had been violated. > > --------------- > Processor Types > > While the universe of possible DITA processor types is unbounded, I > think we can reasonably codify the following general classes of > processor that have important distinguishing characteristics and > conformance and flexibility implications: > > - Source-to-Source Transformers: Tools that take DITA-based content as > input and produce new data sets that are not intended as final > deliverable renditions but as the source for additional processing, such > as further rendition processing or authoring workflows. Such transforms > would include both DITA-to-DITA transforms, where the result of the > transform is a new set of DITA-based documents, and DITA-to-X > transforms, where the result is not DITA based (e.g., DocBook documents, > FrameMaker MIF, etc.) but is not a final form either. Source-to-source > transformers may be standalone tools or may be inseparable components of > tools in other categories. > > - Renderers: Tools that take DITA-based content as input and produce > some final-form consumable rendition of it: visual, aural, tactile, > where the intended use of the rendition is to enable human consumption > of the information, e.g., a printed manual, a set of Web pages, a > talking book. Renderers may be standalone publishing tools or may be > components of editors that provide a visual editing mode. A renderer > always either incorporates a source-to-source transform within itself or > uses the output of a standalone source-to-source transformer. The key is > that rendering DITA content correctly in the general case always > requires some amount of source-to-source transform, either literally or > logically, in order to correctly implement the semantics of conref and > maps, irrespective of the nature of the final rendition. > > - Editors: Tools that enable the interactive creation and modification > of DITA-based XML documents. Editors may or may not incorporate > renderers that produce a more-or-less WYSIWYG rendered view of the > content for authoring (as distinct from simply enabling processing of > the content through a separate renderer, e.g., the Toolkit). > > - Information Management System: Tools that store and manage DITA-based > content in a way that takes advantage of DITA-specific aspects of the > data, such as providing features for manipulating DITA maps or searching > based on specialization hierarchies or map context. Such systems may be > content management systems that support authoring workflows or they may > be retrieval systems that support delivery workflows (e.g., an Astoria > or XHive Docato vs. MarkLogic or eXist). > > ------------------------------------ > DITA-Defined Processing Requirements > > I think that DITA processing indicated by the DITA specification can be > classified into the following categories: > > - Required and invariant: The processing result must be exactly as > specified in the spec and there is no useful deviation from the spec. > This will be those things that are purely mechanical, such as resolving > address pointers to resources. > > - Required but variable: The processing result must be "consistent with" > the specification but there are different ways in which the processing > could legitimately be expressed. Conref is the obvious member of this > category, where the "effective result" of applying conref is clearly > defined but there are many ways that that result could look in practice. > Different types of processors may have different expectations. For > example, a renderer must render the conref as resolved in some way, > while an editor needs to enable the creation of conrefs and their > navigation but may or may not be obligated to provide a "resolved view". > An information management system needs to maintain knowledge of the > conrefs but won't do anything to the data itself. > > - Rendition-defined with defaults: Any rendition may do whatever it > wants but the specification defines default rendition effects for > well-known rendition targets that renderers should produce in absence of > explicit, user-requested overrides. The intent here is to ensure that > different renderers give consistent results for the same elements > rendered to the same rendition type. E.g., The "b" element should be > rendered as bold text by default in visual renderings. The default > behavior is normative in that every conforming DITA processor that > produces a given rendition type must provide at least one style > configuration that produces the default result. This does not imply that > the default rendition produced by a given tool be the DITA-defined > default, only that the DITA-defined default be an available option. > > - Rendition-defined without defaults: The processing result is entirely > rendition-specific and the specification defines no specific default > behavior, although it may indicate non-normative possible renderings, > e.g. "This could be presented as a table or a list or a graphic or ...". > > "Well known" rendition types must include: > > - Paged media (printed pages) > > - HTML-based interactive media (Web browsers, HTML-based help systems) > > - Digital talking books (e.g., DAISY/NIMAS) > > - Embedded "constrained format" help (e.g., phone help, printer help) > > - Interactive electronic technical manuals (IETMs) > > That is, less formally, visual, aural, and interactive renditions, with > the visual renditions having more or less typographic capability. > > ----------------------- > DITA Feature Categories > > I think that DITA features can be sorted into the following categories: > > - Element type and attribute definitions (the "DITA document types") > > This is the core types and all the DITA TC-defined specializations. > > The syntax rules represented by these parts of the standard are clear > and the rules for what you can and can't control is well defined in the > architecture spec. That is, the rules for specialization of DITA markup > are well defined. For conformance, this is primarily applicable to > specialization declaration implementations and editors to the degree > that they allow things required by DITA and don't allow things that > aren't allowed. In general, an editor would have to go out of its way to > not conform in this area assuming it's out-of-the-box configuration is > otherwise correct (uses the official DTDs and so on). There might be > areas where a given editor has hard-to-correct limitations, such as in > table processing or something, but any XML editor should always be able > to allow any valid DITA document to be created. > > Support for specialization at all beyond the core types might be a > conformance question, I suppose. But I would assert that support for > specialization (that is, recognition and processing of DITA element > types based on their class hierarchy is an non-optional feature of DITA). > > That is, a tool that only supports use of the base DITA types using > the TC-provided shells cannot be a conforming DITA processor, unless we > want to define a class of conformance that is exactly this. > > - Addressing > > This is mechanical pointers from one DITA construct to another, > including: > > - href= "and" conref= values > > - keyref (as it is being defined in 1.2) > > Addressing is formally defined in terms of two aspects: > > - The syntax by which addresses (pointers) are written as strings > within documents > > - The processing by which pointers are resolved to resources > > Both of these are invariant, such that for a given address string > used in a given context against a given set of data, the resulting > resource must always be the same. Any processor that needs to resolve > pointers must implement the pointer resolution as required by the spec. > > NOTE: What it does with the resolved result is an entirely different > question. > > - Linking > > This is all those features that serve to establish relationships > among abstract components, including: > > - topicref > > - xref > > - reltable > > - data-about > > For a given relationship the set of things related and their > DITA-defined roles within the relationship are invariant. However, the > rendition result for a given relationship instance or type would be > rendition-defined with defaults for most or all of the DITA-defined link > types. > > - Conref > > This is a special case of linking where the there is less useful 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 conref could vary, in that you might have a rendition that > reports both the conref source and target in some useful way (for > example, showing both the source and effective values for the attributes > shared between the two elements involved). But the elements involved > must be the same in all cases. > > - Rendition behavior > > This is 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. However, there > is an essentially impossible to enforce intent that the rendition of a > given element type be consistent with its core semantic, meaning that it > would be "wrong" to render "pre" elements as flowing text unless you > could show how that particular rendering is in fact consistent with the > basic semantic of "pre". > > In these cases the intent of the spec can be best expressed through > definition of normative default rendering effects where there is a > relevant distinct rendering effect. This would require at least crisping > up the existing language to make it more precise and/or add something > for each relevant rendition type. This could aided to some degree by > making some general statements that serve as "default defaults" just to > avoid continually restating the obvious. > > It might be useful to take some the various forms of processing variance > that have been discussed or people think they might want and try to see > where they fall within this category matrix--if this set of categories > is useful then we should be able to quickly distinguish allowable or > allowed variances from disallowed variances, or at least be able to > focus our discussion when there is not consensus about whether a given > variance should be allowed. > > Cheers, > > Eliot > > -- > Eliot Kimber > Senior Solutions Architect > "Bringing Strategy, Content, and Technology Together" > Main: 610.631.6770 > www.reallysi.com > www.rsuitecms.com > > --------------------------------------------------------------------- > To unsubscribe from this mail list, you must leave the OASIS TC that > generates this mail. You may a link to this group and 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]