Moving away from docs-kde-org

I began by copying the script that builds the PDFs in docs-kde-org to ci-utilities as a temporary step towards independence.

I then dropped the bundled dblatex for the one present in the upstream repos, wired up the new paths and hit build. To no one’s surprise, it failed immediately. The culprit here was the custom made kdestyle latex style. As a temporary measure, I excluded it to get PDFs to generate again, however several (new) locales broke.

So the pipeline now worked, albeit, partially.

(Commit 17bbe090) (Commit 3e8f8dc9)

Trying XeTeX

Most non-ASCII languages (Chinese, Japanese, Korean, Arabic, etc) are not supported for PDF generation because of wonky unicode support in pdfTeX (the existing backend driver that converts LaTeX code to a PDF)

So I switched the backend to XeTeX to improve the font and language handling. Now I’m greeted with a new failure :D

xltxtra.sty not found

xltxtra is a package used by dblatex to process LaTeX code with XeTeX. Installing texlive-xltxtra fixed this, and almost everything built (except Turkish)

(Commit 7ede0f94)

The deprecated package rabbit hole

While installing xltxtra, I noticed that it was deprecated and mostly kept for compatibility. So I tried replacing it with modern alternatives (fontspec, realscripts, metalogo).

Back to xltxtra.sty not found

At the point I looked at the upstream dblatex code and found references to xltxtra in a Latex style file and in the XSL templates responsible for generating the latex.

I experimented with local overrides, but the dependency was introduced during the XSLT stage so it isn’t trivial to swap out.

Clearer mental model

A very good outcome from the experiments is that I now understand the pipeline much better

DocBook XML -> XSLT Engine -> LaTeX Source -> XeLaTex -> PDF

XSL files are templates for the XSLT engine to convert the docbooks to latex and the problem is probably in one of these templates

Decision with mentor

After discussion, Johnny advised me to

• Use texlive-xltxtra for now
• Open an upstream issue
• And that fixing dblatex itself is outside our scope

So I went ahead and filed the issue https://sourceforge.net/p/dblatex/bugs/134/. Now we keep moving forward while also documenting the technical debt.

Locales experiment

I temporarily re-enabled previously excluded locales (CJK etc) to see what happens. Unfortunately most of them didn’t generate silently. I’m still unsure about this part and the behavior might differ in other projects, so I’ll revisit this later.

(Commit 04b698a5)

kdestyle strikes back

Now I fed the absolute path of kdestyle to dblatex (to maintain PDF output parity) which introduced a new set of errors

• Option clash for graphicx
• conflicting driver options in hyperref (dvips, pdftex)

These seem to originate from the style file and is the next major thing to resolve.

(Commit 7ede0f94)

Improved Git skills

I also had a self inflicted problem this week. My feature branch diverged from master and I merged instead of rebasing. As a result the history got messed up. I fixed it by:

• dropping the merge commit
• rebasing properly
• force pushing the cleaned branch

Lessons learnt. Working with open source projects has really made git less intimidating.

Where things stand

Right now

• we can build with XeTeX
• we rely on texlive-xltxtra
• most locales work (except Turkish of course)
• kdestyle introduces some problems

Also here’s a before vs after of the generated PDFs (the end goal would be to make both of them look identical)

Honestly I don’t feel like I got much accomplished but the understanding gained should make future changes much faster (and safer :D)

Dev logs log 1, log 2, log 3, log 4

Edit (09-02-2026): Added links to relevant commits based on feedback received

What’s dblatex?

From the man page: dblatex is a program that transforms your SGML/XML DocBook documents to DVI, PostScript or PDF by translating them into pure LaTeX as a first process. MathML 2.0 markups are supported, too. It started as a clone of DB2LaTeX.

My task is to swap the bundled dblatex with the one present in the upstream repos and make the PDF generation work reliably. Then switch the rendering backend from pdfLaTeX to XeLaTeX to support native unicode (to fix rendering issues for languages like Arabic, Chinese, Japanese, Korean, etc).

If that doesn’t work out, I’ll extract the dblatex fork into its own repository to ease maintenance.

Checkpoints to achieve

• Swap our current fork and use the latest upstream version. Also compare these two.

• Migrate from pdfLaTeX to XeLaTeX

• Verify our fixes and confirm if all the PDFs are being generated properly.

I’ll be sharing my progress and struggles (setting this website up was probably a struggle in itself) from time to time as I start this project. This work is part of Season of KDE, mentored by Johnny Jazeix.

Welcome to my first post. This probably would be a not-so-technical technical blog. Unrelated but I’m going to start college in less than a week.

See y’all in the next one