4 ms·
DocBook has served me very well. For my books I put together an automated publishing workflow that starts with DocBook and produces output for both print and di
by ivanr 5y ago
DocBook has served me very well. For my books I put together an automated publishing workflow that starts with DocBook and produces output for both print and digital (in my case, PDF, EPUB, and HTML). For context, I wrote and published two books (4 editions) with more than a 1,000 pages combined. My goal was always continuous writing and publishing where everything is fully automated.
Conceptually, XML is an excellent choice for this sort of thing. If you want to produce a good quality book, you need many features and markup that can support them. For a technically minded person, being able to programmatically inspect and modify the manuscript is awesome.
Unfortunately, the tooling, although very capable and very well documented (via Bob's free book http://www.sagehill.net/docbookxsl/ http://www.sagehill.net/docbookxsl/), is very difficult to use unless you're an XML expert already. XSLT really isn't a good choice for this sort of thing. That's what I had to use because CSS-styling wasn't mature enough. These days I'd start with CSS instead of XSLT.
Crucially, I would use a commercial FO processor. I spent a lot of time with Apache FOP and, even though it's a great tool, it lacked a number of features that one needed for a professional use. (It may have improved by now, my experience is from a decade ago.) I eventually purchased a licence for Antenna Formatter, https://www.antennahouse.com/ https://www.antennahouse.com/, which has saved me so much time.
You're not meant to write XML by hand, but there aren't that many great editors out there. I use OxygenXML, which is all right. It's expensive. The best thing about OxygenXML is that it supports change tracking. My copyeditor also uses OxygenXML and we have a great workflow that would be impossible to implement in any other way. For me this is the killer feature. A good copyeditor will make thousands of edits to your manuscript. Having an easy way to handle those, respond, and communicate... is key.
There are some other interesting tools out there, for example DocBook Compare, which we use to show exactly what changed between two editions. I have some screenshots of what that looks like in this blog post: https://blog.ivanristic.com/2022/02/bulletproof-tls-and-pki-is-out.html https://blog.ivanristic.com/2022/02/bulletproof-tls-and-pki-...
To sum up: Do use DocBook. Use OxygenXML to write your books and collaborate with your coauthors and editors. Use Antenna Formatter and CSS for styling. It's going to cost you about $2,000 in software licences, but it's worth it and it will pay back loads in time saved. I understand that no one will spend this much money for a hobby, but for any sort of professional activity, it's a no-brainer.
- cylinder714 5y agoI commented several years ago: It was flamed pretty badly when first introduced to HN, but I still think Steve Howell's Shpaml (http://shpaml.com/ http://shpaml.com/) completely removes the pain of writing angle brackets and keeping track of closing tags. Plus, it makes writing arbitrary XML really easy, just the thing for writing DocBook, I'll bet. And no need for a specific editor, just use your favorite. I should add that you don't have to run Django to use Shpaml, just the Python script itself.