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: DITA 1.2 - element aliasing and namespaces


Hi, Energetic TC:

With DITA 1.1 on the train, DITA 1.2 strolls out of the waiting room and onto the platform. So, we may want to take a fresh look at what should be a priority for DITA 1.2

In particular, namespacing has been a perennial issue for DITA as part of both TC conversations and on the user group (http://tech.groups.yahoo.com/group/dita-users/message/4950). A significant challenge is how to correlate a namespaced element with a type on the class attribute and, in particular, how to handle namespaced elements as part of generalization and respecialization of types.

We'd like to bring forward a proposal that DITA 1.2 introduce a general method for element aliasing that has broad value and then treat namespacing as a special case of element aliasing. Once a DITA Specification 1.2 Requirements category exists, I'll add the proposal there, but for the interim, here it is:

Formatted: (See attached file: IssueAliasNamespace.html)
Source: (See attached file: IssueAliasNamespace.dita)


Hoping that's interesting,


Erik Hennum
ehennum@us.ibm.com

Title: DITA Proposed Feature - aliasing and namespacing

DITA Proposed Feature - aliasing and namespacing

Allow an element name to be an alias (with or without a namespace) for its type from the class attribute.

Longer description

The problem: Element names are part of the XML document. There can be good reasons to prefer variant element names.

Culture
An organization might prefer <dl>, <deflist>, or <DefinitionList> as different, appropriate resolutions of the tradeoff between economy and clarity.
Consistency
An organization might prefer to use names from existing vocabularies. For instance, an organization that's familiar with DocBook would likely prefer <variablelist> to <dl>.
Localization
Spanish users would prefer <ejemplo> to <example>.

In addition, DITA has well-known problems with respect to namespacing [1]. Element names must reside in a namespace for some editors. Namespaces are essential to avoid naming collisions between specialized elements created by independent designers and to embed DITA topics as part of compound documents. Some XML users (using both DITA and other markup languages [2]), however, argue that namespace prefixes reduce the usability and should be optional (included only where necessary to avoid collisions). Also, generalization and respecialization have no provision for namespaces.

As a related issue, for types in the DITA class attribute, the module qualifier isn't sufficient to avoid naming collisions because two designers could pick the same module name and element name. As another related issue, DITA specialization can't be extended to foreign vocabularies if the foreign vocabulary already has a non-DITA class attribute.

The solution: Decouple the element name from the type in the class attribute.

  • The default element name is the same as the type name.
  • The document type shell that integrates vocabulary modules can assign a namespace to all elements belonging to a vocabulary or alias specific types to different element names (with or without a namespace).
  • The aliases for one vocabulary module can be packaged as a reusable alias module for inclusion in many document types.
  • Generalization and respecialization operations use the alias when emitting element names.
  • New, generic unaliasing and aliasing transforms convert between the alias and the default element name.

Because processes match the type in the class attribute, introducing aliases for element names doesn't affect most of the existing processing. DITA-aware tools already inspect the class attribute to determine the actual type of the element. Tools that recognize DITA element names but not the DITA class attributes can process the result of the unaliasing transform.

Some references:

[1] http://www.w3.org/TR/xml-names/

[2] http://www.xml.com/lpt/a/1679

Scope

Major

Use Case

Non-professional writers
An organization wants their marketing writers to create structured documents. These writers benefit from additional clarity in the markup, so the designer creates an alias module that renames <dl> to <DefinitionList>, <fig> to <Figure>, <fn> to <Footnote>, and so on. The documents look more formal, but the writers understand what the markup means.
Localized market
A vendor is targeting the Spanish market with their offering. The vendor creates an alias module that renames <example> to <ejemplo> and so on. The Spanish writers can make sense of the markup and embrace the product.
DocBook consistency
An organization has both DocBook and DITA adopters so, to make the DITA content more comprehensible to the DocBook users, creates an alias module that renames <p> to <para>, <li> to <listitem>, <dl> to <variablelist>, and so on. The aliasing and unaliasing transforms allow the same documents to make sense to both the DITA and DocBook heads.
SOAP payload
An IT department want to transmit DITA topics containing trouble ticket descriptions as well as data as part of a SOAP payload. The staff creates alias modules that put the DITA elements into namespaces (with prefixes of topic, concept, and so on ) so the SOAP send and receive functions can process the DITA content.
Parallel invention
One designer creates a DITA domain for documenting XML techniques. Independently, another designer creates a DITA domain for documenting programming techniques. After successful internal adoption, each designer decides to make the domain publicly available. Both domains contain <element> for the XML and programming array senses (and thus, in DITA 1.1, cannot be used in the same document). A DITA adopter installs both plugins and creates alias modules that use namespaces to disambiguate <xm:element> and <pr:element> but that leave the other elements from both domains in the null namespace to provide a unified markup for more usable authoring.

Technical Requirements

Element aliasing requires the following changes:

  • Each vocabulary can have at most one default namespace for its elements. If a default element namespace is provided, the vocabulary must also declare a default prefix for the default element namespace. If a default element namespace isn't provided, the null namespace is the default.
  • The canonical element name for a type consists of the element namespace for the vocabulary module and a local name that's the same as the type name.
  • The design patterns for DTD and XSD change to add a new aliasing module. An aliasing module establishes the aliases for one vocabulary module. The document type shell integrates aliasing modules by importing each module and setting the architectural attributes.
  • The defaulted architectural attributes on the topic or map identify aliasing of a vocabulary module to an element namespace or of one or more types to element names. Two types cannot share an element name.
  • Generalization and respecialization operations change to check the defaulted architectural attributes before emitting element names.
  • The generic aliasing and unaliasing operations are added to the processing definition.

Open issues: Whether there's a strong need to solve attribute aliasing at present and, if so, how to represent that.

While not required for element aliasing, it might be appropriate to consider the closely related namespacing problems with respect to DITA types at the same time. One possible approach:

  • Each vocabulary module can have one namespace for its types. While, for backward compatibility, the vocabulary type namespace cannot be required immediately, it can be strongly encouraged, required for aliasing elements from the vocabulary module, and required in a future version.
  • The full type identifier for a type consists of the vocabulary type namespace plus the type name (either in http style or in Java style as Paul Prescod suggested).
  • A DITA element can have class attribute in the DITA namespace with a defaulted value that declares the type identifiers.
  • Both design and transform modules use the RDF / XSLT technique of a local entity to incorporate the vocabulary type namespace into the DITA namespaced class attribute and into transform expressions that match the DITA namespaced class attribute.
  • New utilities (for instance, using regular expressions in Java or other languages) convert XSLT transforms between existing contains(@class,' module/type ') expressions and new contains(@dita:class,' &module.ns;type ') expressions.
  • The older class attribute can be deprecated but publishers of public specializations encouraged to support both formats during transition.

Costs

Largest cost is for coming up with a backward-compatible extension to the existing DTD and XSD design patterns and implementing that change.

Other hits are modifying the generalization and respecialization transforms and implementing aliasing and unaliasing transforms.

Benefits

Avoiding naming collisions, viability for namespace-required environments while conserving usability where not required, and adapting to local culture while reserving specialization for semantics.

Time Required

If successfully backward compatible, no forced changes for adopters though small encouraged change for every specialization publisher to declare type and element namespace.

IssueAliasNamespace.dita



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