Syntax diagram in WebHelp Responsive Output is missing some attributes

[susannecm]

Hi,
I am working on a publishing template for CSS_styled PDF output and responsive WebHelp. The Oxygen version is 24.1.
We do have a couple of document that include syntax diagrams. Previously, these were only published as PDF files using the XSL-based transformation of the DITA Open Toolkit. Now these documents are supposed to be available in both formats.
Currently, I am trying to enclose optional elements such as groupseqs in square brackets. This is working in the PDF output, but it doesn't work in the WebHelp output. For some reason, the @importance attribute is not passed on to the output at all.
DITA XML:

Code: Select all

<groupseq importance="optional">
    <kwd>--serviceName</kwd>
    <var>arg</var>
</groupseq>

Merged HTML for PDF-output:

Code: Select all

<div class="+ topic/figgroup pr-d/groupseq figgroup groupseq" importance="optional">
          <span class="+ topic/keyword pr-d/kwd keyword kwd">--serviceName</span>
          <span class="+ topic/ph pr-d/var ph var">arg</span>
</div>

WebHelp output:

Code: Select all

<div class="+ topic/figgroup pr-d/groupseq figgroup groupseq">
          <span class="+ topic/keyword pr-d/kwd keyword kwd">--serviceName</span>
          <span class="+ topic/ph pr-d/var ph var">arg</span>
</div>

Interestingly, the HTML5 output also lacks the attribute, but it contains the square brackets I would like to add.

Code: Select all

[ 
    <kbd><b>--serviceName</b></kbd>
    <var>arg</var>
] 

What can I do to get a reasonable formatting of the syntax diagrams?
Thank you for any help
Susanne

[julien_lacour]

Hello Susanne,

You're right, there is a problem in the syntaxdiagram elements processing, we added an issue to fix this problem on the next Oxygen 25.0 maintenance build.

If you already have upgraded to Oxygen 25.0, the problem will resolve automatically when the maintenance build will be available (in a few weeks).

If you have a previous version of Oxygen you can manually fix the problem by editing the OXYGEN_INSTALL_DIR\frameworks\dita\DITA-OT3.x\plugins\com.oxygenxml.webhelp.responsive\xsl\dita2webhelp\html5-pdf-webhelp\html5-figures.xsl, the following template match must be changed:

Code: Select all

  <!-- =========== FIGURE =========== -->
  <!-- Overriding org.dita.html5/xsl/topic.xsl -->
  <xsl:template match="*[contains(@class, ' topic/fig ') and not(contains(@class, ' ut-d/imagemap '))]" name="topic.fig">

Here's the new match fixing the problem:

Code: Select all

  <!-- =========== FIGURE =========== -->
  <!-- Overriding org.dita.html5/xsl/topic.xsl -->
  <xsl:template match="fig[contains(@class, ' topic/fig ')]" name="topic.fig">

Thank you for the reporting,
Best regards,
Julien

[susannecm]

Hello everyone,
I started working on this problem again, using version 25.
We also need the PDF output, and something strange is happening with PDF.
In the merged HTML file for PDF, but not in the WebHelp, some of the longer syntax diagrams include line breaks which I cannot attribute to specific DITA elements. The HTML contains blockquote elements that are apparently caused by the user agent stylesheet. In the resulting PDF, these lines are enclosed in quotation marks.
Any ideas?
Kind regards
Susanne

[julien_lacour]

Hello Susanne,

Have you tried the last Oxygen version (25.1), you should be able to upgrade without changing your license (as you already have 25.0).
Is the problem still present? Could you provide a small sample reproducing the problem?

Regards,
Julien

[susannecm]

Hello Julien,
the problem is still present after an update to version 25.1. The behavior is not related to my publishing template but occurs in the default HTML5 and CSS-based PDF output. For some reason, blockquote and kbd elements are inserted in the output.
I am going to send a small map and sample output to the support email.
Regards,
Susanne

[julien_lacour]

