A simple use case for DITA conkeyrefs
I have struggled to understand the keyref and conkeyref features added in DITA 1.2.
It wasn’t until we started applying them to our proposal workflow that I finally understood them. I hope this use case also helps others.
Our project proposals are relatively straightforward. A typical proposal is 8–18 pages long. Most of the project descriptions, as you might expect, are unique to each customer, but the terms and conditions are fairly standard.
To avoid embarrassing mistakes, we use a conref for the client name. This allows us to set up the client name once in the executive summary and then just reference the client name throughout the proposal:
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="executivesummary" rev="1">
<title>Executive summary</title>
<body><p><ph id="client">XYZ company</ph> is looking for
some help</p>
<p>Scriptorium Publishing provides content strategy and
implementation services for technical communication requirements.
...</p>
...
</body>
</topic>
Elsewhere in the proposal, we use a conref to reference the client name:
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="output" rev="1">
<title>Setting up output</title>
<body>
<p><ph conref="summary.xml#executivesummary/client"/> has determined
that printed, PDF, and HTML versions are required for the technical
documentation.</p>
...
</body>
</topic>
This works well for most of the proposal, but the terms and conditions file is problematic. Most of the information in that file is reusable, so we’d like to use a single terms.xml file.
Consider the following folder structure:
proposals
abc
summary.xml
xyz
summary.xml
output.xml
shared
terms.xml
The problem is in creating a conref inside terms.xml. For client XYZ, it would need to say:
<ph conref="../xyz/summary.xml#executivesummary/client"/>
And for client ABC:
<ph conref="../abc/summary.xml#executivesummary/client"/>
And naturally, there are at least half a dozen of these references in the terms file. We could write around it, of course, by only discussing the generic Client. But if you want the right client name in the file with minimal maintenance, you suddenly have a use case for conkeyref. Instead of linking directly to the summary.xml in a client specific folder, the terms.xml file uses this:
<ph conkeyref="proposalinfo/client">Client Name</ph>
The XYZ proposal ditamap file defines the location of the keyconref:
<keydef keys="proposalinfo" href="proposalinfo.xml" type="topic" format="dita"/>
And the proposalinfo.xml file, which goes into each proposal folder, contains this:
<topic id="variables" xml:lang="en-us">
<title id="stuff">Proposal variables</title>
<body>
<p>
<ph id="client">XYZ</ph>
</p>
</body>
</topic>
This is a bit more work to set up than a regular conref, but when we go to build our next proposal, we just update the proposalinfo.xml file for that proposal.
The key (sorry!) to understanding the conkeyref is that we can eliminate the folder-specific links from our shared terms file. Instead, the terms file points to a generic identifier. The identifier is resolved by information provided in the proposal-specific ditamap file.
About the author
Julio Vazquez
Awesome use case, Sarah! It’s good to see real life examples like this (rather than stuff made up like I do) that show the benefits of DITA and it’s facilities like conkeyref. There are many other things you may want to look into that can probably help your proposal building (push conref comes to mind) in DITA 1.2.
Great job!
Benny
Dear Sarah,
I know this is a post from 2011 but I arrived here by following the link in one of the courses @ learningdita.com. This also means I am new to Dita :). But after following the courses I was wondering why in this situation it is not possible or not desired to just use a key which defines the customer instead of using a conkeyref.
For example, in the map file:
XYZ
and in the terms.xml
Could you comment on this?
Sarah O'Keefe
Hi Benny,
Unfortunately, WordPress ate your code samples, but I take your general point, which is that you could use a keyref and not a conkeyref. I think you are right that a keyref would work for the simple example I’m describing, but a conkeyref would be better if the referenced information is more complex, like an entire paragraph or range of paragraphs.
Benny
Hi Sarah,
Thanks for your fast reply. Actually I read your example at the beginning of the course about advanced conrefs. At the end of that course my question is also answerred: a simple keyref would not support a company name like “Pure-H2O” with the “2” being subscript. As the “keyword” element doesn’t allow for advanced markup.
Thanks also for creating the learning DITA webpage, I learned a lot!