|
Wrote a book for Manning (Redis in Action), from December '11 to July '12 (available online), editing through the summer of '12. Was offered the Word Doc or Docbook-based XML format w/ Java validator + validating xsd, and others. Went with the XML, but built my own tooling for injecting runnable code (what is available in my git repository for the book) into the book, using code comments to define figures so I didn't have to copy / paste / update / etc., along with figure, and other convenient "macros" to save from typing the XML. Call it 85%-90% XML, 10% other stuff. The major challenge I faced was that the validator provided to me was not the same as what was used by the publisher when I uploaded my xml for automatic generation for editing, leaving me in a situation where I didn't even know that my xml wasn't valid until I get a crappy message after `svn commit` and having to submit a build to their system (typically 1-3 minute delay to find out your pdf generation didn't work, try to find what weird xml edgecase you missed that your validator doesn't care about, and submit again). About 2-3 months before finishing with final edits, I found an XML editor that would validate with the xsd directly, finally getting my document validated (but breaking all of my formatting, requiring extra steps in my build process, ...), and allowing me to eliminate 30-40 minutes of the typical "find out what's wrong with my hand-written XML tonight" when editing. They had a forum for discussing ongoing author issues, and I remember there was an author who was using his own Asciidoc -> docbook tool. Looks like they may have imported it more recently if OP was using that and there was no docbook option. I had started early on with a reStructuredText equivalent, but then realized that I didn't want to write / maintain a tool to write a book (and to maintain that tool for others going forward), and ended up with what I used - less than 150 total lines, no external libraries, and no maintenance going forward. :) |