DocBook WebHelp Transformation

Frankwin
Posts: 4

DocBook WebHelp Transformation

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

Re: DocBook WebHelp Transformation

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

Re: DocBook WebHelp Transformation

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

Re: DocBook WebHelp Transformation

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

Return to “DocBook”

Who is online

Users browsing this forum: No registered users and 1 guest