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: FW: [dita] Groups - DITA 1.1 Issue #40 (IssueNumber40.html) uploaded

Replies below

Michael Priestley

"Paul Prescod" <paul.prescod@blastradius.com> wrote on 07/26/2005 08:03:27 AM:

> Issue: "The keyref attribute is intended to provide a key-based
> referencing scheme, with a level of indirection to allow for remapping
> of targets when content is reused in contexts where the target is
> unavailable, or a new target needs to be substituted, or several targets
> need to be collapsed into one."
> Comments:
> 1. I would propose we consider calling this feature "variables" or "map
> variables" to use terminology more familiar to DITA's target users.
> After reading the proposal I had an epiphany that the goal is to allow
> references to "vary" depending on their map context.

Well, the existing attribute is called "keyref", so to some degree we're tied to existing terminology here. I'd be happy to add the words "variable referencing scheme", to the explanation. "Map variables" to me is too loose a term, since in fact there may be a lot of things that are variable from map to map (kind of their point).

> 2. According to the proposal (Use Case step 2), authors can use keys in
> hrefs. How is this different than using them in keyrefs? Perhaps you
> were thinking of implementing my next point.

As noted at the end of the feature, there are a number of issues to resolve. Specifically, we have keyref, href, and conref as referencing attributes. The approach I recommend is to allow both key-based and path-based referencing in conref and href, making them parallel; and allow only key-based referencing in keyref, and deprecate keyref as redundant on elements such as link that allow both keyref and href.

> 3. What if we simply allowed the map to remap any path at any time?
> Instead of explicitly linking to a key named "copyright", you would just
> link to "copyright.xml" (using standard href/conref, not keyref). Then
> the map could either leave that link alone or remap it:
> <map>
>  <remap original="copyright.xml" target="new_copyright.xml"/>
>  ...
> </map>

When you get into the range of relative paths that might apply to the same target, the remapping could get quite complex. In addition, there is then no clue to the author whether a link is variable or not. I'd be happier allowing both schemes to co-exist, as we do with map-based linking versus embedded links. There is some set up on the part of the original author to enable reuse (ie using maps rather than links, using keys rather than direct paths)but I think the alternative invites confusion. IE, if you see a path to another file, you expect it to be there. If you see a key, you know there's an intermediate step somewhere, and aren't confused or misled by the apparent value of the attribute.

> This would require less planning up-front. Is that a good thing or a bad
> thing? I'm leery of schemes that require you to get the information
> architecture all right at the beginning. What happens when you have to
> deliver a document on a deadline and you find that about half of the
> topics have not been carefully marked up with the appropriate keys? What
> happens when you only need to do the remapping after an unforeseen
> corporate merger?

Same applies to map-based linking, and appropriate use of IDs. I think we could strongly encourage key-based linking, but short of actually removing links and xrefs entirely from the topic I think we have to accept that the same language (DITA) allows both strong reuse and weak reuse models. For me the keyref vs. href distinction is yet another example of an existing duality in the architecture.

> You seem to have considered this "saves a step for the information
> architect" but I don't think you go far enough. The whole keyref
> attribute could just be removed and the mechanism could be triggered by
> the map rather than the topic content.

I think the result would be very counterintuitive for authors. I'd rather say "if authors use keys and maps their content is more reusable and more efficiently managed than if they don't".

> 4 What happens if the topic is viewed, printed or otherwise worked with
> outside of a map context? Links simply do not resolve? Or is there a
> fallback mechanism? Note that my proposal 3 has an implicit fallback
> mechanism: simply use the URL that is embedded in the document.

The fallback you propose would only apply to the original authored context, and would break in every reuse case. This privileges the original authored context, something that DITA's basic map-versus-topics distinction is designed to avoid. You are right that an implication of this feature is that key-based conref, for example, will not be resolveable in an editor without access to a map that defines the targets. But you would want this anyway, for the sake of reusers who are authoring that topic, and want to see the conrefs remapped for their context. So again, this is about making sure that authoring and reuse are equally enabled - reuse is just part of authoring, not a completely different thing.

> 5. Can you give an example of an element where keyref makes sense but
> href doesn't?

We have keyref on keyword and term, for example, to allow association with a target topic but explicitly to allow remapping or removal of the reference, since the reference is inline and would otherwise be as dangerous to reusability as a hardcoded xref.

> 6. I think it is worth deferring the element-level remapping until
> somebody presents a strong requirement for it.

OK, good :-)

> -----Original Message-----
> From: mpriestl@ca.ibm.com [mailto:mpriestl@ca.ibm.com]
> Sent: Monday, July 25, 2005 4:53 PM
> To: dita@lists.oasis-open.org
> Subject: [dita] Groups - DITA 1.1 Issue #40 (IssueNumber40.html)
> uploaded
> The document named DITA 1.1 Issue #40 (IssueNumber40.html) has been
> submitted by Michael Priestley to the OASIS Darwin Information Typing
> Architecture (DITA) TC document repository.
> Document Description:
> Keyref architecture for redirectable referencing (linking and reuse).
> View Document Details:
> http://www.oasis-open.org/apps/org/workgroup/dita/document.php?document_
> id=13757
> Download Document:  
> http://www.oasis-open.org/apps/org/workgroup/dita/download.php/13757/Iss
> ueNumber40.html
> PLEASE NOTE:  If the above links do not work for you, your email
> application
> may be breaking the link into two pieces.  You may be able to copy and
> paste
> the entire link address into the address field of your web browser.
> -OASIS Open Administration

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