Images, file-naming conventions, and cross-referencing in Docbook

[Christine Doyle <christine.doyle@gmail.com>]

Hi,

I'm new to Docbook and am investigating converting our RoboHelp files to Docbook format to enable TOC generation for Eclipse plugin help. If we move to Docbook we can automate our help into the build process.

 

I'm now using the Oxygen eclipse plugin on Windows to author my documents in Docbook 4.4 format. It provides very good validation and content assistance and a Docbook framework. I tried running the eclipse.xsl transform on one of my sample books using the Oxygen plugin in Eclipse, but found that although the transform omits a successful message, no output was produced. I have now succeeded in running the eclipse.xsl transform using the command line for the saxon xslt processor:

 

java  -jar dir/saxon.jar   [options]   source-document   stylesheet   [ params…]

 

For example:

java -jar c:/eclipse/plugins/com.oxygenxml.editor_7.0.0/lib/saxon.jar concepts/concepts.xml c:/eclipse/plugins/com.oxygenxml.editor_7.0.0/frame
works/docbook/xsl/eclipse/eclipse.xsl base.dir="html/concepts/"

 

I have two main questions:

 

1. My images are not displaying. Here is an example of one that is not displaying:

 

 <figure><title>blah...</title>
    <mediaobject>
        <imageobject role="html">
          <imagedata fileref="blah_2b.png" format="PNG"></imagedata>
        </imageobject>
    </mediaobject>
  </figure>

 

Can anyone suggest why this image would not display? It is in the same folder as the XML file that references it. Note that I am working from within an Eclipse project directory. Could this be an issue? Or is there a problem with the syntax? Do I need to declare blah_2b.png as an entity somewhere or place it in a different location? 

 

2. When I run eclipse.xsl, the Docbook HTML files that are produced have automatically generated file names, using a numeric convention, for example:

 

Writing pr01s02.html for section
Writing pr01s03.html for section
Writing pr01s04.html for section
Writing pr01s05.html for section
Writing pr01s06.html for section
Writing pr01.html for preface
Writing ch01s02.html for sect1
Writing ch01.html for chapter
Writing ch02s02.html for sect1
Writing ch02s03.html for sect1
Writing ch02.html for chapter
Writing index.html for book
Writing toc.xml
Writing plugin.xml

 

These file names do not match my source XML file names, which are mnemonic, based on the content. This means that all of my original Robohelp cross-references are broken. How can I customize the file naming generation process? Also, what is the best way to create cross-references between files? There seem to be several Docbook elements for cross-referencing, and as I'm new to Docbook, it's quite confusing. I'm using Docbook 4.4.

 

<link> seems to be the easiest way to do internal references but what about between chapters? Should I provide an id for every section and link to sections using <ulink>?

 

I'd appreciate any advice.

 

Regards

 

Christine Doyle