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