Topics

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


Chris Papademetrious
 

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




David Duperron
 

Would be very interested in any feedback on that subject too! :)


despopoulos_chriss
 

I have a partial solution...  We use DITA for online help and for PDFs.  The online help is is actually HTML of all the documentation, while the PDFs are single files for each individual "book".  Obviously, in the HTML help we want xrefs to link to any content, no matter which "book" it belongs to.  That's easy if you just use one  ditamap to generate the entire help system.

For PDF, if you generate each book individually, these cross-book xrefs will be unresolved. We use oXygen  CSS/Help templates to generate our PDFs, and that gives us a hook to handle the situation. It involves the @outputclass and @deliveryTarget attributes in the xref element, and the com.oxygenxml.pdf.css.xsl.merged2html5 extension point in the oXygen CSS-to-PDF template.

A paragraph with an xref looks something like this:
<p>See <xref outputclass="PDF_External" deliveryTarget="User Guide"
          href="Budget_Discounts.xml#Budget_Discounts">Price Adjustments</xref>.</p>

Then we map a custom XSL file to the oXygen extension point, and include this template:
    <xsl:template match="xref[@broken-link = 'true']">
        <xsl:choose>
            <xsl:when test="@outputclass = 'PDF_External'">
                <xsl:text>&quot;</xsl:text>
                <xsl:value-of select="text()"/>
                <xsl:text>&quot; in the </xsl:text>
                <xsl:element name="i">
                    <xsl:value-of select="@deliveryTarget"/>
                </xsl:element>
            </xsl:when>
            <xsl:otherwise>
                <xsl:element name="div">
                    <xsl:attribute name="style">background-color:red</xsl:attribute>
                    <xsl:text>BROKEN LINK!!! </xsl:text>
                    <xsl:value-of select="text()"/>
                </xsl:element>
            </xsl:otherwise>
        </xsl:choose>
    </xsl:template>

The oXygen process generates an intermediary XML file that sets @broken-link for an xref. The entry point runs our XSLT over that intermediary file.  So if the xref does not resolve, then we get one of two results. 

If @outputclass is PDF_External, then we generate the following in the PDF...  See "Price Adjustments" in the User Guide.  It picks up the xref content and it picks up the @deliveryTarget value to produce that string.

If @outputclass is NOT set to PDF_External, we get a big red BROKEN LINK that tells us we messed up.

A few caveats...
* No, this does not generate a link to the external PDF file.
* Yes, this relies on the oXygen CSS to PDF transform templates. One could probably do similar stuff.
* Yes, we hard-code the xref content in our DITA files... We do that anyway.

But this works for us...  I can incorporate content with external xrefs into my release notes, and I can generate PDF books out of subsets of our HTML product.  Elegant and perfectly adherent to the DITA dogma?  No...

Hope that helps...      cud


Megan Bock
 

We use paired key definitions, with all links that leave the PDF going to the HTML. 

During publishing, one or the other of the paired key definitions is used based on the output type. This gets us the correct href and scope attributes and lets us control the link text differently. (For example, use PDF Book Title: Topic title for the keys used by PDF so that the user could find the topic in the other PDF if they have it, but just show the topic title for HTML.) 

We use an external link indicator on all external links in all outputs, so users know what to expect looking at any link before they click. 

I gave up on trying to open a PDF from another one a long time ago. 

Sent from my mobile

On Jul 2, 2019, at 7:58 AM, despopoulos_chriss@... [dita-users] <dita-users@...> wrote:

 

I have a partial solution...  We use DITA for online help and for PDFs.  The online help is is actually HTML of all the documentation, while the PDFs are single files for each individual "book".  Obviously, in the HTML help we want xrefs to link to any content, no matter which "book" it belongs to.  That's easy if you just use one  ditamap to generate the entire help system.

For PDF, if you generate each book individually, these cross-book xrefs will be unresolved. We use oXygen  CSS/Help templates to generate our PDFs, and that gives us a hook to handle the situation. It involves the @outputclass and @deliveryTarget attributes in the xref element, and the com.oxygenxml.pdf.css.xsl.merged2html5 extension point in the oXygen CSS-to-PDF template.

A paragraph with an xref looks something like this:

