Re: [dita] xrefs outside the map topics

[Eliot Kimber <ekimber@contrext.com>]

For this use case the addresses must be keys. 

It is on the key definition that you determine whether the target is local to the current map or needs to be a cross-deliverable reference (key is in a peer map) or an external-scope reference (target is in some non-DITA thing for which you know the URL it is published at). The author of the topic (and thus of the xref) cannot, in the general case, now where the topic will be used or how it will be packaged and therefore cannot possibly know what value to specify for @scope (or even @format). That knowledge is available only to the authors of the maps that use the topic. Thus the information has to be on the keys defined in those maps.

An xref element should never specify scope directly unless it is unalterably to an external-scope resource (and even then going through a key reference is the better practice).

The only other alternative is to have the link elements be conditional on the delivery target (e..g, HTML vs. PDF) but that has obvious limitations since it presumes to know the both the set of possible deliverable targets and the packaging decisions chosen for each one.

In the face of reuse, indirect addressing is a practical requirement when you have embedded links.

Cheers,

E.

----

Eliot Kimber, Owner

Contrext, LLC

http://contrext.com

From: dita <dita@lists.oasis-open.org> on behalf of Jim Tivy <jimt@bluestream.com>
Date: Monday, May 23, 2016 at 6:41 PM
To: dita <dita@lists.oasis-open.org>
Subject: [dita] xrefs outside the map topics

Hi Folks

 

I am unsure on what the Dita 1.3 spec is recommending on this use case.

 

UseCase:

In the context of a CMS there are often multiple books within a product version and multiple product versions within multiple products.  In this sea of content there has to be some checks and constraints to help authors find appropriate content.  As well, authors may in one case publish a set of books as one large book of HTML topics and in other situations just publish each of the books in a single PDF publish. 

What does DITA recommend with respect to xrefs that can potentially reference topics outside the topics explicitly listed in a given map.  For example:

- I insert an xref element into TopicA.dita with scope=”local” and the href references TopicB.dita.

- I have a simple root map MyDoc.ditamap with only one topicref that references TopicA.dita”.

Now I wish to publish HTML for MyDoc.ditamap.

Should the reference from TopicA to TopicB be considered an error, warning or fully allowed by a processor.  Is there special consideration for TopicB because it is not in MyDoc.ditamap?

 

I realize the best practice is not to use an xref but rather use a relationship table or a key.  But if someone uses an xref for the TopicA--->TopicB reference what does the spec recommend?

- Should or Must a processor produce a warning or error?

- Is there a particular part of the 1.3 spec that deals with a recommended treatment of this use case above.  I see references in the scope attribute that refer to the setting of “local” or “peer” according to the “current set” and “current information set” – but is there something else that addresses this situation or defines what  current information set means.

- As a side note there seems to be a few different terms used in the spec: information set, current set, current information set, information unit – perhaps a definition of “information set” would help us in the future.

 

cheers

Jim Tivy - Bluestream