Re: Handle cross-book xrefs in large book collections? #linking


Kristen James Eberlein
 

I want to emphasize a point that Eliot makes about 2/3rd the way through his e-mail:

"The challenge, as you point out, is in the processing ... A general solution for this processing is challenging, but a local solution need not be."

A general solution is indeed challenging, maybe impossible: Too many variables hinge on the specific details of a company's DITA implementation.

So, folks, please do not look for an interoperable, off-the-shelf solution for cross-publication linking. The TC has provided some specific markup, but the actual design (and implementation) for cross-publication linking will always be unique to the specific company.

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 7/3/2019 7:23 AM, Eliot Kimber ekimber@... [dita-users] wrote:
 

Markup for cross-book links is provided for in DITA 1.3.

You define a topicref that points to the root map of the target publication and specify a @scope of "peer" and a @keyscope value, where the @keyscope need to be unique for each target map:

scope="peer"
keyscope="book2"
href="book2.ditamap"
format="ditamap"
>
Book 2


By the rules of DITA 1.3 this means explicitly that the target map is the root of a separate key space.

You then use scoped key references to refer to keys in the target publication, using the keyscope you specified:

See Book 2 introduction for more information



So in the map for Book 1 that wants to point to targets in Book 2, you have:



scope="peer"
keyscope="book2"
href="book2.ditamap"
format="ditamap"
>
Book 2

...


References to targets in book 2 can then be created like so:



See Book 2 introduction for more information





Note that the reference to key "introduction" in book 2 from the topic as used by book 1 is completely resolvable *in the source*--there is no ambiguity at all about what the intent of the source is. Oxygen 21, for example, handles these links perfectly.

The challenge, as you point out, is in the processing: A processor producing a particular deliverable from book 1 has to know how to generate a reference to the appropriate *delivered* version of whatever the key "introduction" becomes in the delivered book 2.

A general solution for this processing is challenging, but a local solution need not be.

In a local solution you can take advantage of your control over the editorial rules and the processing infrastructure in order to simplify things. For example, you might know that links from PDFs should always be to HTML and you know the rules for how URLs of published topics will be constructed based on the associated keys, that sort of thing. You can just build that knowledge into your processing extensions.

More generally, for any cross-book link in the source you have to know what the target deliverable should be for the deliverable you're producing, you have to know what the target anchor in that deliverable is or will be, and you have to know what the URL to the deliverable itself is, either relative to the deliverable you're producing or an absolute URL.

Cheers,

E.
--
Eliot Kimber
http://contrext.com


On 7/2/19, 8:18 AM, "chrispitude@... [dita-users]" wrote:

Hi all,

How are you handling cross-book references in DITA?

For example, let's say I have a bunch of books that I want to publish in PDF and HTML5 online help formats. The book collection is too large to be published monolithically; each book must be published separately.

I want to reference topic B1 in book B from topic A1 in book A. How would I do this? What work is needed to make sure the links would work in an output PDF? What about in the online help?

I know this likely requires some work in the publishing pipelines, so I'm interested to hear how others have solved this problem.

Thanks!

- Chris












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