= 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) &gt; 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, '%')) &gt; 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).
----
CategorySolutions