I feel very strongly that we need to have a real conformance clause in the
spec--without such a clause, it's not a standard.
Also, I believe OASIS rules now require us to have a conformance clause. I'm
willing to take responsibility for that part of the spec.
Cheers,
E.
On 7/6/09 11:35 AM, "Dana Spradley" <> wrote:
> 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/conforman
> ce1.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.:
>
> a.. Shells: Vendors MUST support, implementors SHOULD use
> b.. Constraints: Vendors MUST support, implementors SHOULD use
> c.. Specialization: Vendors MUST support, implementors MAY use
> d.. 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.
>
>
>
>
----
Eliot Kimber | Senior Solutions Architect | Really Strategies, Inc.
email: <mailto:>
office: 610.631.6770 | cell: 512.554.9368
2570 Boulevard of the Generals | Suite 213 | Audubon, PA 19403
www.reallysi.com <http://www.reallysi.com> | http://blog.reallysi.com
<http://blog.reallysi.com> | www.rsuitecms.com <http://www.rsuitecms.com>
