Encoding context-sensitive help information in DITA reltables

Sarah O'Keefe / DITA2 Comments

The problem: DITA does not provide a default mechanism for encoding context-sensitive help information. This article discusses a new approach that avoids specialization and provides a maintainable approach for context-sensitive help mapping.


The mapping between context-sensitive help IDs and topics is encoded in a relationship table (<reltable>). The following example shows a basic mapping:

<reltable id=”cshelp”>
<!– example of single topic mapping to help ID –>
<relrow id=”h234334″>
<relcell>
<topicref href=”example.dita”/>
</relcell>
</relrow>
</reltable>

If a help ID should provide a list of related topics, those topics are shown as separate <relcell> entries in the corresponding <relrow>:


<reltable id=”cshelp”>
<!– example of multiple topic mapping to help ID –>
<relrow id=”h4444444″>
<relcell>
<topicref href=”example2.dita”/>
</relcell>
<relcell>
<topicref href=”example3.dita”/>
</relcell>
<relcell>
<topicref href=”example4.dita”/>
</relcell>
<relcell>
<topicref href=”example5.dita”/>
</relcell>
</relrow>
</reltable>

To make maintenance of the relationship table easier, and to separate it from the core content, the relationship table is stored in its own ditamap file and then referenced in the ditamap that manages the content. For example, if the context-sensitive help relationship table is stored in mapping.ditamap, then it could be referenced as follows:

<reltable conref=”mapping.ditamap#cshelp”><relrow/></reltable>

Important: This encoding approach takes care of the DITA source side of the context-sensitive help. You’ll need to build a DITA Open Toolkit plugin that processes the relationship table and creates the appropriate mapping files.

About the Author

Sarah O'Keefe

Twitter

Content strategy consultant and founder of Scriptorium Publishing. Bilingual English-German, voracious reader, water sports, knitting, and college basketball (go Blue Devils!). Aversions to raw tomatoes, eggplant, and checked baggage.

2 Comments on “Encoding context-sensitive help information in DITA reltables”

  1. Hi Sarah,
    This is an interesting approach for maintaining ID mappings, but I’m curious about why you don’t regard the resourceid element in the topic prolog as the “a default mechanism for encoding context-sensitive help information”. It is true that we have specialized it to define the supported help systems and required attributes, but it could be used without specialization. In both cases, you need to provide the transformations to produce the appropriate mapping files.

    1. Hi Barbara,
      I would consider it. But I see a couple of issues:
      * I’d prefer to abstract the mapping out of the content files. (I could live with the topic-based approach if this were the only issue.)
      * I have a specific requirement for one-to-many help ID mapping, where a single help ID points to multiple topic files. I think the reltables will make it much easier to keep track of the multiple related files.

Leave a Reply

Your email address will not be published. Required fields are marked *