See           href="Budget_Discounts.xml#Budget_Discounts">Price Adjustments.


Then we map a custom XSL file to the oXygen extension point, and include this template:
   
       
           
               
               
                &quot; in the
               
                   
               
           
           
               
                    background-color:red</xsl:attribute>
                    BROKEN LINK!!!
                   
               
           
        </xsl:choose>
   

The oXygen process generates an intermediary XML file that sets @broken-link for an xref. The entry point runs our XSLT over that intermediary file.  So if the xref does not resolve, then we get one of two results. 

If @outputclass is PDF_External, then we generate the following in the PDF...  See "Price Adjustments" in the User Guide.  It picks up the xref content and it picks up the @deliveryTarget value to produce that string.

If @outputclass is NOT set to PDF_External, we get a big red BROKEN LINK that tells us we messed up.

A few caveats...
* No, this does not generate a link to the external PDF file.
* Yes, this relies on the oXygen CSS to PDF transform templates. One could probably do similar stuff.
* Yes, we hard-code the xref content in our DITA files... We do that anyway.

But this works for us...  I can incorporate content with external xrefs into my release notes, and I can generate PDF books out of subsets of our HTML product.  Elegant and perfectly adherent to the DITA dogma?  No...

Hope that helps...      cud


ekimber@contrext.com
 

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:

<mapref keys="book2-rootmap"
scope="peer"
keyscope="book2"
href="book2.ditamap"
format="ditamap"
>
<topicmeta><navtitle>Book 2</navtitle></topicmeta>
</mapref>

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:

<p>See <xref keyref="book2.introduction">Book 2 introduction</xref> for more information</p>

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

<map>
<title>Book 1</title>
<mapref keys="book2-rootmap"
scope="peer"
keyscope="book2"
href="book2.ditamap"
format="ditamap"
>
<topicmeta><navtitle>Book 2</navtitle></topicmeta>
</mapref>
...
</map>

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

<topic id="t1"><title>Topic 1</title>
<body>
<p>See <xref keyref="book2.introduction">Book 2 introduction</xref> for more information</p>
</body>
</topic>

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]" <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


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













ekimber@contrext.com
 

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]" <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 <http://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:

<mapref keys="book2-rootmap"
scope="peer"
keyscope="book2"
href="book2.ditamap"
format="ditamap"
>
<topicmeta><navtitle>Book
2</navtitle></topicmeta>
</mapref>

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:

<p>See <xref keyref="book2.introduction">Book
2 introduction</xref> for more information</p>

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

<map>
<title>Book 1</title>
<mapref keys="book2-rootmap"
scope="peer"
keyscope="book2"
href="book2.ditamap"
format="ditamap"
>
<topicmeta><navtitle>Book
2</navtitle></topicmeta>
</mapref>
...
</map>

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

<topic id="t1"><title>Topic 1</title>
<body>
<p>See <xref keyref="book2.introduction">Book
2 introduction</xref> for more information</p>
</body>
</topic>

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]" <mailto:chrispitude@...[dita-users]>
<dita-users@...> <mailto: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


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


































Chris Papademetrious
 

Replying to a previous discussion...

Radu provided me with a DITA-OT plugin that preserves @keyref information in <xref> elements when publishing to xhtml or html5:

<p class="p">You can also see <span class="xref" origkeyref="B.topic_B">this topic in book B</span> and <span class="xref" origkeyref="C.topic_C">this topic in book C</span>.</p>

This is half the solution - so far so good! Now I need to push and preserve the @keys value (including any nested scopes) from the topicrefs into the final XHTML or HTML5 output. This preservation must handle nested subtopic references (within a topic file):

   <topicref href="topic_C.dita" keys="topic_C">
     <topicref href="topic_C.dita#id_C_subtopic" keys="topic_C_subtopic"/>
   </topicref>

