[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [dita] Re: DocBook vs DITA customization (was RE: [dita] some comemnts on the Draft DITA 1.2 architecture spec.)
Hi Dana, While I could take your question to the DITA Adoption TC, this is not something anybody has brought up to-date. The folks on the Adoption TC appear to be in favor of the rules DITA enforces. I tend to agree with Eliot that loosening DITA would undermine the rationale behind the whole concept. I don't see that keeping the screws tight would lead to folks not adopting DITA. In fact, the opposite is true. I've seen first-hand projects where folks have claimed their content to be either DocBook or DITA compliant, and in these cases they were not at all compliant or interchangeable with the standard they claimed to be in compliance with. I had to fix the content in order to process it with the other content that was compliant. These were projects where different organizations shared content, for instance an OEM vendor providing content for integration into another vendor's solution. One of the things the Adoption TC is working on is a compliance article and test suite folks can use to check whether their DITA implementation is compliant with the standard (or to test how compliant they are). This is work in progress and we are far from ready with it yet, but if we loosen the screws I fear the whole compliance thing may just crumble. Gershon -----Original Message----- From: Dana Spradley [mailto:dana.spradley@oracle.com] Sent: Monday, July 06, 2009 9:34 PM To: Eliot Kimber; Ogden, Jeff; dita Subject: RE: [dita] Re: DocBook vs DITA customization (was RE: [dita] some comemnts on the Draft DITA 1.2 architecture spec.) I don't think we're fundamentally in disagreement, Eliot - it's more a matter of tone and nuance. I do disagree, though, that DITA has nothing really distinguishing to offer people who aren't interested in blind interchange. DITA has a great deal to offer someone shopping around for a standard to base their customization on - not only the topic orientation you mention, but code reduction through class attributes tracing element relationships, a well developed element and attribute vocabulary, content-based tables, conrefs, maps, etc. and authoring and publishing tools that support these features in an agnostic fashion, without requiring full DITA conformance. I think we limit DITA's market acceptance by language in the specification that "tightens the screws," as you say, on people considering DITA who see these features' value, but who see little or no value in their particular case for blind interchange. As you say, "Of course, within an enterprise or community, you are free to do whatever you want, you just can't call it DITA conforming if it's not DITA conforming." That's all I'm really asking for right now, I think - recognition in the standard that people may choose to apply it in this fashion - the way that most other OASIS standards do, through a section that glances at true customization at the end. Long term, though, perhaps we should revisit the issue of the cost that strict conformance in support of blind interchange and round-trip generalization places on the architecture and people who adopt it, and consider loosening some requirements and turning them into recommendations or making them entirely optional, or defining a "loose" version of DITA that does this. I wonder where members of the Adoption Committee stand on this issue? It seems reasonable to allow DITA to be different things to different people to a certain extent. --Dana -----Original Message----- From: Eliot Kimber [mailto:ekimber@reallysi.com] Sent: Monday, July 06, 2009 10:39 AM To: Dana Spradley; Ogden, Jeff; dita Subject: [dita] Re: DocBook vs DITA customization (was RE: [dita] some comemnts on the Draft DITA 1.2 architecture spec.) Unless I'm misunderstanding what you mean by "DocBook-style customization", I could not disagree more. That DITA disallows uncontrolled extension is the reason DITA works at all. The DITA standard *must* disallow it in order for DITA to be what DITA is, that is, a mechanism that enables blind interchange of content in a way that no other XML application can or does. Note that everything in DITA about modular information and topic-oriented writing is really not distinguishing, or for a large potential community of users, particularly interesting. What is distinguishing and compelling about DITA is the specialization feature and the attendant constraints around conref and map composition that enable blind interchange and interoperation of *any* conforming DITA content with any other conforming DITA content. That is the one aspect of DITA that *no other standard* offers and, without which, they all fail, to one degree or another, to deliver on the promise of generalized markup to enable interchange of content and processing. Before DITA, the idea that XML (and SGML before it) enabled interchange was a Big Lie because it provably didn't work. With DITA it works. But it works because DITA tightens the screws. That is, content that uses DITA as a base but does not conform to the DITA constraints *cannot be* DITA content as sanctioned by the DITA standard because such content *is not reliably interchanged*. Of course, within an enterprise or community, you are free to do whatever you want, you just can't call it DITA conforming if it's not DITA conforming. The point of the current text, certainly as I understood it's motivation, was to make it clear that things that are SOP in other XML applications are *absolutely not allowed* in DITA because they break interchange and operability but that the TC recognizes there are practical reasons for doing those things within your own purview and we just want to be clear that, having done those things, what you have is not conforming DITA content. Cheers, E. On 7/6/09 12:26 PM, "Dana Spradley" <dana.spradley@oracle.com> wrote: > I agree on your characterization of the difference, Eliot - but > disagree that DITA should completely disallow DocBook-style customization. > > Different installations have different needs. SGML and XML have a long > tradition of using standard vocabularies like DocBook and DITA as the > basis of customized vocabularies more closely attuned to an > installation's actual content. > > The extension mechanisms DITA supplies are limited, and require a fair > amount of overhead with little benefit to installations that support > only a single flavor of DITA, and do not share their documents with other installations. > > While we can and should recommend their use - I don't think we can or > should dictate against DocBook-style customization in the DITA standard. > > It only makes us look narrow, shortsighted, and a little foolish to do so. > > --Dana > > -----Original Message----- > From: Eliot Kimber [mailto:ekimber@reallysi.com] > Sent: Thursday, July 02, 2009 11:58 AM > To: Dana Spradley; Ogden, Jeff; dita > 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" <dana.spradley@oracle.com> 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_Ext >> ension >> : >> >> 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:jogden@ptc.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 >> >> 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:dana.spradley@oracle.com] >> 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:jogden@ptc.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:joann.hackos@comtech-serv.com] >> 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. >> >> joann.hackos@comtech-serv.com >> >> Skype joannhackos >> >> >> >> >> --------------------------------------------------------------------- >> ----- >> >> From: Dana Spradley [mailto:dana.spradley@oracle.com] >> 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:jogden@ptc.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: ekimber@reallysi.com <mailto:ekimber@reallysi.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> > > > --------------------------------------------------------------------- > To unsubscribe from this mail list, you must leave the OASIS TC that > generates this mail. Follow this link to all your TCs in OASIS at: > https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php > ---- Eliot Kimber | Senior Solutions Architect | Really Strategies, Inc. email: ekimber@reallysi.com <mailto:ekimber@reallysi.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> --------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php --------------------------------------------------------------------- To unsubscribe from this mail list, you must leave the OASIS TC that generates this mail. Follow this link to all your TCs in OASIS at: https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]