thanks
Jeff - I was coming up to speed on the OASIS conformance guidelines - http://docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html -
just before reading this, and in that context it makes a lot of
sense
you're
right - a lot of work would needed to be done to get conformance in order in the
1.2 spec - sorry to hear not much has been done to progress your draft of last
March
at
this point, perhaps it is best to concentrate on regularizing our
conformance clauses to use the standard upper-case vocabulary for 1.2, and
work on integrating something along the more robust lines of your draft for
1.3
an
issue I have with our vocabulary as it exists in the draft so far, besides its
non-standard nature, is that it tends of be overweighted toward the
REQUIRED end of the spectrum for features that are designed to support
round-trip generalization and re-specialization, and conrefs between differently
constrained document instances - which not every implementation wants or
needs to support - and gives less play to the RECOMMENDED and MAY parts of the
spectrum, especially for these advanced kinds of features
also,
I think the specifications needs a statement at the end that at least recognizes
the validity of creating non-conforming DITA variants that are only based on the
specification, but derive their interoperability from generic XML standards
alone - the way, e.g., that the DocBook standard does
-----Original Message-----
From: Ogden, Jeff
[mailto:]
Sent: Thursday, July 02, 2009 1:09
PM
To: dita
Subject: RE: [dita] some comemnts on the Draft
DITA 1.2 architecture spec.
And
a slightly different take on this issue.
Dana
wrote:
> I'm
not sure why we shouldn't distinguish between vendors, implementers, and
authors in the spec.
You could, but you’d have to
do it very carefully. And so far the DITA spec. hasn’t done much of this, so
it will be a lot of new work and probably take a lot of discussion to get
agreement.
If
you distinguish between people or organizations that have different roles in
examples and other non-normative descriptions, it isn’t too hard to do. If you
start to try to impose different requirements on different people or
organizations, then things get a lot more complex very
quickly.
The
draft conformance statement that was originally written by Eliot and revised
by me back in March 2008 starts to address these issues, but there hasn’t been
much done with this since then. See:
http://www.oasis-open.org/apps/org/workgroup/dita/download.php/27616/conformance1.2-jcoV2.pdf
The
thing to note in the draft conformance statement is that rather than talking
about people and organizations with different roles (vendors, implementers,
authors, …) it talks about implementations and the “requirements
that must be met for documents, document types, specialization modules, and
processors to be considered DITA conforming”.
Different
levels of conformance are allowed for different types of implementation and a
DITA conforming implementation does not have to implement all features to be
conforming. Some excerpts from the draft 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
….
·
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.
The
draft statement goes on to define five Conformance
Categories:
1.
Required
and invariant
2.
Required
but variable
3.
Variable
with defaults
4.
Variable
without defaults
5.
Informative
or non-normative
As
well as five types of processors:
1.
DITA-Aware
Processor
2.
DITA
Editor
3.
Information
management system
4.
Renderer
5.
Source-to-source
Transformer
And
then seven feature groups:
1.
Documents
(required, but variable)
2.
Document
types (required, but variable)
3.
Specialization
Modules (required, but variable)
4.
Addressing
(required and invariant)
5.
Linking
(required, but variable)
6.
Content
reference (required and invariant)
7.
Rendition
behavior (variable with or without defaults)
The
work that I don’t think has been done is to define a more detailed list of
DITA features, to state if each feature is required or optional, and place
each feature into one of the feature groups listed above or possibly in new
feature groups, if none of the existing groups works well for a particular
feature.
All
of this is done without talking about vendors, implementers, or authors
(people, organizations, or roles). Instead the people or organizations
would identify what it is they have implemented, what type of implementation
it is, what features the implementation includes, that all required features
for the type of implementation have been included, and that all of the
requirements for all included features have been met. Once all of that
is done, they are entitled to claim that they have a “DITA conforming”
implementation.
Or
at least that was the thinking from more than a year ago.
The
DITA TC will need to decide how much or how little of this they want to take
on for the DITA 1.2 specification. To do this completely and well will be a
lot of work.
-Jeff
From: Dana Spradley
[mailto:]
Sent: Wednesday, July 01, 2009
5:59 PM
To: Ogden, Jeff; dita
Subject: RE: [dita] some
comemnts on the Draft DITA 1.2 architecture
spec.
Hi
Jeff--
I'm
not sure why we shouldn't distinguish between vendors, implementors, and
authors in the spec.
The
HTML spec, for example, distinguishes between authors, users, and user agents,
and imposes different kinds and levels of conformance on each.
Also,
I think most tools that support DITA also support XML in general - which
allows for much greater customizability even than DITA.
So
typically if an implementor diverges from the DITA standard, but conforms to
more generic XML standards, their vendor toolkit will support
them.
For
example, the authoring/publishing tool I'm most familiar with has implemented
DITA conrefs...but generically, so that any xml application can use them - and
call the attribute that supports them by any name it wants to.
So it
seems vendors are already going beyond the call of duty to support customers
who want to implement standard DITA features, but in various non-standard
ways.
Shouldn't
the standard indicate where we acknowledge the validity of such divergence -
and encourage vendors to support it - and where we absolutely don't - and
mandate that vendors do not support it?
--Dana
-----Original
Message-----
From: Ogden, Jeff
[mailto:]
Sent: Wednesday, July 01, 2009 10:55
AM
To: dita
Subject: RE: [dita] some comemnts on the
Draft DITA 1.2 architecture spec.
Dana,
I think what you outline
makes a lot of sense. But the DITA specification doesn’t really make a
distinction between vendors, implementers, and end user authors. And I’m not
sure we should treat these classes of folks differently in the
specification. Requirements are requirements and should apply to everyone.
We shouldn’t have different requirements for vendors than we do for other
implementers or for authors.
What this all points out is
that one of DITA’s strong points is how customizable it is, but the fact
that it is so customizable makes it harder to write an understandable and
unambiguous standard. Although some might argue that using the words
“standard” and “understandable” in the same sentence is a conflict to start
with :-).
Another thing that makes
this hard is that the DITA TC only has the DITA Specification to work with
or perhaps the DITA Specification plus some best practice documents. If we
had something other than the DITA Specification such as an Implementer’s
Guide or a User’s Guide that might allow us to focus the specification on
true standards issues and focus the other documents on issues that are of
more concern to implanters or authors. I guess some of this might be
something that the DITA Adoption TC could take on, but it would be a lot of
work and isn’t likely to happen soon.
Given the recent discussions
I would update my outline to look something like this:
1)
Customization
1.1)
Specialization
1.1.1)
Structural
Specialization
1.1.2)
Domain
Specialization
1.2)
Integration (via document type
shells)
1.2.1)
Modules
1.2.2)
Constraints
1.3)
Processing
1.3.1) Transformations
1.3.1.1)
Conditional Processing (filtering and flagging)
1.3.1.2)
Conref processing
1.3.1.2)
Merging properties between maps and topics including key and keyref
processing
1.3.1.3)
Default attribute value processing
1.3.2) Stylesheet
processing/formatting
But I would note that the
use of “customization” above is different from the definition of
customization in the DITA 1.1 spec. In the DITA 1.1 spec. it seems as
if customization, integration, and specialization are peer terms. If
we want to stick with that (we don’t have to), then we need a new word,
perhaps “configuration”, and the outline might look like
this:
1)
Configuration
1.1)
Specialization
1.1.1)
Structural
Specialization
1.1.2)
Domain
Specialization
1.2)
Integration (via document type
shells)
1.2.1)
Modules
1.2.2)
Constraints
1.3)
Processing
1.3.1) Transformations
1.3.1.1)
Conditional Processing (filtering and flagging)
1.3.1.2)
Conref processing
1.3.1.2)
Merging properties between maps and topics including key and keyref
processing
1.3.1.3)
Default attribute value processing
1.3.2) Customization (stylesheet
processing/formatting)
The items toward the top of
the outline are pretty tightly defined by the DITA specification. The items
toward the bottom of the outline are less tightly defined or in the case of
(1.3.2) Customization, perhaps undefined by the
specification.
-Jeff
Here are the DITA 1.1
definitions:
Customization
When you just need a difference in output, you
can use DITA customization to override the default output without affecting
portability or interchange, and without involving
specialization.
For example, if your readers are mostly
experienced users, you could concentrate on creating many summary tables,
and maximizing retrievability; or if you needed to create a brand presence,
you could customize the transforms to apply appropriate fonts and indent
style, and include some standard graphics and copyright
links.
Use customization when you need new output,
with no change to the underlying semantics (you aren’t saying anything new
or meaningful about the content, only its display).
Integration
Each domain specialization or structural
specialization has its own design module. These modules can be combined to
create many different document types. The process of creating a new document
type from a specific combination of modules is called
integration.
Integration is accomplished using a document
type shell, which defines the modules to be integrated and how they will be
integrated. Integration defines both what topic types and domains will be
allowed in the document type, and how the topic types will be allowed to
nest.
The module for a specific type should contain
only the declarations for elements and attributes that are unique to that
type, and should not embed any other modules. The shell should contain no
markup declarations, and should directly reference all the modules it
requires. Nesting shells or nesting modules (having shells that embed other
shells, or modules that embed other modules) is discouraged since it adds
complexity and may break some tools. Sharing between document types should
be accomplished through shared modules, not through direct reference to any
other document type. Dependencies between modules should be satisfied by the
integrating shell, not through the module itself.
What is
specialization?
Specialization allows you to define new kinds
of information (new structural types or new domains of information), while
reusing as much of existing design and code as possible, and minimizing or
eliminating the costs of interchange, migration, and
maintenance.
Specialization is used when new structural
types or new domains are needed. DITA specialization can be used when you
want to make changes to your design for the sake of increased consistency or
descriptiveness or have extremely specific needs for output that cannot be
addressed using the current data model. Specialization is not recommended
for simply creating different output types as DITA documents may be
transformed to different outputs without resorting to specialization
(see Customization).
There are two kinds of specialization
hierarchy: one for structural types (with topic or map at the root) and one
for domains (with elements in topic or map at their root, or the attributes
props or base). Structural types define topic or map structures, such as
concept or task or reference, which often apply across subject areas (for
example, a user interface task and a programming task may both consist of a
series of steps). Domains define markup for a particular information domain
or subject area, such as programming, or hardware. Each of them represent an
“is a” hierarchy, in object-oriented terms, with each structural type or
domain being a subclass of its parent. For example, a specialization of task
is still a task; and a specialization of the user interface domain is still
part of the user interface domain.
Use specialization when you are dealing with
new semantics (new, meaningful categories of information, either in the form
of new structural types or new domains). The new semantics can be encoded as
part of a specialization hierarchy, that allows them to be transformed back
to more general equivalents, and also ensures that the specialized content
can be processed by existing transforms.
From: Dana Spradley
[mailto:]
Sent: Wednesday, July 01, 2009
12:33 PM
To: Ogden, Jeff; JoAnn Hackos; dita
Subject:
RE: [dita] some comemnts on the Draft DITA 1.2 architecture
spec.
I
think I'm starting to agree with you Jeff: the entire section should be
called "Customization," and specialization should be considered a species of
customization.
So
the distinction is between using a vendor implementation of DITA off the
shelf and out of the box without modification - which some, perhaps many
implementors are going to do - and "customizing" that vendor implementation
to fit customer requirements.
What
this section needs to do in terms of conformance is to spell out vendor and
implementor responsibilities for each kind of customization to achieve an
interoperable, or at least a harmless, system (to use the RFC
phraseology on conformance statements), i.e.:
Shells:
Vendors MUST support, implementors SHOULD use
Constraints:
Vendors MUST support, implementors SHOULD use
Specialization:
Vendors MUST support, implementors MAY use
Variation
(or whatever we call customization that changes some parts of the DITA
vocabulary or violates some of its architectural principles, yet produces
valid XML, and perhaps even valid DITA document instances): Vendors SHOULD
support, implementors MAY use
-----Original
Message-----
From: Ogden, Jeff
[mailto:]
Sent: Tuesday, June 30, 2009 11:23
AM
To: JoAnn Hackos; Dana Spradley; dita
Subject: RE:
[dita] some comemnts on the Draft DITA 1.2 architecture spec.
I don’t know if there is a
less “drastic” and more appropriate term than “customization”, but I’m
sure that “specialization” isn’t the right word to use when someone
creates a new document type shell. Specializations create new DITA
types. Modifying a document type shell doesn’t create a new DITA type, but
just assembles existing DITA types for use. One of the goals of the
constraints proposal as I remember it was to allow customization without
requiring specialization.
I’ve always thought of
“specialization” as being a subset of the larger class of
customizations:
1)
Customization
1.1)
Specialization
1.1.1)
Structural
Specialization
1.1.2)
Domain
Specialization
1.2)
Customized Document type
shells
1.3)
Customized
Processing
1.3.1) Transformations
1.3.2) Stylesheet
processing/formatting
Part of the problem here
may be that we don’t have good names for 1.2 and
1.3.
-Jeff
From: JoAnn Hackos
[mailto:]
Sent: Tuesday, June 30,
2009 1:52 PM
To: Dana Spradley; Ogden, Jeff;
dita
Subject: RE: [dita] some comemnts on the Draft DITA 1.2
architecture spec.
Should
not we always refer to such changes as “specializations” rather than
“customizations”?
JoAnn Hackos
PhD
President
Comtech Services,
Inc.
Skype
joannhackos
From: Dana Spradley
[mailto:]
Sent: Tuesday, June 30, 2009
11:46 AM
To: Ogden, Jeff; dita
Subject: RE: [dita]
some comemnts on the Draft DITA 1.2 architecture spec.
Is
"customized"/"customization" really appropriate here? Are is this
something we're considering less drastic than customization?
-----Original
Message-----
From: Ogden, Jeff
[mailto:]
Sent: Monday, June 29, 2009 7:37
PM
To: dita
Subject: [dita] some comemnts on the
Draft DITA 1.2 architecture spec.
Some
suggestions with additions underlined
and blue and deletions strikeout
and red:
Concrete
document types
A
given DITA map or topic document is governed by a concrete document type
that defines the set of structural modules (topic or map types), domain
modules, and constraints modules that the map or topic can
use,
as well as the degree of topic nesting that is allowed within the
document type.
While the DITA specification includes a starter set of concrete document
types for common combinations of modules, those document types are not
mandatory and, for most
many
DITA users, include more things
definitions
than they need for their documents. In
general, any production use of DITA involves definition of
the
DITA
users are encouraged to create their own customized concrete document
types that include the set
of modules best suited to local requirements. This always
customization
requires
the creation of "local shell" document types, even if all they do is
omit unneeded modules or apply constraints to the standard DITA-defined
vocabulary. Thus
you should expect in any production use of DITA that the first step is
to define local concrete document types.
Note: The
simplest form of local shell is an unaltered copy of one of the DITA
TC-provided shells to which is associated a new public identifier or
absolute
URI,
reflecting ownership of the new shell by its creator. For example, to
create a local shell DTD for generic maps, simply copy the TC-provided
file "map.dtd" to a local location, possibly using a new name for the
file to avoid confusion, and create an entity mapping catalog that binds
the new copy of map.dtd to a public ID or absolute
URI you define, e.g. PUBLIC
"-//example.com/DTD DITA NewMap//EN or urn:public:example.dom/dita/doctypes/map
urn:example.com:names:dita:xsd:newmap.xsd.
Concrete
DITA document types must
SHOULD
follow the implementation design patterns defined in this specification.
This ensures consistency of implementation and also serves to make the
task of creating concrete document types almost entirely
mechanical.
·
Modularization
and integration of design
Specialization
hierarchies are implemented as sets of vocabulary modules, each of which
declares the markup and entities that are unique to a specialization.
The modules must be integrated into a document type before they can be
used.
·
DTD
syntax specialization design patterns
To
be extensible and backward compatible, DITA
requires that
a DTD implementation of structural and domain specialization modules
SHOULD
conform
to well-defined
the
design patterns used
for the DTD shells included as part of the DITA specification and
described in this topic.
·
XSD
schema specialization design patterns
To
be extensible and backward compatible, DITA
requires that
an XML schema implementation of structural and domain specialization
modules SHOULD
conform to well-defined
the design patterns used
for the XML schema shells included as part fo the DITA specification and
described in this topic.
While we can require that
customized concrete document types follow the rules as outlined in the
DITA 1.2 speciication, I don’t think that we can require that they
follow the design patterns or that the design patterns are well enough
specified to allow them to be a requirement. At this stage I think
the design patters are more of a “best practice” than a requirement that
must be followed and so they SHOULD be followed rather than MUST be
followed.
It seems
likely that the section on “Modularization and integration of design”
should be deleted since it is almost entirely repeating information that
has been provided in the main section..
For the page
dita-1.2-spec/arch/20090617/createConstraintsDomainSpec.html
:
I don’t have
any comments on the main topic other than to say that it feels as of
this topic is saying the same thing two or even three times and that
probably isn’t a good idea.
