Did anything concrete about moving from Docbook come about?
- There are 3 candidates to move from Docbook: markdown, asciidoc and RST. The last one has least supporters, but some do know it.
- There are actually 2 objections to Docbook which we want to address: rarely anybody knows it and GitHub doesn’t render XML nicely in Github web UI.
a) For first one there exists https://docbook.rocks/, but it doesn’t mention all the gazillion of special tags used in Nix/pkgs/OS manuals (different terminals outputs, filepath, crosssection targets, …).
b) For second one @edolstra objected that people who write docs don’t need GitHub rendering on Github website. Well we should convince him this is not true and we often end up making small doc changes in GH webpage and we want rendered preview right at hand.
c) Eelco also pointed out that Emacs XML mode powers him to write docs fluently. But what are the options if we use something different from emacs?
- Asciidoc(tor) is the most obvious choice to switch from Docbook:
- it is designed from start as XML-less docbook
- it has consistency check out of box
- it has GitHub rendering, it has editor support
- it is machine-processable (using Ruby)
- I was convinced that Markdown may be of same rendering power as Asciidoc, but I don’t know the MD story about linters/checks/machine-processability. cc @tazjin
- We also have cases when two formats (Docbook and Asciidoc/markdown) are mixed in single text blob! It is in
descriptionsection of Nixos options: https://github.com/NixOS/nixpkgs/blob/08f68313a47a2093dc0f408a706b2c125bc59c95/nixos/modules/services/misc/zoneminder.nix#L73-L80. I think also that library function documentation (in function comments) is already markdown.