Re: Links that are both local and cross-deliverable in shared topics


ekimber@contrext.com
 

DITA 1.3 introduced the ability to author links between two root maps, which is what you want here.

(You can find a small working sample here: https://github.com/dita-community/dita-test-cases/tree/master/cross-deliverable-links)

The basic technique is you define a mapref with a @scope value of "peer" that points to the root map of the target document (the document you are linking to) and a @keyscope value by which you can then refer to keys in the target root map.

So for your example, in the map for Book A you would give Topic 1 the "Topic_01".

Topics used in Book A can refer to Topic one by the unqualified key "Topic_01": <xref keyref="Topic_01"/>

In the map for Book B you would create this keydef to associate a key scope for Book A:

Book B:

<map>
...
<mapref keyscope="book_A" scope="peer" href="..\BookA\book_a.ditamap" format="ditamap"/>
...
</map>

Then in a topic used in Book B you can refer to topic 1 as:

<xref keyref="book_A.Topic_01"/>

Per the rules we defined for scope="peer" in DITA 1.3, this explicitly means "Go to the topic with the key 'Topic_01' as declared in the root map associated with the key scope 'book_A' in this root map."

If you need to be able to have topics that refer to Topic_01 also shared between books A and B, you can enable having all references to Topic_01 be the same in one of two different ways:

1. Use another level of indirection that goes from a global key ("Topic_01") to the appropriately-qualified key in the context of a given map:

Book A:

<topicref keys="Topic_01" href="topics/topic-01.dita"/>

Book B:

Resource-only topicref that points to topic-01 used from Book A:

<keydef keys="Topic_01" keyref="book_a.Subject_of_Topic_01"/>

With this approach, topics can blindly refer to key "Topic_01" without worrying about where the topic is used.

2. Put a key scope name on the Book A map so that a scope-qualified reference to key "book_a.Topic_01" will resolve in the context of Book A as well as in Book B:

Book A:

<map keyscope="book_a" ...>
...
</map>

An unqualified reference to key "Topic_01" from Book A will still work because the key and reference will be in the same scope.

Note that OxygenXML supports resolution of cross-deliverable links in the editor, so you can use it to validate your content as authored.

Cheers,

E.


--
Eliot Kimber
http://contrext.com


´╗┐On 6/9/21, 11:57 AM, "Chris Papademetrious" <main@dita-users.groups.io on behalf of chrispitude@gmail.com> wrote:

We have two books that share a common topic, called "Shared Topic":

Book A:

* Topic 1
* Topic 2
* Shared Topic

Book B:

* Topic 3
* Topic 4
* Shared Topic

In "Shared Topic", we want to include a cross-reference to "Topic 1", such that it is a local link in Book A and a cross-book link in Book B.

Each book has the other book defined as a peer book, with mapref-level keyscopes:

<bookmap>
<title>Book A</title>
<mapref href="bookB.ditamap" ... scope="peer" keyscope="B"/>
...
</bookmap>


<bookmap>
<title>Book B</title>
<mapref href="bookA.ditamap" ... scope="peer" keyscope="A"/>
...
</bookmap>

If I write <xref keyref="topic1"/>, the link works in book A but not book B.

If I write <xref keyref="A.topic1"/>, the link works in book B but not book A.

So I tried adding local (map-level) keyscopes to each book, which "2.3.4.2 Keyscopes" <http://docs.oasis-open.org/dita/dita/v1.3/errata02/os/complete/part2-tech-content/archSpec/base/keyScopes.html> suggests would allow references to A.* to resolve locally:

<bookmap keyscope="A">
<title>Book A</title>
<mapref href="bookB.ditamap" ... scope="peer" keyscope="B"/>
...
</bookmap>


<bookmap keyscope="B">
<title>Book B</title>
<mapref href="bookA.ditamap" ... scope="peer" keyscope="A"/>
...
</bookmap>

Unfortunately, Oxygen doesn't create cross-book links correctly with this map configuration - it concatenates the mapref-level and map-level keyscopes (for example, B.B.topic1 instead of B.topic1) instead of treating them as a union as described in the spec.

Has anyone run into this situation before, or am I charting new territory here?

- Chris

P.S. On the publishing side, we resolve cross-book links with this DITA-OT plugin <https://github.com/chrispy-snps/DITA-fix-xbook-html-links/>. So mostly, I just need to solve the authoring and DITA-correctness aspects.

Join main@dita-users.groups.io to automatically receive all group messages.