Hello Susanne,

I added a new issue on our side to optimize the default CSS rules for PDF and WebHelp outputs.
Until then you can already use the following rules in a custom CSS stylesheet to remove the extra layout:

Code: Select all

blockquote {
  margin:1em 40px;
  border-left: 0;
}
.lq {
  padding-left: 0.5em;
  border-left: 2px solid #EEE;
}
.lq:before {
  color: initial;
  content: open-quote;
  font-size: 1.2em;
}
.lq:after {
  color: initial;
  content: close-quote;
  font-size: 1.2em;
}

/* 
 * Blockquotes inside syntaxdiagrams should not be between quotes.
 */
*[class ~= "pr-d/syntaxdiagram"] blockquote:before,
*[class ~= "pr-d/syntaxdiagram"] blockquote:after {
  content: none;
}

There's an extra rule for <kbd> in WebHelp, if you don't like it you can also override the properties:

Code: Select all

kbd {
  background-color: #212529;
  border-radius: .2rem;
  color: #fff;
  font-size: 87.5%;
  padding: .2rem .4rem;
}

You may need to set the 'clean.output' parameter for the WebHelp Responsive transformation in order to obtain the desired result.

Regards,
Julien

[susannecm]

Hello Julien,
thank you for your help with this.
I am getting close to something useful, but there are still two problems left.
The first problem is cosmetic in nature. The kbd elements within the syntaxdiagram appear in bold in the output, and somehow I cannot override this. This is the code that did not work (that is, it worked, except for the font-weight property):

Code: Select all

*[class ~= "pr-d/syntaxdiagram"] kbd {
	font-weight: normal;
	font-family: 'Inconsolata', monospace;
	font-size: 100%;
	background-color: transparent; 
        color: var(--blackish-color);
}

The second problem is more severe. Some of the syntax diagrams contain a repsep element. Unfortunately, these elements are completely missing in the output.
The repsep element of the following diagram is visible in the author mode of oXygen, but there is no trace of it in the PDF or WebHelp:

Code: Select all

    <syntaxdiagram translate="no">
        <groupseq>
          <kwd>AGGREGATE</kwd>
          <delim/>
          <var>aggmethod</var>
          <kwd>(</kwd>
          <groupseq>
            <repsep>,</repsep>
            <var>aggparam</var>
          </groupseq>
          <kwd>)</kwd>
        </groupseq>
      </syntaxdiagram>

Is there a way to make it visible in the output?
Kind regards,
Susanne

[julien_lacour]

Hello Susanne,

I tested the following CSS in a WebHelp Responsive transformation scenario and the kbd are modified:

Code: Select all

:root {
  --blackish-color: black;
}
...
*[class ~= "pr-d/syntaxdiagram"] kbd {
  font-weight: normal;
  font-family: 'Inconsolata', monospace;
  font-size: 100%;
  background-color: transparent; 
  color: var(--blackish-color);
}

Regarding the <repsep> element support, currently the default DITA-OT processing is to hide them: https://github.com/dita-ot/dita-ot/issues/199
You could use the svg-syntaxdiagrams plugins to render the diagrams as SVG:

1. Download the last plugin release from GitHub
2. Download a separate Oxygen Publishing Engine from our website (we recommend the usage of a separate engine to avoid permissions issues, also it's easier to manage than to search inside Oxygen folders) and unzip it
3. Unzip the plugins into Oxygen Publishing Engine /plugins directory
4. In Oxygen > Options > Preferences > DITA > DITA Open Toolkit change the option to Custom
5. Set the path to the unzipped Oxygen Publishing Engine folder (the path must end with "oxygen-publishing-engine")
6. Start the "Run DITA-OT Integrator" scenario from the DITA Maps Manager, you must see the plugins name in the console
7. Run your WebHelp Responsive transformation scenario, you should see SVGs files in the output, for example:

   

   syntaxdiagram.png (11.83 KiB) Viewed 573 times

Regards,
Julien