Context.xml in Eclipse help

[syed]

Hello,

I am planning to create context.xml that will contain context sensitive help and will integrate with Eclipse-based products.

I created a concept topic (dita) with title and short description. When i generated eclipse output, the text in the title element in the dita topic is displayed in the <description> element in the output.

Is this expected? I was expecting the text in short description to be available in the <description> element in the output.

Thanks...

[Radu]

Hi,

Indeed right now the topic title is used as a description in the context.xml.
There is an XSLT stylesheet which builds the context.xml by looking over the result XHTML documents:

OXYGEN_INSTALL_DIR\frameworks\dita\DITA-OT3.x\plugins\org.dita.eclipsehelp\xsl\contexts.xsl

It has some code like this:

Code: Select all

 <xsl:variable name="title" select="normalize-space(/xhtml:html/xhtml:head/xhtml:title)"/>
      <xsl:if test="string-length($title) > 0">
          <description><xsl:value-of select="$title"/></description>
          <topic label="{$title}" href="{concat($prefixHelpInstallPath, $href, '#', @id)}"/>
        </xsl:if>

maybe you can replace that XSLT code with code which also looks for the shortdesc:

Code: Select all

<xsl:variable name="title" select="normalize-space(/xhtml:html/xhtml:head/xhtml:title)"/>
      <xsl:variable name="shortdesc" select="normalize-space(/xhtml:html/xhtml:body/xhtml:div/xhtml:p[@class='shortdesc'])"/>
      <xsl:if test="string-length($title) > 0">
          <description>
            <xsl:choose>
              <xsl:when test="$shortdesc"><xsl:value-of select="$shortdesc"/></xsl:when>
              <xsl:otherwise><xsl:value-of select="$title"/></xsl:otherwise>
            </xsl:choose></description>
          <topic label="{$title}" href="{concat($prefixHelpInstallPath, $href, '#', @id)}"/>
        </xsl:if>

I will add an internal issue to look into making a similar change in the XSLT stylesheet bundled with Oxygen.
Maybe you can try it on your side and if it works attach some screenshots with how things look like in the Eclipse Help when the generated help is used.

Regards,
Radu

[syed]

Thanks Radu. That worked. I will let you know the result after integrating it with Eclipse.

Can you tell me what XSL code be added/updated so that everything in the body element of XHTML file is displayed? In the dita source, there is text beyond shortdesc. For instance, there is body element after shortdesc. Attached is sample dita and XHTML files.

Body.zip

(4.5 KiB) Downloaded 152 times

[Radu]

Hi Syed,

You can probably try an Xpath like this:

Code: Select all

  <xsl:variable name="shortdesc" select="normalize-space(/xhtml:html/xhtml:body//text()"/>

to get all the text from the XHTML body as a string for the shortdesc. I'm not sure if maybe there are circumstances when it's too much.
I have not worked with Eclipse help in a while. Where is this description used in the Eclipse Help window? Does it appear as a preview, or when hovering the reference?

Regards,
Radu

[syed]

Hi Radu,

There seems to be some issue with that code that you shared. Especially with the parentheses in "text()".
Sorry, i am not an XSL/SPath guy. I tried to make some changes but it didn't work. Can you please look into it?

Here's the snippet:

Code: Select all

   <xsl:variable name="title" select="normalize-space(/xhtml:html/xhtml:head/xhtml:title)"/>
      <xsl:variable name="shortdesc" select="normalize-space(/xhtml:html/xhtml:body//text())"/>
      <xsl:if test="string-length($title) > 0">
        <description>
          <xsl:choose>
            <xsl:when test="$shortdesc"><xsl:value-of select="$shortdesc"/></xsl:when>
            <xsl:otherwise><xsl:value-of select="$title"/></xsl:otherwise>
          </xsl:choose></description>
        <topic label="{$title}" href="{concat($prefixHelpInstallPath, $href, '#', @id)}"/>
      </xsl:if>

Also, attaching screenshot of a sample Eclipse help window that shows up on F1.

cshelp-sample.PNG (46.76 KiB) Viewed 1697 times

Syed

[Radu]

Hi Syed,

Sorry, the shortdesc variable definition should be something like:

Code: Select all

<xsl:variable name="shortdesc" select="normalize-space(string-join(/xhtml:html/xhtml:body//text(), ''))"/>

Regards,
Radu

[syed]

Thanks Radu. Sorry, was away.

That code worked. However, it just pulls everything and puts it just like that without honoring line breaks(<p> tag), bold text (<uicontrol> tag), list (<ul,ol> tags) and the rest of the allowed DITA tags. At the minimum, it's good to consider line breaks and list to present info in a readable manner.

Does contexts.xsl needs to be modified to get the required output?

Syed

[Radu]

Hi Syed,

From what I looked the "<description>" tag inside the Eclipse Help contexts.xml only allows plain text.
So you would need some kind of ASCII graphics plain text equivalent of the HTML content, using * to mark list items, adding line breaks between paragraphs. This is probably feasible with XSLT but you probably need time to implement it and there are probably lots of cases like tables, links, images. So you will have to figure this on your own.

Regards,
Radu

[syed]

Thanks Radu. Would you know if dita-ot or any other off the shelf option available for cs help?

Syed

[Radu]

Hi Syed,

If by "cs help" you mean context-sensitive help, our Oxygen WebHelp responsive output has this feature as it maps IDs to topics:

https://www.oxygenxml.com/doc/versions/ ... itive.html

Regards,
Radu