User:Nmariusp/ProductDocumentation

Docbook

Using docbook technology. KDE apps that use Qt widgets and kxmlgui have "Product Handbooks". Also man pages for KDE command line executables use docbook. Kirigami apps usually do not have product handbooks.

Procedure.

See https://community.kde.org/How-to-visualize-docbook-files-in-browser

kde-builder kdoctools
kde-builder klickety
# See https://community.kde.org/How-to-visualize-docbook-files-in-browser
source ~/kde/build/kdoctools/prefix.sh
cd ~/kde/src/klickety/doc

# Static analysis.
checkXML6 index.docbook
# Fix issues if needed.

# Test in web browser.
meinproc6 --stylesheet ~/kde/usr/share/kf6/kdoctools/customization/kde-web.xsl index.docbook
xdg-open index.html

# Test in khelpcenter.
kde-builder klickety
kde-builder --run klickety
# From the main menu of the app > Help > Handbook F1.

# You can see if the handbook files are being opened from the correct directory
apt install fnotifystat
sudo fnotifystat 1 -i /home/administrator/kde/usr/share/doc/HTML/en/klickety/
# Says:
#  Total   Open  Close   Read  Write     PID  Process         Pathname
#  3.0    1.0    1.0    1.0    0.0    32442 <unknown>       /home/administrator/kde/usr/share/doc/HTML/en/klickety/index.cache.bz2
#  3.0    1.0    1.0    1.0    0.0    32446 kioworker       /home/administrator/kde/usr/share/doc/HTML/en/klickety/index.cache.bz2
#  6.0    2.0    2.0    2.0    0.0    32446 kioworker       /home/administrator/kde/usr/share/doc/HTML/en/klickety/config-customgame.png

# khelpcenter command line.
khelpcenter help:/klickety/credits.html

Deep dive.

# Extract /home/administrator/kde/usr/share/doc/HTML/en/klickety/index.cache.bz2 to /home/administrator/kde/usr/share/doc/HTML/en/klickety/index.cache.html
# In /home/administrator/kde/usr/share/doc/HTML/en/klickety/index.cache.html replace "help:/kdoctools6-common/" with "/home/administrator/kde/usr/share/doc/HTML/en/kdoctools6-common/".
# E.g. you can use vscode to open the directory /home/administrator/kde/usr/share/doc/HTML/en/klickety, reformat the file index.cache.html. You can install the vscode extension "Live Preview" "ms-vscode.live-server" to have a live preview of the HTML file.
firefox index.cache.html
# Everything seems to be correct, except the fact that the handbook is in a single page and you cannot navigate the handbook pages using e.g. the hyperlinks "Next", "Prev", "Contents".