OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[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" <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_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: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> 



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]