One key difference between DITA and DocBook is DocBook has no controlled
extension mechanism comparable to specialization, so there is *only*
customization with DocBook. By contrast, DITA enables configuration and
extension and essentially disallows the type of customization DocBook
assumes (that is, direct modification of content models, adding new,
non-standard element types, etc.).
So I continue to suggest that the features DITA provides are materially
different from what things like DocBook provide and are not, for most part,
customization.
Cheers,
E.
On 7/2/09 12:07 PM, "Dana Spradley" <> wrote:
> I've started to look into some other OASIS specs, and a "Customization" or
> "Extensibility" section like I describe is fairly typical:
>
> http://docs.oasis-open.org/xliff/v1.2/cs02/xliff-core.html#Struct_Extension
> :
>
> At times, it may be useful to extend the set of information available in an
> XLIFF document by inserting constructs defined in various other XML
> vocabularies. You can add non-XLIFF elements, as well as attributes and
> attribute values. Adding elements and attributes use the namespace mechanism [
> XML Names]. Adding attribute values generally involves preceding the value by
> an "x-" (e.g. <context context-type='x-for-engineers'>).
>
> Although XLIFF offers this extensibility mechanism, in order to avoid a
> nimiety of information and increase interoperability between tools, it is
> strongly recommended to use XLIFF capabilities whenever possible, rather than
> to create non-standard user-defined elements or attributes.
>
>
>
> http://docs.oasis-open.org/docbook/specs/docbook-5.0-spec-cs-02.html#s.custom
> :
>
> From the very beginning, one of the goals of DocBook has been that users
> should be able to produce customizations that are either subsets of extensions
> of DocBook.
>
> Customization is possible in DocBook V4.x, but because of the intricacies of
> XML DTD syntax and the complex and highly stylized patterns of parameter
> entitiy usage in DocBook, it's not as easy as we would like it to be.
>
> In DocBook V5.0, we hope to take advantage of RELAX NGs more robust design
> (and it's lack of pernicious determinism rules) to make customization easier.
>
> Three schema design patterns get us most of the way there...
>
>
>
> -----Original Message-----
> From: Dana Spradley
> Sent: Wednesday, July 01, 2009 2: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>
