1. 21

A lot of people meet DocBook for the first time when they’re contributing to the documentation of older, well established open source projects. I’ve built https://docbook.rocks/ to help them get past the initial hurdle of “what do I do now?” I hope this helps!

  1.  

  2. 8

    I used DocBook for years. Among other things for writing the Slackware Linux Basics book [1], writing some chapters for the NetBSD guide, and writing documentation for Libranet Linux (paid).

    The one thing that I really liked is the customization that you can do with XSL stylesheets. However, writing documentation in XML is such a dread (even with a decent editor) that I eventually stopped using DocBook completely. Oxygen XML made the experience somewhat more enjoyable, but still not great.

    I have largely replaced DocBook by Markdown + pandoc. It is by no means as sophisticated as DocBook and for a large documentation project I would probably still recommend DocBook. But Markdown (and org-mode markup) are a hell lot easier and less dreadful to write. Of course, pandoc can convert to DocBook XML as well ;).

    [1] https://rlworkman.net/howtos/slackbasics.pdf

    1. 8

      Markdown’s good enough for small documents, but if you have much structure to keep track of, AsciiDoc or ReStructuredText are better options, and still much more ergonomic than XML. For what it’s worth, Github README handles both of them (and org-mode) just as easily as markdown.

      1. 2

        Our documentation stack is somewhat in-between, we use ReST + pandoc, the former being a little more powerful than markdown (while only slightly more complex to use). It’s pretty nice.

        1. 2

          After switching between markdown, textile and sphinx-flavoured rst, I start to long for an XML based markup language for writing my book.

        2. 5

          What’s the point of using DocBook over HTML5? Every one of the elements described maps 1:1 to an HTML5 element. Is it because there’s a larger set of tools to take DocBook and typeset it for printing? Or is the verbosity of DocBook a usability advantage (<para> V.S. <p>)?

          1. 3

            Great question!

            DocBook has lots of tools for rendering, to much more than just HTML: Literal books, PDFs, manpages, knowledgebases, even special formats for some editors to find and interpret and provide contextual help on a project.

            DocBook has special tags to help represent EBNF and functions and types and GUIs and error messages and function arguments and command line program options and variable names and and and and.

            Yes, every element described maps 1:1 but there are hundreds more which are undescribed by this post and are useful for large documentation projects.

            Edited to say: much of this is not strictly necessary for getting started and writing some docs, which is the goal of this document. It is so easy to look at the massive amount of tags and try and pick the most perfect semantics for your writing when the truth is having any docs being contributed is much more important. Leave the precise and fiddly semantics to the maintainers and PR reviewers. Let’s just write some docs.

            1. 2

              I’ve been considering building a system to auto-generate documentation from the source code and comments of different languages into a common format with no styling information. Would DocBook be a good format-of-record for my project?

              I’d like to use the preferred tool for each language to extract comments-based docs, and then a single new tool to combine source-derived documentation with human-authored guides into a final presentation format:

              • Ruby -> YARD -> DocBook
              • Java -> Javadoc -> DocBook
              • Lang -> Native tool for Lang -> DocBook
              • Markdown -> DocBook

              Then at the end, I can take all the DocBook and unify the presentation style:

              • DocBook -> HTML
              1. 1

                You could try integrating pandoc, it has a Lua or Haskell API, and an internal intermediate representation: https://pandoc.org/index.html

              2. 1

                Follow up questions: what toolchain do you use?

                And are there styles for rendering docbook that feel satisfactory for people used to latex typesetting?

            2. 3

              Looking forward to use this as a reference to improve the NixOS documentation!

              1. 1

                Follow up questions: what toolchain do you use?

                And are there styles for rendering docbook that feel satisfactory for people used to latex typesetting