and preserve it something like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="copyright" content="(C) Copyright 2019" />
<meta name="DC.rights.owner" content="(C) Copyright 2019" />
<meta name="DC.type" content="topic" />
<meta name="DC.title" content="Topic in Book C" />
<meta name="DC.relation" scheme="URI" content="topic_C.html#id_C_subtopic" />
<meta name="DC.format" content="XHTML" />
<meta name="DC.identifier" content="id_C" />
<link rel="stylesheet" type="text/css" href="commonltr.css" />
<title>Topic in Book C</title>
</head>
<body id="id_C" @origkeys="topic_C">
   <h1 class="title topictitle1" id="ariaid-title1">Topic in Book C</h1>
   <div class="body">
      <p class="p">Welcome to the topic in book C!</p>
      <p class="p">You can also see <span class="xref" origkeyref="A.topic_A">this topic in book A</span> and <span class="xref" origkeyref="B.topic_B">this topic in book B</span>.</p>
   </div>
   <div class="related-links">
<ul class="ullinks">
<li class="link ulchildlink"><strong><a href="topic_C.html#id_C_subtopic">Subtopic in Book C</a></strong><br />
</li>
</ul>
</div><div class="topic nested1" aria-labelledby="ariaid-title2" id="id_C_subtopic" @origkeys="topic_C_subtopic">
   <h2 class="title topictitle2" id="ariaid-title2">Subtopic in Book C</h2>
   <div class="body"><p class="p">Welcome to the subtopic in book C!</p></div>
   <div class="related-links">
<div class="familylinks">
<div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="topic_C.html">Topic in Book C</a></div>
</div>
</div></div>
</body>
</html>

As long as the @keys information is preserved in the output instances, my post-processing script can match the cross-book <xref> elements to the correct instances in the published output files. If we can figure this out, I think we'll have a basic generalized capability for cross-book links (via post-processing) that anyone could use.

My current solution requires the map files to make the connections. This is overly restrictive, plus it assumes the output file structure always matches the DITA topic file structure, which might not always hold true. With the @keys values preserved in the output instances, both these restrictions disappear and the solution becomes generalized.

If someone can at least point me to the right extension point and template to work with, I'd greatly appreciate it!

 - Chris


Chris Papademetrious
 

The writers in our pilot project have started inserting cross-book links in their books. We quickly realized that the <xref> must contain the text of the target or the reference is blank in the PDF. To its credit, the DITA-OT warns of this need:

[move-meta] file:/mnt/c/Users/chrispy/Documents/DITA/bugs/oxygen_key_scope/bookA.ditamap:13:114: [DOTX020E][ERROR]: Missing navtitle attribute or element for peer topic "bookB.ditamap". References must provide a local navigation title when the target is not a local DITA resource.
[move-meta] file:/mnt/c/Users/chrispy/Documents/DITA/bugs/oxygen_key_scope/bookA.ditamap:13:114: [DOTX024E][ERROR]: Missing linktext and navtitle for peer topic "bookB.ditamap". References must provide a local navigation title when the target is not a local DITA resource.

although the message is strangely worded to refer to the peer map as a topic.

It is impractical to require writers to insert the title of the destination topic for every <xref>. We already have a "book fixer" utility that adds topicrefs for nested subtopics. I'll update the utility to populate the text of cross-book links.

In addition, Radu helped me put together a real DITA-OT plugin to preserve cross-book keyref information in the processing pipeline. Once I have a working start-to-finish solution, I'll share it here.

 - Chris


Stuart Norton <stu.norton@...>
 

Thanks for sharing your efforts, Chris!

Our writers are also very keen to have cross-book linking work smoothly in our writing and publishing environment, since it's something that worked just fine in their previous environment.

So far we are reading through all of Eliot Kimber's presentations on this and trying to figure out how to enable this functionality well. Ideally it would be nice to have a solution that is generic, perhaps taking advantage of the new DITA OT project files, but I fear we might have to "hack" it and come up with something that meets our internal needs if we can do that more quickly.

We would definitely appreciate hearing more on the plug-in and your solution as it develops.

Thanks and best regards,
Stuart


Wayne Brissette
 



On Dec 2, 2019, at 6:41 PM, Chris Papademetrious <chrispitude@...> wrote:

The writers in our pilot project have started inserting cross-book links in their books. We quickly realized that the <xref> must contain the text of the target or the reference is blank in the PDF. To its credit, the DITA-OT warns of this need:

What is your output? PDFs have always caused us grief, even when ‘working’ they can easily get broken by the remote PDF not being where the link is looking. 

-Wayne