[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [dita] some comemnts on the Draft DITA 1.2 architecture spec.
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" <firstname.lastname@example.org> 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:email@example.com] > 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 > > 22.214.171.124) Conditional Processing (filtering and flagging) > > 126.96.36.199) Conref processing > > 188.8.131.52) Merging properties between maps and topics including key > and keyref processing > > 184.108.40.206) 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 > > 220.127.116.11) Conditional Processing (filtering and flagging) > > 18.104.22.168) Conref processing > > 22.214.171.124) Merging properties between maps and topics including key > and keyref processing > > 126.96.36.199) 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:firstname.lastname@example.org] > 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:email@example.com] > 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:firstname.lastname@example.org] > 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. > > email@example.com > > Skype joannhackos > > > > > -------------------------------------------------------------------------- > > From: Dana Spradley [mailto:firstname.lastname@example.org] > 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:email@example.com] > 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: firstname.lastname@example.org <mailto:email@example.com> 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>