DocBook WebHelp Transformation

Frankwin
Posts: 4
Joined: Wed Sep 19, 2012 8:16 pm

DocBook WebHelp Transformation

Post by Frankwin » Wed Sep 19, 2012 8:28 pm

Hi,

We recently started using Oxygen to author our help files for our product and converted our custom XML schema documentation to the DocBook schema. We're running into some issues though when trying to transform this to the DocBook WebHelp format.

The issues we're seeing are:
1. When transforming, none of our pictures are included. This is likely due to how we've setup our folder structure for our DocBook Oxygen project, so I'm wondering what the recommended folder structure setup is for a DocBook project in Oxygen. We currently have something like:

Code: Select all


root
images
topic 1
images
subtopic 1
images
subtopic 2
images
topic 2
images
topic 3
images
Our root folder contains the index.xml for the DocBook book, as well as some of our generic help files, things like contact us, etc.
Each of our topic folders contains all the help files for that topic. Some of our topic folders also contain sub-topic folders for any sub-topics, etc. Each of our (sub)topics folder has it's own images folder to store all the images for that particular (sub)topic.
These are all physical folders, not virtual ones.

2. When doing the transformation, the entire text of all of our (sub)topics turns into a link, except for the last page, which displays normally.
I'm suspecting this has something to do with us missing something somewhere, or how our index.xml is setup.
Our (test) index.xml contains the following:

Code: Select all


<?xml version="1.0" encoding="UTF-8"?>
<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
<article xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
<title>SkedFlex User Help</title>
<xi:include href="Topic1/topic1.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
<xi:include href="Topic2/topic2.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
</article>
Any help in resolving these issues would be appreciated.

sorin_ristache
Posts: 4144
Joined: Fri Mar 28, 2003 2:12 pm

Re: DocBook WebHelp Transformation

Post by sorin_ristache » Thu Sep 20, 2012 5:11 pm

Hi,
Frankwin wrote:1. When transforming, none of our pictures are included. This is likely due to how we've setup our folder structure for our DocBook Oxygen project, so I'm wondering what the recommended folder structure setup is for a DocBook project in Oxygen. We currently have something like:

Code: Select all


root
images
topic 1
images
subtopic 1
images
subtopic 2
images
topic 2
images
topic 3
images
There is nothing wrong with your folder structure. There is a problem in the DocBook WebHelp transformation with images in nested folders with a nesting depth greater than one which we just fixed in the current development stream. The fix will be included in Oxygen 14.1 which we will release in October. If you cannot wait until version 14.1 we can provide a nightly build that includes the fix, please contact us by email (support at oxygenxml dot com).
Frankwin wrote:2. When doing the transformation, the entire text of all of our (sub)topics turns into a link, except for the last page, which displays normally.
We fixed a bug that manifested like that before release 14.0, which means you should not get this problem anymore if you run Oxygen 14.0 (the current version available on the Download page). What Oxygen version and build number do you run? You can see that in the Help -> About dialog box. If you get this problem in Oxygen 14.0 please send us a set of sample files (source XML files, images files, etc) for reproducing the problem.


Regards,
Sorin

Frankwin
Posts: 4
Joined: Wed Sep 19, 2012 8:16 pm

Re: DocBook WebHelp Transformation

Post by Frankwin » Thu Sep 20, 2012 5:55 pm

Hi Sorin,
sorin wrote: There is nothing wrong with your folder structure. There is a problem in the DocBook WebHelp transformation with images in nested folders with a nesting depth greater than one which we just fixed in the current development stream. The fix will be included in Oxygen 14.1 which we will release in October. If you cannot wait until version 14.1 we can provide a nightly build that includes the fix, please contact us by email (support at oxygenxml dot com).
Ok I will send an email to support as I do need this.
sorin wrote:
Frankwin wrote:2. When doing the transformation, the entire text of all of our (sub)topics turns into a link, except for the last page, which displays normally.
We fixed a bug that manifested like that before release 14.0, which means you should not get this problem anymore if you run Oxygen 14.0 (the current version available on the Download page). What Oxygen version and build number do you run? You can see that in the Help -> About dialog box. If you get this problem in Oxygen 14.0 please send us a set of sample files (source XML files, images files, etc) for reproducing the problem.
I am using the latest version, updated yesterday actually : <oXygen/> XML Author 14.0, build 2012082911

I'll send the files as well.

Thanks,

Frankwin

sorin_ristache
Posts: 4144
Joined: Fri Mar 28, 2003 2:12 pm

Re: DocBook WebHelp Transformation

Post by sorin_ristache » Fri Sep 28, 2012 10:19 am

Hi,

Just to update the discussion here for the other users:

1. The nightly build of Oxygen 14.1 beta fixed the problem with the images not visible in the DocBook WebHelp output.

2. Version 14.1 will probably include a fix (or rather a workaround for a web browser bug, see below) for the problem with the text content rendered as a single big hyperlink in the output. In the meantime a simple workaround is to avoid empty <title/> elements (an empty DocBook section title) in the source XML document. That is because an empty <title/> element in the source XML document results in an empty <a href="..."/> element in the WebHelp output which hits a web browser bug which causes the browser to render the text content as a single big hyperlink.


Regards,
Sorin

Post Reply