Suppress "buildId" to make WebHelp output deterministic

[chrispitude]

When we integrate WebHelp into our tools, the entire WebHelp directory is checked into R&D revision control along with the C code.

Currently, revision control detects every HTML file in the WebHelp output as changed because of differences in "buildId" values as follows:

Code: Select all

diff -r out1/out/dita/topic-3_3_3.html out2/out/dita/topic-3_3_3.html
10c10
<     <script src="../oxygen-webhelp/app/options/properties.js?buildId=20221019170411"></script>
---
>     <script src="../oxygen-webhelp/app/options/properties.js?buildId=20221019170439"></script>
12c12
<     <script src="../oxygen-webhelp/app/search/index/keywords.js?buildId=20221019170411"></script>
---
>     <script src="../oxygen-webhelp/app/search/index/keywords.js?buildId=20221019170439"></script>

This causes large checkins (thousands of files) that take a lot of time. This also makes it impossible to meaningfully use the revision history to see just content changes over time.

If I run the following command:

Code: Select all

find out* -name '*.html' -print0 | xargs -0 sed -E -i 's/\?buildId=[0-9]+//'

then I can remove these "buildId" values and the HTML files diff identically (except for content changes).

Are these values required for any WebHelp functionality (including invalidating browser caches, etc.), or are they purely informative?

Can WebHelp implement a feature to suppress these values in the output, or is there an easy way to do it that does not involve defining custom transformation types and all the headaches that brings?

Thanks!

[chrispitude]

It looks like maybe I could set the following transformation parameters to an empty string value:

Code: Select all

webhelp.build.number
webhelp.transformation.timestamp

which leaves empty "?buildId=" references in the HTML. Or perhaps if there is an XSLT template that the HTML content ultimately flows through, perhaps I could add attribute templates there to remove the "?buildId" suffixes completely?

[radu_pisoi]

Hi,

WebHelp transformation appends the buildID to the internal resources(CSS or Javascript) references to avoid browsers cache when users upgrade the WebHelp version.

We do not have a specific mechanism to override the buildID generation in the output files, I will add a feature request in our internal issue tracker to allow this in a future version.

Meanwhile, you can override the addLinksToSkinResources template from the {DITA-OT-DIR}/plugins/com.oxygenxml.webhelp.responsive/xsl/template/commonComponentsExpander.xsl file to skip buildID generation in the output files.

[chrispitude]

Great, thanks Radu! I will look into the short-term solution on our side.

Can you please let me know the issue ID for this enhancement request?

[chrispitude]

Hi Radu,

Also, do you recall the details of why this buildId value was needed? At least within our team, we cannot recall any previous situations where this was required, but maybe it was specific to some server or CDN (content delivery network) that might not apply to our configuration.

[radu_pisoi]

Hi,

Can you please let me know the issue ID for this enhancement request?

The issue id is WH-3056.

We had users in the past that complain the output styles are not changed after they upgrade the WebHelp version, somehow the browser delivers web page resources (CSS, JS) from cache and do not load the ones that come with new WebHelp output. Unfortunately, I don't remember for which server this situation happens.