Skip to main content

Should DocBook still serve as the sole documentation language for KDE?

KDE's getting started page on documentation states:

KDE documentation is written in DocBook XML.

Historically, this was probably a good decision. Who does not remember that XML was so much easier to read, parse, and work with compared to binary or virtually any propitiatory file format?

KDE is aiming to bump its major version to 6. This might be a good time to reflect whether DocBook should serve as the sole official documentation language. Well, I would like to open this to an optional second language.

I don't mind what the second language could be; possible candidates are reStructuredText / Sphinx, Markdown, AsciiDoc -- among others. I don't want to convert DocBook to any other format. But giving projects some choice, might help.

I am by far not the only person with regard to a replacement of DocBook: DigiKam recently switched to Sphinx for their user documentation after 20 years of using DocBook. Krita uses Sphinx for five years and Kdenlive for over a year. By the way, the Linux kernel left DocBook for Sphinx, too.

What do you think? This would be a good topic for an Akademy BoF. Where should we discuss this in the meantime?

Comments

  1. Hi,

    KDE doc infra maintainer here. This is definitely not the first time that the issue was discussed or raised, but it needs work.

    Please check my old presentation from Akademy 2017, for example: https://conf.kde.org/en/akademy2017/public/events/377.html

    At the time the candidate in my mind was Asciidoc (because it was closer to DocBook and may have made the transition easier) but ReST has since positioned itself as a better choice. Of course it's not just a matter of "let's use it" - the 3 doc websites are a good example, but before we scale that more we may need some more common tooling to centralize the access and avoid scattering the content around.

    ReplyDelete
  2. Thanks Luigi for mentioning the talk from Akademy 2017. It is still worth watching and the questions raised needs to be answered.

    Depending on the general interest, we need to figure get several things done. Some point, more will come up:
    - Decide on the actual tool
    - Get proper CMake support, either upstream or in the cmak-extra-module
    - Think about ways to integrate the tool in the current toolset, both for developers and KDE servers
    - Have a proof of concept project to get feedback first hand.

    ReplyDelete
  3. As most people don't like documentation in general making things as easy should be a priority. That being said the clear option would be Asciidoc as it is simple yet powerful when needed and super easy and approachable. You can easily convert to docbook if need be and it makes it easy to convert to epub, man page, html or pdf. Thirdly it is human readable and non obtuse you can easily edit read and share the document and not run into xml issuer and validation errors. Also you can reference actual code and get it highlighted easily within the documentation.

    ReplyDelete

Post a Comment

Popular posts from this blog

Use cppcheck to find bugs and improve code quality (not only for Kile)

Do you know isocpp.org's blog ? As an open-minded C++ programmer, I am a fond reader and have been inspired multiple times. I always enjoyed the blog posts from Andrey Karpov . He has deep knowledge with static code analysis and is a co-founder of PVS-Studio, a commercial static code analyzer for C++, C#, C, and Java. To advertise new releases of their product, Andrey and his co-workers scan popular open source projects with their tool. They explain the numerous results and showcase by these real-world examples how beneficial static code analysis is even for mature and healthy code bases. I found these posts both entertaining and instructive. If you are not aware of them, you might find them an interesting read: Clang 11 , LLVM 15 , Qt 6 , GCC 13 . I find this topic intriguing; nevertheless, for a long time I did not manage to dive deeper into this topic. I am a satisfied user of Kile , KDE's user-friendly TeX/LaTeX editor. In the span of almost 20 years (Is Kile really that ol

New programming language needed for KDE?

Disclaimer: I am not one of KDE's masterminds or spokespersons. I am a mere bystander with few unimportant commits. I follow KDE's ecosystem and other developments in the free software world. In the following, I share some thoughts and my personal opinion. Talks about new programming languages After 30 years of C code, the Linux kernel opens itself to a second high-level language: Rust. Since fall of 2022 the kernel mainly gained infrastructure work. Some experiments show promising results like a Rust-based network driver or a scheduler . Recently, Git developers started to discuss how to allow Rust code in our beloved version control system. Far from having reached a consensus, its media coverage and heated discussions in forums show how interested the public is in this topic. Other projects try to replace established software by rewritten from scratch Rust ones: uutils coreutils , sudo-rs , librsvg , Rustls . Heck, Rewrite it it Rust (RiiR) has become a meme . We already h

Kile 2.9.95 / 3.0 beta 4 released

We have a release of Kile 2.9.95, also known as 3.0 beta 4! Earlier today, Michel Ludwig tagged the current Git master. This is the first beta release since October 2019. Beside the port to KDE Frameworks 6 and Qt 6, it provides a couple of new features and bug fixes. New features Port to KDE Frameworks 6 & Qt 6 (Port by Carl Schwan) Enable high-dpi support Provide option to hide menu bar (Patch by Daniel Fichtner, #372295 ) Configurable global default setting for the LivePreview engines (Patch by Florian Zumkeller-Quast, #450332 ) Remove offline copy of "LaTeX2e: An unofficial reference manual", use online version instead (Patch by myself, Christoph GrĂ¼ninger, Issue #7 ) Fixed bugs Kile crashes on selecting "Browse" or "Zoom" for document preview (Patch by Carl Schwan, #465547 , #476207, #467435, #452618, #429452) Kile crashes when generating new document (Patch by Carl Schwan, #436837 ) Ensure \end{env} is inserted in the right place even when the