Usage

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

Outline

DocBook is an XML-based document format that focusses on structure and semantics. DocBook's book template is very appropriate for writing user documentation files. You may convert them into HTML files or PDFs using open (free) tools like xsltproc and / Apache FOP.

Now, when building Qt applications, what about reusing your user documentation for the applications' help pages? This is what db2qthelp does.

Prerequisites

db2qthelp requires some prerequisites. In the most convenient use case, db2qthelp calls xsltproc to convert your DocBook book document into a set of HTML files, first. Then, it processes those files by embedding CSS styles and collects them for being listed in the resulting Qt Help. It then runs Qt Help processors for finally obtaining Qt Help pages. This is all done by just running:

db2qthelp.py -i userdocs.xml

Yet, for doing this, your system should be capable to call xsltproc and qhelpgenerator directly, so you have to add the respective folders:

set PATH=%PATH%;D:\Qt\5.15.2\msvc2019\bin;D:\docbook\libxslt-1.1.26.win32\bin

(of course, the path depend on where you have stored the respective binaries; and — this is for Windows)

Alternatively, you may pass the paths to db2qthelp using the options --xslt-path <XSLT_PATH> (-X <XSLT_PATH>) and --qt-path <QT_BINARIES_PATH> (-Q <QT_BINARIES_PATH>).

In addition, db2qthelp uses custom xsl (XML style sheets, or Extensible Stylesheet Language files) for building documents. As such, you have to let the system know where your xsl are located by setting the XML_CATALOG_FILES variable used by xsltproc:

set XML_CATALOG_FILES=D:\docbook\docbook-xsl-1.79.2\catalog.xml

Building help files

As given above, you may directly convert your DocBook book into Qt Help using a basic call:

db2qthelp.py -i userdocs.xml

db2qthelp recognises that it's a DocBook book by the extension — .xml.

Using this call, db2qthelp will write the intermediate files and the results into the folder qtdocs. A built-in CSS definition will be used and the application's name within the Qt Help files will be set to na. You will need this name when using the Qt Help filter in your application.

Of course, you may change this. The application name can be set using the option --appname <APP_NAME>. You may let db2qthelp use your own CSS definition using the option --css-definition <CSS_FILE>. You may as well export the default one using the option --generate-css-definition — the filename it will be stored under is the one given using --css-definition or template.css if no name is set.

Same for the qhp file used for building Qt Help files. You may export the default one using --generate-qhp-template and use your own one by setting the option --qhp-template <APP_NAME>. Again, the filename used when writing the template is either template.qhp or the one you set using --qhp-template.

Per default, db2qthelp will write the generated files to the folder qtdocs. You may choose a different output folder using the --destination <FOLDER> (or -d <FOLDER> for short) option.

Alternatives

The first version of db2qthelp did not convert the DocBook document, but processed HTML obtained by running the chunking HTML exporter with xsltproc. This possibility still exists, as well as using a single HTML file as input.

When running db2qthelp with a HTML file as input as shown below, it will process this file and generate according Qt Help files. db2qthelp will assume that the input is a single HTML file if it has the extension .html.

db2qthelp.py -i userdocs.html

When the value of the input-option points to a folder, db2qthelp will assume that this folder contains chunked HTML output generated by xsltproc. In this case, all HTML files within this folder will be collected and processed.

Configuration files

You may write all your settings into a configuration file and let db2qthelp process it using the option --config <CONFIG_FILE> (or -c <CONFIG_FILE> for short). A configuration file may look like this:

[db2qthelp]
input=userdocs.xml
xslt-path=D:\docbook\libxslt-1.1.26.win32\bin
qt-path=D:\Qt\5.15.2\msvc2019\bin

Docbook customization

db2qthelp uses an own Docbbok XML style sheet (xsl) named single_html.xsl located in the data sub-folder.

Most of the values should be kept as-are, but you may want to adapt it to your needs anyway. There is no option for using an own style sheet, yet.