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
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.
|