DocBook to WebHelp Classic big problem

Ordinant
Posts: 6
Joined: Mon May 26, 2014 5:57 pm

DocBook to WebHelp Classic big problem

Post by Ordinant » Sat Mar 16, 2019 1:21 am

We use Oxygen 18.1, 19, and now 21.0 to generate WebHelp Classic from a DocBook 4 <book>. It has worked well, and looks great.

However, a customer discovered that if a search engine returns a link to a single frame of our WebHelp site, only that frame is returned as a result of that link, without the TOC and header panels at all.

By contrast, testing with the sample DITA-based WebHelp you provide at https://www.oxygenxml.com/samples/DITA- ... -Feedback/, I see the behavior we want but do not have. The Safari browser provides a right-click "Open Frame in New Tab" option. Using that option on any page in your sample shows me that page still wrapped in three panels with TOC visible and usable. In fact, we can right-click a page's entry in the TOC and "Open Link in New Tab." This opens the requested page, retaining the TOC and header panels as expected.

Trying the same thing on our published WebHelp returns only the document panel. There is no way to recover from this bogus single-frame view back to the standard three-panel view.

Try this yourself. Here is the top level of our WebHelp book: https://docs.tibco.com/pub/str/10.4.2/d ... index.html
You can navigate around in the Webhelp exactly as expected from the TOC and from the Next and Previous links.

However, if you use one of the "in New Tab" methods described above, or if a search engine incorrectly returns a link to a single page, you get into an unrecoverable situation. Try this:
https://docs.tibco.com/pub/str/10.4.2/d ... -client_ed

The AMS documentation I'm showing you here was a prototype for us using Oxygen to produce WebHelp for all books in our very large doc set. I was prepared to talk my managers into spending big bucks for your XML WebHelp product so that we could automate this conversion as part of our doc build system.

But that purchase -- indeed, our future of using Oxygen-generated WebHelp at all -- is now in danger if we can't get this issue fixed of breaking out of the three-panel WebHelp enclosure.

I understand that you and the entire world are turning towards DITA and that you think of DocBook as a legacy albatross around your necks. While I don't completely disagree, we also have a 3000 page doc set, a very active continuing release cycle, and nowhere near enough personnel. That's why I was so eager to let Oxygen do the heavy lifting of making us nice-looking WebHelp instead of crafting it all from scratch.

So, is this panel breakout problem fixable for DocBook, as you already fixed for DITA? If so, please fix this ASAP.

However, if you take the also reasonable position that you don't have resources to devote to DocBook work, please let me know ASAP, so that my group can go in a different direction.

Thank you!

bogdan_cercelaru
Posts: 208
Joined: Tue Jul 01, 2014 11:48 am

Re: DocBook to WebHelp Classic big problem

Post by bogdan_cercelaru » Tue Mar 19, 2019 3:57 pm

Hello,

Thank you for reporting this. I've tested and I can confirm this behavior.
Also, I've registered an issue in our issue tracking system to be addressed by our developers.
In the meantime, to fix this issue, you could edit the "${OXYGEN-DIR}/frameworks/docbook/xsl/com.oxygenxml.webhelp.classic/oxygen-webhelp/resources/js/webhelp_topic.js" file and replace the

Code: Select all

if ($('#permalink').length > 0) {
if (window.top !== window.self) {
try {
if (window.parent.location.protocol != 'file:' && typeof window.parent.location.protocol != 'undefined') {
$('#permalink>a').attr('href', window.parent.location.pathname + '?q=' + window.location.pathname);
$('#permalink>a').attr('target', '_blank');
} else {
$('#permalink').hide();
}
} catch (e) {
error(e);
}
} else {
window.location.href=getPath(location.pathname);
}
}
with the following one:

Code: Select all

if (window.top !== window.self) {
try {
if (window.parent.location.protocol != 'file:' && typeof window.parent.location.protocol != 'undefined') {
$('#permalink>a').attr('href', window.parent.location.pathname + '?q=' + window.location.pathname);
$('#permalink>a').attr('target', '_blank');
} else {
$('#permalink').hide();
}
} catch (e) {
error(e);
}
} else {
window.location.href=getPath(location.pathname);
}
Please note that this fix applies to Oxygen XML Editor version 21.0 and will be overwritten by future updates.

Regards,
Bogdan
Bogdan Cercelaru
<oXygen/> XML Editor, Schema Editor and XSLT Editor/Debugger
http://www.oxygenxml.com

Ordinant
Posts: 6
Joined: Mon May 26, 2014 5:57 pm

Re: DocBook to WebHelp Classic big problem

Post by Ordinant » Tue Mar 26, 2019 8:14 pm

Hi Bogdan,

Thank you for posting this temporary fix. I can confirm that it works as posted with Oxygen 19.1 and 20.1 using our copy of the DocBook WebHelp Classic scenario.

However, even with the fix in place, our scenario was failing in release 21.0 with the error shown below. It turned out to be impossible to get our scenario to run without error in 21.0, because it was copied and edited in an earlier release. I had to start from scratch with a new copy of 21.0's DocBook WebHelp Classic scenario and re-apply all of our customizations (such as directory locations), one by one. This new 21.0-specific scenario does run in Oxygen 21.0.

The primary difference between the 19.1 and 20.1 scenario and the 21.0 one is the number and location of JAR files called.

Using your own Diff Directories utility to compare frameworks/docbook/xsl between Oxygen 20.1 and 21.0 shows a large set of changes, mostly in the com.oxygen.webhelp.classic subdirectory.

I did not see in the release notes a warning that we have to port our scenarios all over again when upgrading to 21.0. Did I miss that?

Thanks!

______________
Here is the error message I got when trying to use a 19-20 scenario in 21.0:

Code: Select all


Description:
Transformation failed. Fatal error during transformation using /Applications/Oxygen XML Editor/frameworks/docbook/xsl/com.oxygenxml.webhelp.classic/xsl/docbook/desktop/chunk_custom.xsl: Cannot find a 1-argument function named {http://nwalsh.com/xslt/ext/com.nwalsh.saxon.UnwrapLinks}unwrapLinks(). The namespace URI and local name are recognized, but the number of arguments is wrong; SystemID: file:/Applications/Oxygen%20XML%20Editor/frameworks/docbook/xsl/xhtml/inline.xsl; Line#: 214; Column#: 23

Severity: Fatal

System ID:
/Users/bwright/sb/eng/sb/main/10.4/streambase/doc/sources/ams/index.xml

Scenario:
AMS DocBook WebHelp Classic

Build file:
/Applications/Oxygen XML Editor/frameworks/docbook/xsl/com.oxygenxml.webhelp.classic/build_docbook.xml

Post Reply