Should I learn pandoc??

I really really really want to write a book (and book-stuff).

I have a question.

I'm learning (finally) about something "I've been meaning to learn for a long time but hadn't had the time", which is DocBook.

It's been on my radar for a long time.

It looks like its a technology which seems to be loosing steam and is being used less and less in the last 20 years.

I somehow feel I "missed the boat/party"

It looks complicated, hard, and it will involve some pain (XSL). I know XSL, but I'm rusty on it, and I remember it sucked.

So, the question is, if you were me, would you learn how to use DocBook? or would you learn another, perhaps newer technology for typesetting books?

These are side-quests: Is Docbook being used by companies?? like, if I put it in my resume, will it increase the chances of getting hired?? is there a company where I can go and hack on Docbook full time that will take me in?

Docbook looks like the kind of thing I could do for a living, like for a company, but I don't even know who is using it, I need to do more research.

I feel like I'm learning php3, all the websites that talk about it look dated, and there isn't a lot of new information, it looks like it is a dying art, and I'm afraid all my knowledge will become obsolete at some point.

On the good side, if I learn it, it's unlikely to change, so I won't have learning fatigue. (or will there be a Docbook 6???) OMG.

Can you advice a stranger?

  • What sort of book are you writing?
    – mmmmmm
    Commented Sep 25, 2019 at 12:47
  • Basically, I'm writing a book on the topic of how to make parametric books based on people's preferences, the premise is that we ask a bit of information from the reader, and automagically generate a book that fits their needs/prior knowledge @Mark Commented Sep 26, 2019 at 4:21

3 Answers 3


I use docbook for my ebook workflow, so I have a good deal of insight into this question.

Employment-wise, I haven't seen a lot of demand for docbook, though occasionally it is called for in open-source documentation. A lot of programmers know about it, and tech pubs know about it. I'm guessing that DITA is somewhat more popular in tech writing circles. Knowing how to do XSLT is a somewhat hard to find skill (even among programmers).

Some positives:

  • The docbook-apps mailing list is small but dedicated. I usually get a good answer fairly soon.

  • Docbook -- like DITA -- is a modular XML-based method for producing documentation. I've repurposed it for ebook publishing. The semantics are rich, and indeed, a branch called DOCBOOK FOR PUBLISHERS, uses the same tools, tosses out some of elements used only for technical pubs and adds a few ones for poetry and drama.

  • The best thing about it is that it's easy to read, it's easy to use for version control and you can use general XSLT in a customization layer to add functionality you need.

  • the HTML output is very clean, so it's easy to customize the CSS.

  • XML Oxygen is an extremely good client-side tool for producing and transforming docbook files.

  • The standard is likely to remain stable and backward compatible for a long while. For now at least Oxygen is adequate as a tool.

Among the negatives:

  • Even though it's theoretically possible to produce epubs from docbook xml and it's possible to use a framework like ANT to produce the final output, I find it unwieldy. Instead I use the built in XSLT transformations in Oxygen XML, and actually I do some manual steps -- moving image files into a directory, zipping the files up.

  • I often perform these manual steps because I'm too lazy/stupid to write appropriate xslt code, but sometimes the stupid solution is the easiest.

  • Because Docbook outputs into several files, often you will see some extra elements and attributes which are remnants of this functionality. Example: <div class="titlepage">

  • I have not seen any server-solutions for Docbook output although I'm sure they exist.

The future:

3 trends I see that may suggest declining importance of docbook.

First, a lot of source is being written in markdown. I am seeing more tools (like Pandoc) to allow for richer presentation. Markdown isn't xml and not really a semantic language.

Client-based WYSIWG ebook tools are improving. None are really great (maybe Calibre?), but every year means more functionality and ease of use.

Static Site Generators - if they become more widespread, might result in more web-based ebooks. Docbook has a website builder function which I have never used btw. Hope this helps.

  • Thank you so much for your detailed answer! Commented Sep 27, 2019 at 12:38

Short answer: no. Having to learn something complex like this will simply delay actual writing. Try a very simple editor. An office product, or text editor such as VSCode which is quite nice. I suggest writing using Markdown, and then generate epub and pdf using Pandoc. Those tools take a day or two to figure out. The Markdown Extra syntax is nice, supports footnotes. The biggest thing is to start in on the writing. Stephen King's book "On Writing: A Memoir of the Craft" is excellent for dealing with fiction/stories, and also focuses on process. The book "Deep Work" also emphasizes setting aside large chunks of time (or simply writing during any little bit of available time).

  • 1
    I don't disagree -- I use a simple text editor for composition. But docbook has rich semantics, and that's an advantage. Markdown is mainly a language for formatting. Semantics stress the function of the elements and hypothetically that could be helpful if HTML or CSS change radically. To give an example. Sometimes I use custom attribute classes (i., para role="line-verse") for lines in a poetry stanza. You totally can't do that in markdown. Commented Nov 1, 2019 at 12:34
  • You can definitely add classes in Markdown Extra Commented Dec 27, 2021 at 8:16

I think Docbook and whole SGML/XML publishing industry is moving where it started … to the area of industrial documentation with ultra-long shelf-life, scientific documents (TEI, OSIS), etc. There is nothing else to use for maintaining a documentation for F-16 (introduced to the market on 17 August 1978; which other format allows you to use the same documents for 40+ years?).

These days for anything else than these super-specialized areas, it is better to use something more normal: Markdown or (my preferred) reStructuredText.

  • What are your views on HTML as an answer to your question? Commented Jun 14, 2023 at 22:56
  • HTML is these days “generate-only-never-write-manually” format for me. Something like .o files during C development. There are just too many things missing from the standard HTML (metadata, footnotes).
    – mcepl
    Commented Jun 19, 2023 at 7:30

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.