Skip to main content
May 31, 2011

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.

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>
<p><ph conref="summary.xml#executivesummary/client"/> has determined
that printed, PDF, and HTML versions are required for the technical

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:


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>
<ph id="client">XYZ</ph>

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.