Running on the Command Line

db2qthelp is implemented in Python. It is started on the command line.

Description

db2qthelp requires some prerequisites. In the following, the steps for a QtHelp from a DocBook book are described.

Preparing your DocBook document

You should have a user documentation written as a DocBook book. Images should be stored in a subfolder, at best one that is located in the same folder as the DocBook document itself. E.g. if you have a project, you may have a folder “docs” in which the document itself (“docs/userdocs.xml”) is located and the images / figures it references are located in “docs/images/*”.

Converting DocBook to HTML

In the first step, you have to convert this document to a single-HTML document. Being in the docs folder, I use xsltproc for this using a call similar to this one:

xsltproc.exe --output userdocs.html single_html.xsl userdocs.xml

Here, “single_html.xsl” is a slightly modified DocBook style sheet. You may find it in this package under “data/single_html.xsl”. Please not that you have to update the references to your docbook stylesheets location.

What we get is a HTML-representation of the DocBook user docs named “userdocs.html”.

Prepare the QtHelp template

We now need a template for our QtHelp project. Generate it using db2qthelp by calling:

db2qthelp --generate

You will get a file named “template.qhp”. It should be located in the same folder as your DocBook document. You may though name it differently to set it's name on generation use:

db2qthelp --generate --template new_template_name.qhp

Open it in an editor. It should look like this:

<?xml version="1.0" encoding="latin1"?>
<QtHelpProject version="1.0">
    <namespace>%source%</namespace>
    <virtualFolder>doc</virtualFolder>
    <filterSection>
        <filterAttribute>%appname%</filterAttribute>
        <toc>
%toc%
        </toc>
        <keywords>
%keywords%
        </keywords>
        <files>
            <file>*.html</file>
            <file>*.png</file>
            <file>*.gif</file>
        </files>
    </filterSection>
</QtHelpProject>

You may note that there are some placeholders. Both will be later on filled by db2qthelp

  • %source% is the complete URL to your documentation, it usually looks like “org.foo.bar.MyFancyApp_v0.1”
  • %appname% is your application name (e.g. “MyFancyApp”)
  • %toc% will be replaced by the documentation's structure (table of contents)
  • %keywords% will be replaced by the collected keywords

You may add additional filter attributes.

Generate the QtHelp

Well, that's almost everything. Run db2qthelp again to build the documentation:

db2qthelp -i userdocs.html -t new_template_name.qhp -s org.foo.bar.MyFancyApp_v0.1 -a MyFancyApp -p c:\Qt\bin

The options tell db2qthelp to read the HTML document “userdocs.html” generated from our original DocBook book, to use our project template “new_template_name.qhp” and that images and figures are located in “images”.

As we did not define the destination folder, db2qthelp uses the default “qtdocs”.

The built documentation can be found in the destination folder. You need two files to include it in your application:

  • <APPLICATION_NAME>.qch
  • <APPLICATION_NAME>.qhc

Options

The script has the following options:

  • --input/-i <DOCBOOK_HTML>: Defines the DocBook HTML document to parse
  • --appname/-a <APPLICATION_NAME>: Sets the name of the application
  • --source/-s <ADDITIONAL_FILES_FOLDER>: Sets the documentation source url
  • --files/-f <ADDITIONAL_FILES_FOLDER>[,<ADDITIONAL_FILES_FOLDER>]*: Sets the folder(s) to collect files from
  • --destination/-d <DESTINATION_FOLDER>: Sets the output folder
  • --template/-t <TEMPLATE_FILE>: Defines the QtHelp project template to use; default: ‘template.qhp’
  • --generate/-g: If set, the template is written to the file as defined by --template; The application quits afterwards
  • --path/-p <QT_PATH>: Sets the path to the Qt binaries to use
  • --help: Prints the help screen

Explanation

db2qthelp copies .png and .gif-files from the folders defined using --files, first.

It then reads the HTML-file generated from DocBook defined using --input and processes it. Processing means here that the file is split at sections and appendices. Each subpart is written into the destination folder defined using --destination and included in the table of contents (toc). The paths to references images as defined using --files are replaced by the destination path defined using --destination. In addition, the headers are included in the list of keywords.

Then, the qhp-templated defined using --template is loaded and the placeholders (see above) are replaced by the given / collected data.

db2qthelp generates a qhcp file afterwards as “<DESTINATION_FOLDER>/<APPLICATION_NAME>.qhcp”.

Finally, the script calls two QtHelp processing applications which must be located in the folder defined using --path:

<QT_PATH>/qhelpgenerator <APPLICATION_NAME>.qhp -o <APPLICATION_NAME>.qch
<QT_PATH>/qcollectiongenerator <APPLICATION_NAME>.qhcp -o <APPLICATION_NAME>.qhc

Examples

db2qthelp --generate

Generates the project template file “template.qhp”.

db2qthelp -i userdocs.html -t template.qhp -s org.foo.bar.MyFancyApp_v0.1  --path c:\Qt\bin

Reads the HTML document “userdocs.html” and the project template “template.qhp” and converts the HTML document to QtHelp assuming images etc. being located in “images”. The Qt binaries are assumed to be found in “c:\Qt\bin\”.