How-to-visualize-docbook-files-in-browser

target audience

This how-to helps people having an existing set of .docbook files who want to see a preview of these files in a browser.

Example: an existing documentation manual has to be updated and the changes must be checked before creating a merge request.

Pre-requisites

operating system: a Linux distribution or MacOS
Having a local version of the documentation which needs to be visualized ^[1]
Having KDocTools installed^[2]. This software is used to:
1. check the .docbook files for XML consistency or errors
2. generate .html files out of the .docbook files

You may read the online documentation of KDocTools. It also explains the usage of KDocTools (meinproc6 and checkXML6 commands.)

1) Check .docbook files for XML consistency and errors

Generally, we want to update one single documentation item, i.e. a single .docbook file.

Warning

The .docbook files are NOT standalone, as there are definitions set in index.docbook needed for properly processing all the other docbook files.

Even if nothing has been changed in the index.docbook file, this is the one we will call in the commands below.

This process checks the technical XML quality within the .docbook files:

go into the local folder where the manual documentation is stored
open a terminal
run this command:
```
checkXML6 index.docbook
```
if the command runs without errors, you are done, there are no XML errors in the files. Else, analyse and fix the errors.

Information

Your computer may have another version of KDocTools than version 6. In that case, replace (e.g. for version 5) checkXML6 by checkXML5.

2) Visualize the local .docbook files

The .docbook files must be converted into .html files so that a browser can display them as they will really look like later.

Again, irrespective of the really updated .docbook file, the command needs to target the index.docbook file.

Check the location of KDocTools stylesheets

Depending on the operating system, the KDocTools stylesheets may be stored at different places.

Example for distribution Debian bookworm, the stylesheets are located under: /usr/share/kf6/kdoctools/customization/:

List of stylesheets files (KDocTools6)
Filename
kde-chunk.xsl
kde-chunk-common.xsl
kde-chunk-online.xsl
kde-include-common.xsl
kde-include-man.xsl
kde-navig.xsl
kde-navig-online.xsl
kde-nochunk.xsl
kde-style.xsl
kde-ttlpg.xsl
kde-ttlpg-online.xsl
kde-web.xsl
kde-web-navig.xsl

Generate the .html files

go into the local folder where the manual documentation is stored
open a terminal
run this command (replace the 6 in meinproc6 by a lower/higher number according to your operating system):
```
meinproc6 --stylesheet /usr/share/kf6/kdoctools/customization/kde-web.xsl index.docbook
```
Result: a bunch of .html files have been created, one (sometimes more) for each existing .docbook file. The .html files are located in the same folder as the .docbook files.
open the index.html file in a browser and navigate to the documentation page you have updated to check its look and feel.

Note

KDocTools provides several stylesheets. You may replace the argument "kde-web.xsl" by another one in the command.

Following tasks

After having tested that all changes are fine, you may create a merge request against the software documentation, supposing it is hosted on KDE Gitlab.

Warning

Do not forget to first delete all the .html files you created from within the /doc/ folder, otherwise they will be included into the merge request.

Notes

↑
The best way is to make a local clone of the relevant git repository which contains the .docbook files to be edited. You can download the master branch of the software whose user manual you want to update. For this, you may want to set-up your local Gitlab (Wiki instructions):
1. create a SSH private and public keys.
2. update your account on https://invent.kde.org/ with it.
3. relate it to the gitlab instance via ssh -T [email protected].
4. if you don’t want to deal with the git command line, you can install one of the many appropriate graphical front ends to manage Gitlab. You can install git-cola for example. In Git-cola,
  1. Click on "new", choose the directory where you will store all the files of the software you are working on (the one you want to update the documentation manual of)
  2. in the top menu, use Branch/Create.
  3. Make sure to select the master branch as start point (1), name your local branch (2) for example : work/my_KDE_username/... (replace my_KDE_username by your real username) and create the branch (3).
  4. After this, you should see the /doc folder containing all the .docbook files of the software within the directory you created three steps above.
