Check out Get Involved/documentation - KDE Community Wiki I’m not sure if it’s all up to date, but it should point you in the right direction.
- I also edit docfiles directly in emacs. Compiling from docbook to html is done with meinproc6, and I do not know of any WYSIWYG editor for docfiles, and I’m not completely sure I would trust any. I am perfectly happy if you send me plain text edits and I can translate into the docbook format.
- I will send you directly a copy of the .kmy file I have used for generating the png files in the 5.20 manual. I do not know of any other test files easily available.
- the suggestion from mrp is a good place to start for learning about docbook. It’s where I started many years ago.
Thanks @ostroffjh.
Writing documentation is not so straightforward… 
It feels like to pull a thread which always jumps from node to node and never ends.
- I have started reading the documentation on this page KDE Localization - Joining the KDE Documentation Team.
- There, they recommand Kate for editing DocBook files: Using Kate
ok, i already had it on my computer. Good. - I had also to install KdocTools to be able to have an preview of the DocBook file in a HTML way. I installed it through this command
sudo apt install kdoctools5 - Moreover since i don’t have the Konqueror browser on my computer, this stylesheet is required according to documentation:
kde-web.xslfrom src/customization · master · Frameworks / KDocTools · GitLab
So, and before i change anything to the docbook file details-institutions.docbook, i though i start training with these Kdoctools named in Checking and Viewing the Documents on the existing “safe” docbook file. I quote the documentation:
meinproc5 and checkXML5.
checkXML5 (as the name suggests) is used to check that documents are valid, well-formed XML
meinproc5 converts DocBook files to HTML.
I tried to let them run and failed twice:
The git clone of master branch is saved in this folder: /home/otto/Documents/banque/Reporting/K_Ma_Monnaie/gitlab/clone_git/kmymoney/
I saved the single file kde-web.xsl in two directories “above” the master branch doc folder, namely in /home/otto/Documents/banque/Reporting/K_Ma_Monnaie/gitlab/, since this file is required as a stylesheet according to documentation:
To produce output suitable for the web, you can use
kde-web.xsl
A) checkXML5
checkXML5 details-institutions.docbook produces this:
Here the terminal output as a text:
~/Documents/banque/Reporting/K_Ma_Monnaie/gitlab/clone_git/kmymoney/doc$ checkXML5 details-institutions.docbook
details-institutions.docbook:2: validity error : Validation failed: no DTD found !
<chapter id="details.institutions">
^
details-institutions.docbook:5: parser error : Entity 'Roger.Lum' not defined
<author> &Roger.Lum; &Roger.Lum.mail; </author>
^
details-institutions.docbook:5: parser error : Entity 'Roger.Lum.mail' not defined
<author> &Roger.Lum; &Roger.Lum.mail; </author>
^
details-institutions.docbook:6: parser error : Entity 'Jack.H.Ostroff' not defined
<author> &Jack.H.Ostroff; &Jack.H.Ostroff.mail; </author>
^
details-institutions.docbook:6: parser error : Entity 'Jack.H.Ostroff.mail' not defined
<author> &Jack.H.Ostroff; &Jack.H.Ostroff.mail; </author>
^
details-institutions.docbook:14: parser error : Entity 'kmymoney' not defined
Institutions in &kmymoney; serve as a way to group accounts. They are most
^
details-institutions.docbook:98: parser error : Entity 'kmymoney' not defined
sort code in the UK. It is not currently used by &kmymoney;.
^
details-institutions.docbook:167: parser error : Entity 'kmymoney' not defined
by &kmymoney;, but some items may be required by future releases for certain
^
kf.doctools.core: Error: `xmllint --noout` outputted text
B) meinproc5
meinproc5 --stylesheet /home/otto/Documents/banque/Reporting/K_Ma_Monnaie/gitlab/kde-web.xsl details-institutions.docbook produces this:
Here the terminal output as a text:
~/Documents/banque/Reporting/K_Ma_Monnaie/gitlab/clone_git/kmymoney/doc$ meinproc5 --stylesheet /home/otto/Documents/banque/Reporting/K_Ma_Monnaie/gitlab/kde-web.xsl details-institutions.docbook
I/O warning : failed to load external entity "/home/otto/Documents/banque/Reporting/K_Ma_Monnaie/gitlab/kde-include-common.xsl"
compilation error: file /home/otto/Documents/banque/Reporting/K_Ma_Monnaie/gitlab/kde-web.xsl line 4 element import
xsl:import : unable to load /home/otto/Documents/banque/Reporting/K_Ma_Monnaie/gitlab/kde-include-common.xsl
I/O warning : failed to load external entity "/home/otto/Documents/banque/Reporting/K_Ma_Monnaie/gitlab/kde-web-navig.xsl"
compilation error: file /home/otto/Documents/banque/Reporting/K_Ma_Monnaie/gitlab/kde-web.xsl line 5 element include
xsl:include : unable to load /home/otto/Documents/banque/Reporting/K_Ma_Monnaie/gitlab/kde-web-navig.xsl
I/O warning : failed to load external entity "/home/otto/Documents/banque/Reporting/K_Ma_Monnaie/gitlab/kde-ttlpg.xsl"
compilation error: file /home/otto/Documents/banque/Reporting/K_Ma_Monnaie/gitlab/kde-web.xsl line 6 element include
xsl:include : unable to load /home/otto/Documents/banque/Reporting/K_Ma_Monnaie/gitlab/kde-ttlpg.xsl
I/O warning : failed to load external entity "/home/otto/Documents/banque/Reporting/K_Ma_Monnaie/gitlab/kde-style.xsl"
compilation error: file /home/otto/Documents/banque/Reporting/K_Ma_Monnaie/gitlab/kde-web.xsl line 7 element include
xsl:include : unable to load /home/otto/Documents/banque/Reporting/K_Ma_Monnaie/gitlab/kde-style.xsl
kf.doctools.core: Error: Unable to parse "details-institutions.docbook"
I don’t really know how to come forward.
Is there any issue on my side? Does my distribution (Debian 12) have an outdated Kdoctools version?
Here is the installation script output:
~/Documents/banque/Reporting/K_Ma_Monnaie/gitlab/clone_git/kmymoney/doc$ sudo apt install kdoctools5
[sudo] Mot de passe de otto :
Lecture des listes de paquets... Fait
Construction de l'arbre des dépendances... Fait
Lecture des informations d'état... Fait
Les paquets suivants ont été installés automatiquement et ne sont plus nécessaires :
kde-cli-tools-data libkf5pty-data libkf5pty5 libkf5su-bin libkf5su-data libkf5su5
Veuillez utiliser « sudo apt autoremove » pour les supprimer.
Les paquets supplémentaires suivants seront installés :
docbook-xsl libxml2-utils
Paquets suggérés :
dbtoepub docbook-xsl-doc-html | docbook-xsl-doc-pdf | docbook-xsl-doc-text | docbook-xsl-doc docbook-xsl-saxon fop libsaxon-java libxalan2-java libxslthl-java xalan
Les NOUVEAUX paquets suivants seront installés :
docbook-xsl kdoctools5 libxml2-utils
0 mis à jour, 3 nouvellement installés, 0 à enlever et 2 non mis à jour.
Il est nécessaire de prendre 1 786 ko dans les archives.
Après cette opération, 19,0 Mo d'espace disque supplémentaires seront utilisés.
Souhaitez-vous continuer ? [O/n] o
Réception de :1 http://deb.debian.org/debian bookworm/main amd64 docbook-xsl all 1.79.2+dfsg-2 [1 237 kB]
Réception de :2 http://security.debian.org/debian-security bookworm-security/main amd64 libxml2-utils amd64 2.9.14+dfsg-1.3~deb12u2 [99,4 kB]
Réception de :3 http://deb.debian.org/debian bookworm/main amd64 kdoctools5 amd64 5.103.0-1 [450 kB]
1 786 ko réceptionnés en 1s (3 347 ko/s)
Sélection du paquet docbook-xsl précédemment désélectionné.
(Lecture de la base de données... 270371 fichiers et répertoires déjà installés.)
Préparation du dépaquetage de .../docbook-xsl_1.79.2+dfsg-2_all.deb ...
Dépaquetage de docbook-xsl (1.79.2+dfsg-2) ...
Sélection du paquet libxml2-utils précédemment désélectionné.
Préparation du dépaquetage de .../libxml2-utils_2.9.14+dfsg-1.3~deb12u2_amd64.deb ...
Dépaquetage de libxml2-utils (2.9.14+dfsg-1.3~deb12u2) ...
Sélection du paquet kdoctools5 précédemment désélectionné.
Préparation du dépaquetage de .../kdoctools5_5.103.0-1_amd64.deb ...
Dépaquetage de kdoctools5 (5.103.0-1) ...
Paramétrage de docbook-xsl (1.79.2+dfsg-2) ...
Paramétrage de libxml2-utils (2.9.14+dfsg-1.3~deb12u2) ...
Traitement des actions différées (« triggers ») pour sgml-base (1.31) ...
Traitement des actions différées (« triggers ») pour man-db (2.11.2-2) ...
Paramétrage de kdoctools5 (5.103.0-1) ...
or is the official documentation from Checking and Viewing the Documents which gives the hint kdoctools on outdated?
I suspect that doc suggests Kate because Kate is the default text editor for KDE. You can use any text editor. It is good if it can be configured to know about docbook files, so it can highlight some of the syntax and help with formatting. Use whatever editor you are comfortable with.
It will take time for a more detailed reply, but you now need kdoctools6 (or whatever your distro might call it. I suspect ‘sudo apt search kdoctools’ will show you the options. I don’t know of anything specific in our docbook files that should fail with kdoctools5 and not kdoctools6, but it is a place to start. meinproc and checkxml (use the 6 versions also) usually produce mostly the same errors, but with different verbosities, so it IS good to use both.
If you run meinproc without referring to the stylesheet, the result can be opened in khelpcenter for best viewing. However, it can be opened in any browser (I sometimes use Firefox) although the layout may not look very good.
In terms of running checkxml and meinproc, you are correct to run them in a folder outside the git clone, since the latter produces many files there. I have long forgotten whether it also copies the image files (png jpg) so check and copy them manually if necessary.
DTD files are "doctype definition"s (or something similar.) They give the formal syntax description of the docbook (and other) files. The error about DTD not found just says there is one or more package you still need to install. Search for something including docbook-xml. All the errors after that are just because it doesn’t know anything about what a .docbook file should look like - so everything might be an error.
Final point - both checkxml and meinproc always need to be run on index.docbook. The other docbook files are NOT standalone, as there are definitions set in index.docbook needed for properly processing all the other docbook files.
1 Like
Thanks for this info.
This means that the page Checking and Viewing the Documents is not up-to-date 
since it hints the 5th version.
-
I removed kdoctools5
sudo apt-get remove kdoctools5 -
i couldn’t install the version 6 from terminal,
sudo apt-get install kdoctools6seems not to work in my distro (Debian 12 bookworm). -
Anyway i downloaded kdoctools6_6.13.0-1_amd64.deb from https://pkgs.org/download/kdoctools6
- i couldn’t installt it either because of a dependency. Looks like i need
libkf6archive6
and i don’t know if this is the unique blocking point, or if other dependencies will arise when this one is solved.
- i couldn’t installt it either because of a dependency. Looks like i need
I am kind of stuck here…
A) checkXML5
ow i have missed this one !
Many thanks for the hint.
Now i run (after having reinstalling kdoctools5) checkXML5 index.docbook and the command runs without errors 
:
Though it doesn’t give any positive confirmation, like “everyting ok with these files”…
B) meinproc5
I run the command on index.docbook as you adviced:
meinproc5 --stylesheet /home/otto/Documents/banque/Reporting/K_Ma_Monnaie/gitlab/kde-web.xsl index.docbook
the result is:
I/O warning : failed to load external entity "/home/otto/Documents/banque/Reporting/K_Ma_Monnaie/gitlab/@DOCBOOKXSL_DIR@/html/autoidx.xsl"
compilation error: file /home/otto/Documents/banque/Reporting/K_Ma_Monnaie/gitlab/kde-include-common.xsl line 4 element import
xsl:import : unable to load /home/otto/Documents/banque/Reporting/K_Ma_Monnaie/gitlab/@DOCBOOKXSL_DIR@/html/autoidx.xsl
I/O warning : failed to load external entity "/home/otto/Documents/banque/Reporting/K_Ma_Monnaie/gitlab/@DOCBOOKXSL_DIR@/html/chunk.xsl"
compilation error: file /home/otto/Documents/banque/Reporting/K_Ma_Monnaie/gitlab/kde-include-common.xsl line 5 element import
xsl:import : unable to load /home/otto/Documents/banque/Reporting/K_Ma_Monnaie/gitlab/@DOCBOOKXSL_DIR@/html/chunk.xsl
kf.doctools.core: Error: Unable to parse "index.docbook"
it seems that this parameter @DOCBOOKXSL_DIR@ has not received any value (from where?)
How is your own gitlab folder organization on your local computer?
Do you have other folders for documentation next to the kmymoney folder?
I have this:
- kmymoney folder in
../gitlab/clone_git/ - single files downloaded into
../gitlab/folder (from Kdoctools in Github)
but i feel it may be the wrong approach to have downloaded them manually. They should be in this@DOCBOOKXSL_DIR@, shouldn’t they?
How have you set the value of @DOCBOOKXSL_DIR@ ?
I answer myself.
The stylesheet path in my command was wrong.
The proper path is /usr/share/kf5/kdoctools/customization/.
so the proper command is
meinproc5 --stylesheet /usr/share/kf5/kdoctools/customization/kde-web.xsl index.docbook.
Hello all,
I have created a how-to to collect the most important steps towards a contribution to the software online documentation. It is not perfect, but it is a start for anyone having the same struggle in the future.
I did this because:
- this topic went over the edges
- i struggled to understand the full sequence of all steps required to contribute to the software documentation
I took the way of KDE wiki, i hope it is not wrong and not creating another source of knowledge beside Kdoctool online documentation (Checking and Viewing the Documents) which was clearly too unspecific for me.
Here is the link to the how-to.
@ostroffjh , I hope it reflects also your settings.