{
  "$type": "site.standard.document",
  "bskyPostRef": {
    "cid": "bafyreih4xd66deepnpl2qp5gv2oqvnjnh52drshbx5tve5rx6gjbjlxzji",
    "uri": "at://did:plc:6dmfe46c76jjenq3kaxc5eds/app.bsky.feed.post/3meesn6on5ld2"
  },
  "coverImage": {
    "$type": "blob",
    "ref": {
      "$link": "bafkreiehn43sddq4ilsizbds75pqg6btzyjiosw3wvqegy7fjf3vwoigvu"
    },
    "mimeType": "image/png",
    "size": 2459961
  },
  "path": "/blog/kde/2026/02/08/01-sok-kde-docs/",
  "publishedAt": "2026-02-07T18:30:00.000Z",
  "site": "https://libremelon.com",
  "tags": [
    "first blog",
    "https://sourceforge.net/p/dblatex/bugs/134/",
    "log 1",
    "log 2",
    "log 3",
    "log 4"
  ],
  "textContent": "This is a sequel to my first blog where I’m working on fixing a part of docs.kde.org: PDF generation. The documentation website generation pipeline currently depends on `docs-kde-org`, and this week I was focused on decoupling it.\n\n## Moving away from docs-kde-org\n\nI began by copying the script that builds the PDFs in `docs-kde-org` to `ci-utilities` as a temporary step towards independence.\n\nI 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.\n\nSo the pipeline now worked, albeit, partially.\n\n## Trying XeTeX\n\nMost 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)\n\nSo I switched the backend to XeTeX to improve the font and language handling. Now I’m greeted with a new failure :D\n\n\n    xltxtra.sty not found\n\n\n`xltxtra` is a package used by `dblatex` to process LaTeX code with XeTeX. Installing `texlive-xltxtra` fixed this, and almost everything built (except Turkish)\n\n## The deprecated package rabbit hole\n\nWhile installing `xltxtra`, I noticed that it was deprecated and mostly kept for compatibility. So I tried replacing it with modern alternatives (`fontspec`, `realscripts`, `metalogo`).\n\nBack to `xltxtra.sty` not found\n\nAt 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.\n\nI experimented with local overrides, but the dependency was introduced during the XSLT stage so it isn’t trivial to swap out.\n\n## Clearer mental model\n\nA very good outcome from the experiments is that I now understand the pipeline much better\n\n\n    DocBook XML -> XSLT Engine -> LaTeX Source -> XeLaTex -> PDF\n\n\nXSL files are templates for the XSLT engine to convert the docbooks to latex and the problem is probably in one of these templates\n\n## Decision with mentor\n\nAfter discussion, Johnny advised me to\n\n  * Use `texlive-xltxtra` for now\n  * Open an upstream issue\n  * And that fixing dblatex itself is outside our scope\n\n\n\nSo 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.\n\n## Locales experiment\n\nI 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.\n\n## kdestyle strikes back\n\nNow I fed the absolute path of `kdestyle` to dblatex (to maintain PDF output parity) which introduced a new set of errors\n\n  * Option clash for `graphicx`\n  * conflicting driver options in `hyperref` (`dvips`, `pdftex`)\n\n\n\nThese seem to originate from the style file and is the next major thing to resolve.\n\n## Improved Git skills\n\nI 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:\n\n  * dropping the merge commit\n  * rebasing properly\n  * force pushing the cleaned branch\n\n\n\nLessons learnt. Working with open source projects has really made git less intimidating.\n\n## Where things stand\n\nRight now\n\n  * we can build with XeTeX\n  * we rely on `texlive-xltxtra`\n  * most locales work (except Turkish of course)\n  * `kdestyle` introduces some problems\n\n\n\nHonestly I don’t feel like I got much accomplished but the understanding gained should make future changes much faster (and safer :D)\n\n> Dev logs log 1, log 2, log 3, log 4",
  "title": "(SOK) Weekly recap (1) - KDE Docs PDF generation"
}