RE: [dita] some index-range-* issues

["Paul Prescod" <paul.prescod@xmetal.com>]

> -----Original Message-----
> From: Chris Wong [mailto:cwong@idiominc.com] 
> Sent: Wednesday, August 09, 2006 6:41 AM
> To: Yas Etessam; dita@lists.oasis-open.org
> Subject: RE: [dita] some index-range-* issues
> 
> Yas, you are on record as favoring the attribute proposal for 
> implementation purposes. I'm wondering why the existing 
> proposal is hard to implement. They are all XML, after all, 
> so internally you would just reduce them to some ID. 

I think that there is a usability issue in requiring a user to exactly
replicate a bunch of text that they typed elsewhere. What if they change
the text in one place? Then they must remember to track down the other
or cause a broken link.

"""Don't Repeat Yourself (DRY, also known as Once and Only Once) is a
process philosophy aimed at reducing duplication, particularly in
computing. No piece of information should ever be duplicated, because
duplication increases the difficulty of change, may decrease clarity,
and leads to opportunities for inconsistency. "Piece of information" can
be taken quite broadly to include data stored in a database, a program's
source code, or even textual information and documentation. When the DRY
principle is applied successfully, changes to any one part of the
process require changes only in one place. When parts of the process are
repeated in many places, changes can more easily cause things to break
if all those places are not kept in sync."""

 * http://en.wikipedia.org/wiki/Once_and_only_once

Repeating an ID is unavoidable, but IDs can be chosen so that they are
invariant (which is a best practice).

> The other issue that both you and Paul G are eminently 
> qualified to address is the usability issue. The proposed 
> change to index ranges is essentially a switch from 
> element/content-based authoring to an element/@attribute 
> approach. You essentially require that the author come up 
> with an ID to assign to an attribute. Existing XML authoring 
> tools simply don't make attribute editing/viewing easy. 

Any production-quality DITA authoring tool will need to assign IDs
automatically. It will also have a lot of cross-referencing
infrastructure already built in. DITA already has a cross-reference
syntax based on href attributes and this proposal is creating a new one
based upon element content.

> Everything I've heard about user friendly XML authoring says 
> to avoid authoring attributes (which are usually invisible), 
> let alone coming up with IDs for those invisible attributes, 
> let alone authoring matching pairs of those invented IDs for 
> those invisible attributes. Won't this approach be 
> unacceptably unfriendly to your users?

Quite the opposite (speaking for XMetaL). We've invested substantial
effort in making the existing cross-referencing syntax easy to work with
and extending that to index ends is relatively easy.

 Paul Prescod