v25.1 change in behavior for <image placement="break">

Post by **chrispitude** » Tue May 23, 2023 5:35 pm

This is a heads-up to my fellow WebHelp users. Given a DITA <image> element with @placement="break":

<p>LINE</p>
<image href="image.png" placement="break"/>
<p>LINE</p>

In v25.0, the webhelp-responsive transformation produces HTML that uses a @class="break" property to apply "display: block" via CSS:

Code: Select all

<p class="- topic/p p">LINE</p>
<img class="- topic/image image break" src="image.png"/>
<p class="- topic/p p">LINE</p>

In v25.1, the webhelp-responsive transformation produces HTML that uses   elements to make the images effectively block elements:

Code: Select all

<p class="- topic/p p">LINE</p>
<br><img class="- topic/image image" src="image.png"/><br>
<p class="- topic/p p">LINE</p>

The v25.1 webhelp-responsive behavior matches the DITA-OT's html5 transformation behavior, which has always used   elements to bound placement="break" images (including in Oxygen v25.0).

However, the default CSS properties for   elements cause additional vertical space to be added above the image. I'm still deciding how I want to fix this in our flow:

Keep the   elements, but add a line-height: 0 property in our CSS file
In our HTML5 DITA-OT plugin, remove the   elements and reapply @class="break" to these image elements
In our HTML5 DITA-OT plugin, remove the   elements and add @styles="display: block" to these image elements

Note that PDF Chemistry is unaffected by this behavior change; the intermediate HTML it produces still uses the @class="break"/CSS approach, so any change to DITA-OT processing must keep this in mind.

Here's a small testcase for experimentation:

webhelp-images-placement-break.zip: (4.12 KiB) Downloaded 93 times

Post by **chrispitude** » Tue May 23, 2023 6:56 pm

Well this is frustrating! If the output is serialized as XHTML, then the   element considers the line-height CSS property:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<html lang="en">
 <head>
  <style>br {line-height: 0}</style>
 </head>
 <body>
  <p>LINE</p>
  <br /><span>image</span><br />
  <p>LINE</p>
 </body>
</html>

But if the output is serialized as HTML5 (the default), then the   element ignores line-height completely:

Code: Select all

<!DOCTYPE html>
<html lang="en">
 <head>
  <style>br {line-height: 0}</style>
 </head>
 <body>
  <p>LINE</p>
  <br><span>image</span><br>
  <p>LINE</p>
 </body>
</html>

I was going to propose an enhancement to the DITA-OT's default CSS to apply line-height: 0 to   elements, but without resolving this issue, it would be ignored.

display: none does not work, because then consecutive @placement="break" images would get stacked on the same line as inline images.

Post by **chrispitude** » Wed May 24, 2023 12:52 am

I filed the following DITA-OT issue:

#4202: Images with @placement="break" have extra blank space above them in HTML5 output

Post by **chrispitude** » Wed May 24, 2023 3:23 am

So now I see the reason for the difference in WebHelp behavior. There is an "html5-images.xsl" stylesheet in the WebHelp and PDF Chemistry transformations that converts the adjacent   elements to @class="break" added to the image. This stylesheet is used in both versions of PDF Chemistry, but only in v25.0 of WebHelp:

Code: Select all

$ find . -name 'html5-images.xsl'
./oxygen-publishing-engine-3.x-25.0-2023012609/plugins/com.oxygenxml.pdf.css/xsl/merged2html5/html5-pdf-webhelp/html5-images.xsl
./oxygen-publishing-engine-3.x-25.0-2023012609/plugins/com.oxygenxml.webhelp.responsive/xsl/dita2webhelp/html5-pdf-webhelp/html5-images.xsl
./oxygen-publishing-engine-25.1-2023042507/plugins/com.oxygenxml.pdf.css/xsl/merged2html5/html5-pdf/html5-images.xsl

As a workaround, I will include this stylesheet in our company's WebHelp plugin using the com.oxygenxml.webhelp.xsl.dita2webhelp extension point. The "break" keyword is added twice in v25.0 because both copies of html5-images.xsl add it. I tried to work around this by not copying the keyword if it already exists in our copy:

Code: Select all

      <xsl:when test="$placement = 'break' and not(tokenize(., '\s+') = 'break')">
        <xsl:attribute name="class" select="concat(., ' ', $placement)"/>
      </xsl:when>

but unfortunately in

plugins/com.oxygenxml.webhelp.responsive/xsl/dita2webhelp/dita2webhelp_template.xsl

the Oxygen XSLT files are applied after the com.oxygenxml.webhelp.xsl.dita2webhelp extension point, which means a user plugin cannot override WebHelp templates. I will file an enhancement request to move the extension point to be last.

Post by **radu_pisoi** » Fri May 26, 2023 9:54 am

Hi,
I have tested the com.oxygenxml.webhelp.xsl.dita2webhelp extension point with WebHelp 25.1 using a publishing template. After running the DITA-OT Integrator, the XSLT file associated with the extension points is imported after the WebHelp XSLT stylesheet.

Code: Select all

<xsl:import href="dita2webhelpImpl.xsl"/>
<xsl:import xmlns:dita="http://dita-ot.sourceforge.net" href="template:xsl/com.oxygenxml.webhelp.xsl.dita2webhelp"/>

The template:xsl/com.oxygenxml.webhelp.xsl.dita2webhelp XSLT stylesheet is resolved through the XML catalog to the custom user XSLT stylesheet.

Do you reproduce this with 25.1 version? You can upgrade freely from version 25.0 to 25.1.

Post by **chrispitude** » Fri May 26, 2023 3:14 pm

Hi Radu,

Indeed you are correct! I misunderstood how the extension points were structured in the template file. Instead, there was a bug in my workaround plugin that caused the duplicate values in v25.0.

If anyone wants to revert to the CSS-based @class~="break" behavior, you can use this workaround plugin:

com.synopsys.webhelp-images-placement-break.zip: (1.33 KiB) Downloaded 96 times

This works in both v25.0 (does not affect output) and v25.1 (converts the   structure to @class~="break").

Radu, was this change made to align WebHelp's output to the default DITA-OT HTML5 output? I like that the outputs are more aligned, but maybe we can work together to fix DITA-OT issue #4202. The cleanest solution actually seems to be how WebHelp implemented it in v25.0 - would you be interested in seeing the DITA-OT adopt this approach natively?

v25.1 change in behavior for <image placement="break">

v25.1 change in behavior for <image placement="break">

Re: v25.1 change in behavior for <image placement="break">

Re: v25.1 change in behavior for <image placement="break">

Re: v25.1 change in behavior for <image placement="break">

Re: v25.1 change in behavior for <image placement="break">

Re: v25.1 change in behavior for <image placement="break">