DocBook 5 Webhelp fails with language attribute

[Ordinant]

There is a major conflict between the DocBook 5 Webhelp generation and XSLTHL syntax coloring. If I run either the DocBook Webhelp or DocBook Webhelp - Mobile transformations on DocBook 5 source that contains simple <programlisting>s without attributes, then all is well. As soon as I add the language attribute, <programlisting language="java"> (or any other supported language), Webhelp generation fails with the following error:

Code: Select all

BUILD FAILED

/Applications/oxygen/frameworks/docbook/xsl/com.oxygenxml.webhelp/build_docbook.xml:76: The following error occurred while executing this line:

/Applications/oxygen/frameworks/docbook/xsl/com.oxygenxml.webhelp/build_docbook.xml:111: Fatal error during transformation using /Applications/oxygen/frameworks/docbook/xsl/com.oxygenxml.webhelp/xsl/docbook/mobile/chunk_custom.xsl: Exception in extension function java.lang.NoClassDefFoundError: org/w3c/dom/ElementTraversal; SystemID: file:/Applications/oxygen/frameworks/docbook/xsl/highlighting/common.xsl; Line#: 71; Column#: -1

This problem is trivial to reproduce. Copy the sample below to a file, open it in Oxygen, and run the two Webhelp transformations on it. Boom. Then remove the language="java" attribute and try again. This time, Webhelp generation succeeds.

Notice that the HTML and XHTML transformations always succeed, with or without the attribute, but syntax coloring does not appear. That's a different issue. Let's get it to stop crashing, then work on getting the syntax coloring to work.

Environment: OS X Mavericks, Oxygen 16.0 build 2014052022. Also reproduced on Oxygen 15.2 build 2014040317, so this is not new with 16.0. On this system, the default system Java is Oracle 1.7.0_51-b13, but Apple Java 1.6.0_65-b14-462-11M4609 is also available. From the System Properties dialog, it looks like Oxygen is using the latter.

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>

<?xml-model href="http://docbook.org/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>

<?xml-model href="http://docbook.org/xml/5.0/rng/docbook.rng" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?>

