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


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

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