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


Chris Papademetrious
 

Hi Ed, all,

Our writers use nested <topic> elements in some topic files to keep tightly-related content together. One pain point with "keyref-all-the-things" is that subtopics nested within topic files also require key definitions to reference them or their contents:

      <topicref href="fcdm/preface/about_this_user_guide.dita" keys="about_this_user_guide">
        <topicref href="fcdm/preface/about_this_user_guide.dita#section_id1" keys="audience"/>
        <topicref href="fcdm/preface/about_this_user_guide.dita#section_id2" keys="related_publications"/>
        <topicref href="fcdm/preface/about_this_user_guide.dita#section_id3" keys="release_notes"/>
        <topicref href="fcdm/preface/about_this_user_guide.dita#section_id4" keys="conventions"/>
      </topicref>

It's impractical for authors to keep their map up-to-date as they create and modify subtopic structure and content. We have a "map-fixer" utility, written in perl and compiled to a Windows .exe with Strawberry Perl, that is configured as an external tool in Oxygen. Users can run this "Map Updater" utility from the menu and it will scan their DITA files and update their bookmap as needed. (It also populates the text content of cross-book <xref keyref> elements with the target text.)

The utility has a couple specific references to our directory structure and specializations, but I can point those areas out. This whole approach is admittedly a quick-and-dirty hack to keep our writers writing, I'm happy to share it if anyone's interested.

 - Chris

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