OASIS Darwin Information Typing Architecture (DITA) TC

 View Only

  • 1.  Conformance and Feature Optionality/Flexibility

    Posted 01-15-2008 20:00 
    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


  • 2.  RE: [dita] Conformance and Feature Optionality/Flexibility

    Posted 02-05-2008 20:18 
    













    


    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


  • 3.  Re: [dita] Conformance and Feature Optionality/Flexibility

    Posted 02-07-2008 14:14 
    Ogden, Jeff wrote:

> 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?

I think so.

> Did I pick the right “feature” and “processor type” categories?

I think that this feature applies to all processor types. That is, all
the DITA features that define the rules for determining effective values
are relevant to all processor types, simply because they all either
contribute to the determination of values or act on the values.

> Which processing requirements category is the right one for this case?

I think this is "required but variable". In particular, this aspect of
DITA is defining the rules for determining the effective values of
attributes and elements. It is essential that all processors use the
same effective values for a given data set, but what they do with those
effective values is still variable.

My analysis is that features that define effective values are all
required but variable. So this feature is of a kind with conref= and
keyref=.

The language in the spec using the terms "must" and "shall" is another
indicator of requiredness.

Cheers,

Eiot

-- 
Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 610.631.6770
www.reallysi.com
www.rsuitecms.com


Related Content