Hi Erik--
This looks very good and comprehensive.
Given that, it would nice if it would handle attribute renaming too -
as you suggest it might.
And I think it might also be the most appropriate place to handle the
long-deferred project to allow adding implementation-specific metadata
attributes to arbitrary elements.
Such attributes could be considered renamings of contained data or
associated data-about elements whose name attribute has the same name
as the implementation-specific attribute's name.
This makes more sense to me than evolving a
specialization/generalization mechanism for such attributes, given that
data elements, like implementation-specific attributes, have no generic
processing.
Something to think about while waiting on the platform for the train to
arrive, anyway.
--Dana
Erik Hennum wrote:
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
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.