Updating from 12.1 to 12.2 and CHM transformation problems

[sisselo]

Hi,

I tried to update from version 12.1 to 12.2, but I experienced so severe problems with my CHM transformations that I had to roll back to 12.1.

First of all the transformations did take approx 6 minutes longer (on my computer) with version 12.2 than with 12.1. Even transformations that took 6 seconds on 12.1 took 6,5 minutes on 12.2. The step that causes this is:

dita.htmlhelp.convertlang:
[check-lang] Check Language
[convert-lang] Convert Language

I could not find any description of what this step does. I commented you the <antcall target="dita.htmlhelp.convertlang"></antcall> line in the ..Oxygen XML Editor 12\frameworks\dita\DITA-OT\build_dita2htmlhelp.xml file and then it worked better.

This might be a good feature, but I think you should make it optional in the user interface if you will keep it. It is not doable for all my colleagues to manually edit the DITA-OT files. And it is not an option to spend so long on each transformation. It looks like a feature you will run once in a while to make sure everything is correct, but not every single time.

The other problems that I could not find a workaround for were changing my chm output. I got the shortdesc text at the top of all documents (in the head section of the html), and I did not get any "Parent topic" links at the bottom of my documents. These problems reduced the quality of my chm's and were the direct reason for the roll back to version 12.1.

Are there any settings I can use so I can run version 12.2 without these problems?

Regards, Sissel

[Radu]

Hi Sissel,

Oxygen 12.2 comes with an update to the DITA Open Toolkit (it uses the final DITA OT 1.5.2).

So you reported 3 problems:

First of all the transformations did take approx 6 minutes longer (on my computer) with version 12.2 than with 12.1. Even transformations that took 6 seconds on 12.1 took 6,5 minutes on 12.2. The step that causes this is:

dita.htmlhelp.convertlang:
[check-lang] Check Language
[convert-lang] Convert Language

Indeed I can see this modification was added to the DITA OT 1.5.2 but I don't know the reason for this (this is probably related to internationalization support). You can probably indeed comment the ant call:

Code: Select all

<antcall target="dita.htmlhelp.convertlang"></antcall>

with no side effect if you are only using English content.
I see there were previous complains on the DITA Users List (unanswered):
http://tech.groups.yahoo.com/group/dita ... sage/20975
I'll ask for this on the DITA developers list.

I got the shortdesc text at the top of all documents (in the head section of the html)

Yes, we noticed this bug in one of our patches for DITA OT 1.5.2 and we made some fixes in the stylesheets but the fixes were not incorporated in Oxygen 12.2.
The next maintenance release of Oxygen 12.2 will also contain a fix for this problem:
http://www.oxygenxml.com/rssBuildID.xml

I did not get any "Parent topic" links at the bottom of my documents.

This is a side effect generated by the fact that we added an extra plugin for DITA to EPUB to the bundled DITA OT.
I registered a bug for this to the plugin's developer:
https://sourceforge.net/tracker/?func=d ... id=1259341
But the workaround is simple, edit the DITA to CHM transformation scenario, in the Parameters tab edit the args.hide.parent.link parameter and force its value to no (do not rely on the default value).

Regards,
Radu

[Radu]

One more thing:

Oxygen does not force you to use the bundled DITA OT for DITA publishing.
If you edit a DITA transformation scenario, in the Parameters tab you can edit the dita.dir to point to a custom DITA OT (for example you can use the DITA OT bundled in the Oxygen 12.1 OXYGEN_12.1_INSTALL_DIR/frameworks/dita/DITA-OT directory with Oxygen 12.2).
Some of our users use a custom DITA OT (with modified stylesheets and build files) for publishing from Oxygen. They usually commit the custom DITA OT to a repository like Subversion (Oxygen has a Subversion client bundled) so that everybody uses the same DITA OT.

If you want a patch for the shortdesc problem and do not want to wait for the next 12.2 maintenance release (probably a month) you can write us using the support at oxygenxml dot com email address and we'll provide one for you.

Regards,
Radu

[sisselo]

Hi Radu,

Thanks for the replys

We will definitively consider to have a "company" version of the DITA-OT. We have already done some customizations and this will be a simpler way to distribute them. The only challenge I can see is to get your Oxygen changes implemented when we upgrade to a new version. How will it work if we have a common DITA-OT for our company based on the Oxygen DITA-OT and not all my colleagues are using the same Oxygen version? I assume from your post that the 12.1 DITA-OT can be used with version 12.2. But should it also work the other way around?

Sissel

[Radu]

Hi Sissel,

Basically what Oxygen is doing when running the transformation is to invoke an external ANT process on the main build file from the DITA OT directory with the set custom user parameters.
We also have some patches which might break the processing when using a different DITA OT but you can control if these patches contribute to the ANT process:
http://www.oxygenxml.com/doc/ug-oxygen/ ... ta-ot.html

So if in a future version of Oxygen you will not be able to run the custom DITA OT you will probably be able to modify the transformation scenario to get it working again.

For our user manual we use automated ANT scripts to publish the documentation to various formats and we only use Oxygen to preview how documentation for a certain topic will look like.

Regards,
Radu

[nkerzreho]

Hi,

I was able to change the parent linking with the transformation argument, thanks for that tip Radu!
Of course, I also have the problem in CHM outputs with short descriptions displaying before AND after the title.
Will you keep us posted on the next patch for version 12.2 that resolves this?

Regards,
Nolwenn Kerzreho
--
Technical Writer at Technicolor (Thales Services)
Adjunct Teacher at Université Rennes 2 http://www.cfttr.fr

[Radu]

Hi Nolwenn,

The problem was generated by a bad patch we made in the bundled DITA OT distribution.
Instead of waiting for a maintenance release of Oxygen 12.2 you can make the modification yourself in the stylesheet:
OXYGEN_INSTALL_DIR/frameworks/dita/DITA-OT/xsl/xslhtml/get-meta.xsl

Search for the xsl:template:

Code: Select all

<!-- CONTENT: Description - shortdesc -->

<xsl:template match="*[contains(@class,' topic/shortdesc ')]" mode="gen-metadata">

  <xsl:variable name="shortmeta">

    <xsl:apply-templates select="*|text()" mode="text-only"/>

  </xsl:variable>

  <!-- OXYGEN PATCH START EXM-19758 -->

  <xsl:value-of select="normalize-space($shortmeta)"/>

  <!-- OXYGEN PATCH END EXM-19758 -->

</xsl:template>

and replace it with:

Code: Select all

<!-- CONTENT: Description - shortdesc -->

<xsl:template match="*[contains(@class,' topic/shortdesc ')]" mode="gen-metadata">

  <xsl:variable name="shortmeta">

    <xsl:apply-templates select="*|text()" mode="text-only"/>

  </xsl:variable>

  <meta name="abstract">

    <xsl:attribute name="content"><xsl:value-of select="normalize-space($shortmeta)"/></xsl:attribute>

  </meta>

  <xsl:value-of select="$newline"/>

  <meta name="description">

    <xsl:attribute name="content"><xsl:value-of select="normalize-space($shortmeta)"/></xsl:attribute>

  </meta>

  <xsl:value-of select="$newline"/>

</xsl:template>

Regards,
Radu