1

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? – user151019 Sep 25 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 – Felipe Valdes Sep 26 at 4:21
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! – Felipe Valdes Sep 27 at 12:38
1

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).

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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