Enhance topic IDs
Enhances Eclipse Help template to use custom labels and improved handling of context-sensitive help markers.
Version |
Date |
Changes |
1.0 |
2011-01-10 |
Initial version. |
Applies to WebWorks build 2010.2 (and others)
Overview of Eclipse context-sensitive help elements
Eclipse uses the contexts.xml file to map GUI elements to help topics (HTML anchors on pages) for context-sensitive help. Each mapping is achieved with a <context> element that has three parts:
id identifies help topic
description is text summarizing the help topic in the Eclipse Related Topics Help window.
label is text naming the help topic in Related Topics.
href is a URI to the help page
The Eclipse Help template creates the contexts.xml file when it encounters a TopicID marker. That marker contains the id value. A second marker, TopicDescription is optional and contains the description text to use with the previous TopicID. When there is no TopicDescription marker, the template uses the source text where the TopicID was located. The template always uses the HTML page heading for the label value.
Problem
The problems with the default implementation are:
- You cannot define a custom label
When there are multiple TopicIDs on the same page (on the same location), it is hard to manage the associate TopicDescriptions
- The topic HREF always points to the page, and not to anchors on the page
Solution
I prefer to overload the TopicID marker values to include the ID, label, and description values. The format of the marker is
id:label%description
Where the id is required, and the label and description components are optional. When the optional parts are not in the marker, the template uses the default values. A typical marker value looks like this:
node_dialog:Dialogs% Dialogs are collections of nodes working together to complete a complex task.
And the generated < context> looks like this:
<context id="node_dialog"> <description>Dialogs are collections of nodes working together to complete a complex task.</description> <topic label="Dialogs" href="/com.nuance.help.e_test/nas_welcome.01.2.html" /> </context>
Implementation
I rewrote contexts.xsl to look for and extract the values based on the presence of colon (:) and percent (%) characters.
Labels
Here is the code that extracts the label:
<!-- CUSTOM: Look for custom label -->
<xsl:variable name="VarContextLabel">
<xsl:choose>
<xsl:when test="(contains($VarTopicText, ':')) and (contains($VarTopicText, '%'))" >
<!-- Contains an ID, label, and description 'id:label%description' -->
<xsl:value-of select="substring-before(substring-after($VarTopicText, ':'),'%')" />
</xsl:when>
<xsl:when test="contains($VarTopicText, ':')" >
<!-- No description, just ID and label 'id:label' -->
<xsl:value-of select="substring-after($VarTopicText, ':')" />
</xsl:when>
<xsl:otherwise>
<!-- Use default value, to be determined later -->
<xsl:value-of select="''" />
</xsl:otherwise>
</xsl:choose>
</xsl:variable>And later, this code uses it or the default value:
<!-- CUSTOM -->
<!-- Use custom label if it exists. -->
<xsl:choose>
<xsl:when test="string-length($VarContextLabel) > 0 " >
<econtexts:topic label="{$VarContextLabel}" href="{$VarAbsoluteLinkTarget}" />
</xsl:when>
<xsl:otherwise>
<econtexts:topic label="{$VarTopicByTextSplit/@title}" href="{$VarAbsoluteLinkTarget}" />
</xsl:otherwise>
</xsl:choose>
ID
This code extracts the ID:
<!-- CUSTOM: Look for a custom ID -->
<xsl:variable name="VarContextID">
<xsl:choose>
<xsl:when test="contains($VarTopicText, ':')">
<!-- Contains a description 'id:*' -->
<xsl:value-of select="substring-before($VarTopicText, ':')" />
</xsl:when>
<xsl:when test="contains($VarTopicText, '%')">
<!-- Contains a description without a colon 'id%*' (bad form) -->
<xsl:value-of select="substring-before($VarTopicText, '%')" />
</xsl:when>
<xsl:otherwise>
<!-- Use default value -->
<xsl:value-of select="$VarTopicText" />
</xsl:otherwise>
</xsl:choose>
</xsl:variable>And later, it is used like this:
<!-- CUSTOM: Use custom ID -->
<!-- Original line
<econtexts:context id="{$VarTopicText}">
-->
<econtexts:context id="{$VarContextID}" >
Description
Here is the code for extracting the description:
<xsl:variable name="VarDescription">
<!-- CUSTOM: Look for custom description -->
<xsl:choose>
<xsl:when test="string-length(substring-after($VarTopicText, '%')) > 0" >
<!-- Contains a custom description in the form '*%description' -->
<xsl:value-of select="substring-after($VarTopicText, '%')" />
</xsl:when>
<xsl:otherwise>
<!-- Use default -->
<xsl:choose>
<xsl:when test="$VarTopic/following-sibling::wwtopics:Topic[1]/@type = 'topic-description'">
<xsl:value-of select="$VarTopic/following-sibling::wwtopics:Topic[1]/wwtopics:Text/text()" />
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$VarTopic/following-sibling::wwtopics:ParagraphText/text()" />
</xsl:otherwise>
</xsl:choose>
</xsl:otherwise>
</xsl:choose>
</xsl:variable>And later it is used with this code (which is also the default):
<econtexts:description><xsl:value-of select="$VarDescription" /></econtexts:description>
HREF Anchors
I often have topic IDs in the middle of a topic. For those I want the link to go to the paragraph in the page, not the top of the page. Do that with HTML anchors (e.g., page.html#12345). This change includes the anchor ID in the href link:
<!-- CUSTOM: include the HTML anchor too.--> <!-- <xsl:variable name="VarLinkTarget" select="wwuri:GetRelativeTo($VarTopicByTextSplit/@path, $ParamSplit/@path)" /> --> <xsl:variable name="VarLinkTargetTmp" select="wwuri:GetRelativeTo($VarTopicByTextSplit/@path, $ParamSplit/@path)" /> <xsl:variable name="VarLinkTarget" select="concat($VarLinkTargetTmp, '#', $VarTopicByTextSplit/@id)" />
For the complete code, see the attached file (contexts_this_one.xsl; the contexts.xsl does not contain the anchor fix).