Encoding context-sensitive help information in DITA reltables

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>

<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.