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] ITEM: Meaningful Values for type= on xref and topicref

We can argue if this was or wasn't a "bug" in the approved DITA 1.0 and 1.1 specifications, but it doesn't really matter since the "fix" being proposed is incompatible with what that DITA 1.0 and 1.1 called for. We shouldn't be making incompatible changes in a 1.x version and certainly not at this late stage in the DITA 1.2 cycle.  Something like this requires a full proposal, dissuasion, and a vote.

Note that this is not just an issue for implementors.  @type is something that can be set by authors.  And the proposal that is currently on the table would make existing documents that use what are perfectly valid values such as "fig" or "fn" rather than "topic/fig" or "topic/fn" invalid.  We can't do that.

We might be able to allow both the old and new values, but I think even that would be better left until DITA 1.3.


-----Original Message-----
From: Eliot Kimber [mailto:ekimber@reallysi.com]
Sent: Sun 7/5/2009 9:35 AM
To: Gershon Joseph (gerjosep); Ogden, Jeff; dita
Subject: Re: [dita] ITEM: Meaningful Values for type= on xref and topicref 
On 7/5/09 6:40 AM, "Gershon Joseph (gerjosep)" <gerjosep@cisco.com> wrote:

> I'm wondering whether we should not give this change more thought before
> throwing it into 1.2... The domain names are not usually exposed to the
> users. We may wish to think through how this would impact users. Since
> @class is not supposed to be in the source XML content (processors
> insert it later when parsing against the DTD or schema), this change may
> impact authoring in ways we have not considered. I'm hesitant to rush
> this into 1.2 for these reasons. Does anyone else share my concerns, or
> do y'all feel that because this is an edge case that only impacts
> specializations that use official DITA element names, we don't need to
> concern ourselves with such usability hits?

The issue is not specializations that use official DITA element names but
simply having two domains not intended to be used in the same shell that
happen to declare the same local name. Specializations cannot use base names
defined by the standard and should certainly avoid, as a matter of practice,
any names defined in other standard-defined specialized vocabulary modules.

The issue is two non-standard specializations that both declare the same
local name (e.g., multiple-choice as a specialization of lcSingleSelect in
one case and lcAssessment in another case) but are not intended (or
expected) to be integrated into the same shell but might be integrated into
the shells of topics that are part of the same local or peer information

In that case, you could have a topic-to-topic crossref where the local name
alone is not sufficient to determine the intended type of the cross
reference target, meaning a processor would not be able to validate whether
or not the target instance satisfies the intended type constraint (because
the constraint is underspecified, being only a local name and not a
module-qualified name).

This is probably unlikely to happen in the case of a topic or map set that
is entirely under the control of one information architect, but could easily
happen when two data sets developed by different communities interoperate,
for example, when an information supplier licenses content to an information
consumer and both are DITA users. In that case, the licensee might author
topics that reference topics provided by the supplier. Since both data sets
were originally designed without knowledge of each other, the possibility
exists for duplicate local names in different domain or topic modules.

I see this possibility increasing when one of the likely uses of
specialization is to provide more friendly names for standard-defined names,
which is already effectively standard practice for use of the L&T
specializations. And since content based on the L&T specializations is one
of the more compelling uses for content that, by its nature, is intended for
wide re-use, this starts to feel like less of an edge case and more of a

The potential implementation cost is to implementors of processors that
check type= constraints, either during authoring or during rendition.
However, if we assume that for a given processor that check is done by a
single code component (e.g., a checkXRefType() method of some DITA utility
class), the implementation cost will be very small. Since this is standard
engineering practice, it seems unlikely it would not be the case for most,
if not all, DITA-aware tools.

The change for authors would be in the case of creating xrefs where the
author needs to specify the target element type and that type is defined in
a non-standard specialization module. However, authors don't normally need
to define the target type. The type attribute is primarily useful on
specializations of xref that set a fixed or default type value in order to
limit what the specialized xref is allowed to point to. So authors would not
normally be affected by this change since it would be reflected in schemas,
not instances.

Remember too: this is a straight up design bug, something that has been
broken in DITA since 1.0. It's only now that specialization is becoming more
wide spread that we've even realized the problem but it is a real problem.

Obviously not the end of the world if this doesn't make it into 1.2, but it
seems like an easy fix with minimal cost to implementors.



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]