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


Kristen James Eberlein
 

I'll rework my answer slightly:

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 for now and the immediate future be unique to the specific company.

It's not impossible, but it involves many, many variable and would also require an extensive rework of DITA-OT.

At the last DITA-OT meeting, we decided to add a caveat to the documentation stating that DITA-OT does not now -- and does not plan in the future -- to implement cross-publication linking.

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 8:34 AM, Eliot Kimber ekimber@... [dita-users] wrote:
 

Kris says:

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.

I don't think it's quite that dire: it would certainly be possible to implement a general solution for cross-deliverable linking, i.e., in the context of DITA Open Toolkit, but it would be a lot of work because, as Kris says, there are a lot of variables, meaning that any such solution would have to support a large number of options and provide appropriate extension points. It's unlikely to happen soon unless somebody funds the work.

In addition, DITA-aware content management systems should be able to implement support for cross-deliverable linking because they presumably have access to all knowledge about the content they manage and how it is processed for delivery. If this is a feature you need and you're using a commercial CMS system, you should ask them "what's your support for cross-deliverable links?" (which, by the way, implies the question "what's your support for DITA 1.3?").

However, the Open Toolkit team is working on features that would enable implementing such a general solution, in particular, a general "project" mechanism that lets you capture in a single project definition the relationship between a root map or maps, transformation details, filtering details, and so on.

This kind of project mechanism is necessary for any general cross-deliverable linking solution as you must have a way to represent a "publication" as an object that includes both the source (the root map and all its dependencies) and all the ways that it is (and has been) published, so that you can distinguish and talk about the different deliverables produced from a given root map in order to then relate those deliverables to the deliverables produced from other root maps.

The other big challenge in Open Toolkit is capturing the relationship between elements in the source that are link targets from other deliverables and the anchors those elements become in a given deliverable. Because Open Toolkit lets any extension modify the details of how deliverables are generated, including the anchors in those deliverables, there has to be some sort of element-to-anchor record or database that is updated whenever a deliverable is produced. Open Toolkit doesn't currently have this mechanism and was never architected with this requirement in mind, so retrofitting it will be a challenge, but it's definitely doable given time and resources.

I would love to be able to implement this kind of general solution but it's definitely not something I can do nights and weekends on my own...

Cheers,

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


On 7/3/19, 6:35 AM, "Kristen James Eberlein kris@... [dita-users]" wrote:

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.