<article xmlns="http://docbook.org/ns/docbook"

  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">

  <info>

    <title>Java Programming Language</title>

    <author>

      <orgname>Wikipedia</orgname>

    </author>

  </info>

  <section>

    <title>Hello World</title>

    <para>The traditional Hello world program can be written in Java as:</para>

    <programlisting language="java">class HelloWorldApp {

    public static void main(String[] args) {

        System.out.println("Hello World!"); // Display the string.

    }</programlisting>

    <para>Source files must be named after the public class they contain,

      appending the suffix .java, for example, HelloWorldApp.java. It must first

      be compiled into bytecode, using a Java compiler, producing a file named

      HelloWorldApp.class. Only then can it be executed, or launched. The Java

      source file may only contain one public class, but it can contain multiple

      classes with other than public access and any number of public inner

      classes.</para>

  </section>

</article>

[sorin_ristache]

Hello,

This problem is trivial to reproduce. Copy the sample below to a file, open it in Oxygen, and run the two Webhelp transformations on it. Boom. Then remove the language="java" attribute and try again. This time, Webhelp generation succeeds.

. . .

Environment: OS X Mavericks, Oxygen 16.0 build 2014052022. Also reproduced on Oxygen 15.2 build 2014040317, so this is not new with 16.0. On this system, the default system Java is Oracle 1.7.0_51-b13, but Apple Java 1.6.0_65-b14-462-11M4609 is also available. From the System Properties dialog, it looks like Oxygen is using the latter.

THank you for posting the source XML content but I can't reproduce the error. The built-in DocBook WebHelp transform works correctly and the Java code is syntax highlighted correctly in the output Webhelp pages on Mac OS X 10.9.1 (Mavericks) ansd also on WIndows 7. I tried on Mac OS X 10.9.1 with both Oxygen 16.0 with Java 1.7.0_45 and Oxygen 15.2 with Java 1.6.0_65 and I get the same (correct) output.

Did you modify or customize the built-in transform?

Code: Select all

BUILD FAILED

/Applications/oxygen/frameworks/docbook/xsl/com.oxygenxml.webhelp/build_docbook.xml:76: The following error occurred while executing this line:

/Applications/oxygen/frameworks/docbook/xsl/com.oxygenxml.webhelp/build_docbook.xml:111: Fatal error during transformation using /Applications/oxygen/frameworks/docbook/xsl/com.oxygenxml.webhelp/xsl/docbook/mobile/chunk_custom.xsl: Exception in extension function java.lang.NoClassDefFoundError: org/w3c/dom/ElementTraversal; SystemID: file:/Applications/oxygen/frameworks/docbook/xsl/highlighting/common.xsl; Line#: 71; Column#: -1

This class is located in the file OXYGEN_INSTALL_DIR/lib/xml-apis.jar which is present in the list of required jar libraries in the DocBook WebHelp transform. You can see the entire list if you press the Libraries button in the dialog box for editing the transform. If this jar file is present in the list (as it should be) the only remaining cause for this error is a corrupt xml-apis.jar file on disk in your OXYGEN_INSTALL_DIR/lib/xml-apis.jar directory which you can fix by re-installing the Oxygen application.


Regards,
Sorin

[Ordinant]

Hi Sorin,

Thanks for your quick reply.

Did you modify or customize the built-in transform?

No modifications or customizations of any transform. But see below, that turns out to be necessary.

I tried to figure out any differences between our systems to explain the different results. One is that this is OS X 10.9.3, but I doubt that's the issue. If you can, please update one of your Macs and try again to see.

This class is located in the file OXYGEN_INSTALL_DIR/lib/xml-apis.jar

Yes, indeed. I find that JAR file in /Applications/oxygen/lib and, opening the JAR, I find the .class file in question.

... which is present in the list of required jar libraries in the DocBook WebHelp transform.

Um, actually, it is not present. Looking inside both DocBook WebHelp and DocBook WebHelp - Mobile transforms, I find a list of 19 libraries. This does include ${oxygen home}/lib/xml-apis-ext.jar, but does NOT include the xml-apis.jar file that actually contains the class in question.

I fixed the problem by making a copy of the two transforms and adding file:/Applications/oxygen/lib/xml-apis.jar file right above the xml-apis-ext.jar line. Using my modified transforms, I can generate Mobile Webhelp from the sample source file I sent, and from my company's large User Guide.

As you know, installing Oxygen on a Mac is a matter of dragging the oxygen folder from the distribution zip file to the /Applications folder. There is no installation program to run, and none to fail. I could drag the folder over again, but I deeply doubt that is going to change anything.

I cannot explain why my copy of Oxygen contains WebHelp transform definitions that are missing the xml-apis.jar reference. Can you double-check that you tested with the latest 16.0 update, build 2014052022? Does your test Mac have developer-oriented class path or library settings that find the xml-apis.jar file independent of the transform's list of libraries?

I have a workaround for now. I will leave it to you to investigate how these installation differences could have happened.

Thanks!

[sorin_ristache]

Hi,

I tried to figure out any differences between our systems to explain the different results. One is that this is OS X 10.9.3, but I doubt that's the issue. If you can, please update one of your Macs and try again to see.

No, that can't be the issue because the list of libraries is stored in the Oxygen Docbook framework file on disk which is an XML file. The number of jar files in the list that is read from the XML file does not depend on the OS X version (10.9.1, 10.9.3, etc) or the Java version (1.6, 1.7, etc).

Um, actually, it is not present. Looking inside both DocBook WebHelp and DocBook WebHelp - Mobile transforms, I find a list of 19 libraries. This does include ${oxygen home}/lib/xml-apis-ext.jar, but does NOT include the xml-apis.jar file that actually contains the class in question.

It is present in the Docbook framework that comes in both 16.0 and 15.2 versions. It seems the Docbook framework was inherited from an older Oxygen version which is possible if you are working with the OXYGEN_INSTALL_DIR/frameworks directory that was created by an older version.

I fixed the problem by making a copy of the two transforms and adding file:/Applications/oxygen/lib/xml-apis.jar file right above the xml-apis-ext.jar line. Using my modified transforms, I can generate Mobile Webhelp from the sample source file I sent, and from my company's large User Guide.

That is only a workaround. We should figure out instead why you don't have the built-in Webhelp transformation of the latest Oxygen version.

As you know, installing Oxygen on a Mac is a matter of dragging the oxygen folder from the distribution zip file to the /Applications folder. There is no installation program to run, and none to fail. I could drag the folder over again, but I deeply doubt that is going to change anything.

That is probably it! I gather that you always install a newer version by overriding the install directory of an older version (/Applications/oxygen). It seems that operation does not override correctly all files in the frameworks directory (/Applications/oxygen/frameworks), particularly oxygen/frameworks/docbook/docbook5.framework. I suggest first dragging the old Oxygen install directory to Trash and emptying the Trash before overriding it with the newer version of Oxygen. Or alternatively unzipping the oxygen.zip archive in a different directory, for example on the Desktop, and starting Oxygen 16.0 from this new location.

I cannot explain why my copy of Oxygen contains WebHelp transform definitions that are missing the xml-apis.jar reference. Can you double-check that you tested with the latest 16.0 update, build 2014052022? Does your test Mac have developer-oriented class path or library settings that find the xml-apis.jar file independent of the transform's list of libraries?

I tested on a clean Oxygen 16.0 install kit. Please unzip the oxygen.zip kit in a different directory, not in /Applications, for example on the Desktop, ant start Oxygen 16.0 from that location. Also check if the Default option is selected in Options -> Preferences -> Document Type Association / Locations.


Regards,
Sorin

[Ordinant]

Hi Sorin,

That is probably it! I gather that you always install a newer version by overriding the install directory of an older version ...

You seem so attached to this theory, Sorin, that I almost hate to burst the bubble. However, the truth is that I never, ever, under any circumstances, overwrite one Oxygen release with another. Your OS X download page explicitly forbids overwriting in its instructions. You will be delighted to learn that some of your users actually do read and follow your instructions.

But your note did provide enough information to solve the problem without workarounds. Here is what I have always done with Oxygen releases on OS X:

• Rename /Applications/oxygen, appending the number of the version it contains. For example, rename oxygen to oxygen_15.2. (I do this because you guys have a LOT of maintenance releases in quick succession, and sometimes we need to back down to a previous release.)

• Download the new release and open the resulting zip file in WinZip Mac.

• Drag the oxygen folder from WinZip Mac to /Applications.

The issue in this thread is caused by my using /Applications, which I was using because that is where all OS X applications should be installed. This makes the /Applications/oxygen folder and its contents read-only, which is where the problems begin. Under these circumstances, when I open Options -> Preferences -> Document Type Association and double-click DocBook 5 (to change the default initial edit mode to my preference), I am prompted that DocBook 5 is read-only, and would I like to make a copy and use that instead? I say yes, and thereafter use "DocBook 5 - Copy".

On your suggestion, I reinstalled Oxygen into /Users/mylogin/Applications/oxygen, and on opening the Document Type Associations page, clicked the Restore Defaults button. This removed my various * - Copy frameworks. When I looked inside the WebHelp - Mobile framework in this scenario, it did indeed contain 20 library references, not 19, including xml-apis.jar. Building both WebHelp and WebHelp Mobile work fine under these circumstances.

Obviously, I will continue to install new versions of Oxygen into ~/Applications instead of /Applications. However, I am still hard-pressed to explain why using an editable copy of the DocBook 5 framework could lose one line, the xml-apis.jar line, compared to the original. I did nothing deliberate to make that change.

You now have enough information to duplicate the issue, if you wish. I can't be the only user installing into /Applications. But I notice that, having now used Oxygen from ~/Applications, when I go back to the one in /Applications, I no longer get the prompt about read-only frameworks. So you might only be able to duplicate the issue if you clean out ~/Library/Preferences/com.oxygenxml and other private settings folders.

I'm now sending to Trash all copies of Oxygen except the one in ~/Applications/oxygen, which is working as designed.

Thanks!
~Barton Wright

[sorin_ristache]

The issue in this thread is caused by my using /Applications, which I was using because that is where all OS X applications should be installed. This makes the /Applications/oxygen folder and its contents read-only, which is where the problems begin. Under these circumstances, when I open Options -> Preferences -> Document Type Association and double-click DocBook 5 (to change the default initial edit mode to my preference), I am prompted that DocBook 5 is read-only, and would I like to make a copy and use that instead? I say yes, and thereafter use "DocBook 5 - Copy".

The "DocBook 5 - Copy" should be a copy of the original one, including 20 libraries in both built-in WebHelp transformations. The duplication operation does not modify the content of the framework.

Obviously, I will continue to install new versions of Oxygen into ~/Applications instead of /Applications. However, I am still hard-pressed to explain why using an editable copy of the DocBook 5 framework could lose one line, the xml-apis.jar line, compared to the original. I did nothing deliberate to make that change.

It seems a DocBook 5 framework from an older version was used in the newer version. This is why I asked you to check if the Default option is selected in Options -> Preferences -> Document Type Association / Locations, which should point to the OXYGEN_LATEST_VERSION_INSTALL_DIR/frameworks directory.

You now have enough information to duplicate the issue, if you wish. I can't be the only user installing into /Applications.

There are many users installing Oxygen on Mac in the /Applications directory but you are the first reporting this problem with a missing library in a built-in framework.

I'm now sending to Trash all copies of Oxygen except the one in ~/Applications/oxygen, which is working as designed.

Thank you for letting us know. I am glad it works correctly now for you, too.


Regards,
Sorin

[Ordinant]

Hi Sorin,

This is why I asked you to check if the Default option is selected in Options -> Preferences -> Document Type Association / Locations

I forgot to report on that. The answer is: of course the Default option is selected, and always has been. I have never even looked at that page of the preferences until now.

It seems a DocBook 5 framework from an older version was used in the newer version

Yes, and now we know how. The DocBook 5 - Copy framework was stored in my personal preference settings, probably in ~/Library/Preferences/com.oxygenxml. I probably created the - Copy framework years ago, with Oxygen 12 or 13, or perhaps even earlier. Because the framework was in personal preferences, it was never overwritten by Oxygen upgrades, and thus survived unchanged. I was always pleased that I could install a new Oxygen release and find settings like that ready to run without having to start over.

It now appears that starting over would have been a good idea. Perhaps Oxygen, as part of starting up the first time after an upgrade, should run a scan of frameworks stored in personal settings, compare them to the latest version, report possible incompatibilities, and offer to fix those. Because users can name their personal frameworks anything, you could match by contents, or by comparing similar names, such as DocBook 5 - Copy compared to the latest DocBook 5.

For me, the issue is now moot, because I am now gritting my teeth and installing Oxygen in ~/Applications. This removes the read-only problem for frameworks, and thus removes the need for me to make a copy. I never intended to edit the Oxygen-provided frameworks, and am happy to use those as provided. I only made the - Copy version because Oxygen required me to.

Thanks for such an excellent product. Every day, I learn more practical details about the efficiencies that Oxygen provides, and am continually amazed.

[sorin_ristache]

Hi,

It now appears that starting over would have been a good idea. Perhaps Oxygen, as part of starting up the first time after an upgrade, should run a scan of frameworks stored in personal settings, compare them to the latest version, report possible incompatibilities, and offer to fix those.

Thank you for the suggestion.


Regards,
Sorin