Re: Keyref/conkey ref conversion strategy - keyref all the things? #conref

Chris Papademetrious

Hi Ed,

I posted a similar question awhile back:

We are relatively new to DITA. Our writers have been adding cross-book links to their content (which is calling our bluff on finding a PDF/OLH solution to publish them properly!). As a result, we decided to use keyref cross-references for all topic references, both within-book and cross-book.

The easiest part has been the creation of the topic cross-references in Oxygen XML Author. Notably,

  • If you drag-and-drop a topic from the DITA Maps Manager into your editing window, Oxygen creates a keyref-based reference (if possible).
    • If the topic isn't reachable by keyref, Oxygen is smart enough to insert an href-based reference instead.
  • If you copy a topic (or other) element, then do a Paste Special > Paste as link (keyref), then Oxygen inserts a keyref-based reference to that element.
    • If the element isn't reachable by keyref, the tool issues an error dialog.
In both cases, Oxygen creates the scoped keyref properly if the reference is in another book's keyscope.

The hardest part has been getting writers to remember to create key values for new topics. If they don't, there's nothing to reference. I've filed an Oxygen enhancement request to automatically populate the key values of new topics, similar to how the topic filename and @id values are pre-set.

I wish there were a "Paste as link (keyref/href)" that would prefer keyrefs but fall back to hrefs. Then I would keep only that in the right-click context menu to guide writers to the best practice by construction.

 - Chris

Join to automatically receive all group messages.