↑ Use your distribution’s package manager to install KDocTools6 (example for Debian-based distributions:run the command: sudo apt install kdoctools6 - replace the 6 at the end by a lower/higher number if your distribution packages it)

[1] The best way is to make a local clone of the relevant git repository which contains the .docbook files to be edited. You can download the master branch of the software whose user manual you want to update. For this, you may want to set-up your local Gitlab (Wiki instructions):
create a SSH private and public keys.

update your account on https://invent.kde.org/ with it.

relate it to the gitlab instance via ssh -T [email protected].

if you don’t want to deal with the git command line, you can install one of the many appropriate graphical front ends to manage Gitlab. You can install git-cola for example. In Git-cola,
Click on "new", choose the directory where you will store all the files of the software you are working on (the one you want to update the documentation manual of)

in the top menu, use Branch/Create.

Make sure to select the master branch as start point (1), name your local branch (2) for example : work/my_KDE_username/... (replace my_KDE_username by your real username) and create the branch (3).

After this, you should see the /doc folder containing all the .docbook files of the software within the directory you created three steps above.

[2] reate a SSH private and public keys.

[3] update your account on https://invent.kde.org/ with it.

[4] relate it to the gitlab instance via ssh -T [email protected].

[5] you don’t want to deal with the git command line, you can install one of the many appropriate graphical front ends to manage Gitlab. You can install git-cola for example. In Git-cola,
Click on "new", choose the directory where you will store all the files of the software you are working on (the one you want to update the documentation manual of)

in the top menu, use Branch/Create.

Make sure to select the master branch as start point (1), name your local branch (2) for example : work/my_KDE_username/... (replace my_KDE_username by your real username) and create the branch (3).

After this, you should see the /doc folder containing all the .docbook files of the software within the directory you created three steps above.

[6] Click on "new", choose the directory where you will store all the files of the software you are working on (the one you want to update the documentation manual of)

[7] the top menu, use Branch/Create.

[8] Make sure to select the master branch as start point (1), name your local branch (2) for example : work/my_KDE_username/... (replace my_KDE_username by your real username) and create the branch (3).

[9] After this, you should see the /doc folder containing all the .docbook files of the software within the directory you created three steps above.

[2] Use your distribution’s package manager to install KDocTools6 (example for Debian-based distributions:run the command: sudo apt install kdoctools6 - replace the 6 at the end by a lower/higher number if your distribution packages it)

[11] reate a SSH private and public keys.

[12] update your account on https://invent.kde.org/ with it.

[13] relate it to the gitlab instance via ssh -T [email protected].

[14] you don’t want to deal with the git command line, you can install one of the many appropriate graphical front ends to manage Gitlab. You can install git-cola for example. In Git-cola,
Click on "new", choose the directory where you will store all the files of the software you are working on (the one you want to update the documentation manual of)

in the top menu, use Branch/Create.

Make sure to select the master branch as start point (1), name your local branch (2) for example : work/my_KDE_username/... (replace my_KDE_username by your real username) and create the branch (3).

After this, you should see the /doc folder containing all the .docbook files of the software within the directory you created three steps above.

[15] Click on "new", choose the directory where you will store all the files of the software you are working on (the one you want to update the documentation manual of)

[16] the top menu, use Branch/Create.

[17] Make sure to select the master branch as start point (1), name your local branch (2) for example : work/my_KDE_username/... (replace my_KDE_username by your real username) and create the branch (3).

[18] After this, you should see the /doc folder containing all the .docbook files of the software within the directory you created three steps above.

[19] Click on "new", choose the directory where you will store all the files of the software you are working on (the one you want to update the documentation manual of)

[20] the top menu, use Branch/Create.

[21] Make sure to select the master branch as start point (1), name your local branch (2) for example : work/my_KDE_username/... (replace my_KDE_username by your real username) and create the branch (3).

[22] After this, you should see the /doc folder containing all the .docbook files of the software within the directory you created three steps above.

[1]

[2]