2nd Edition of Technical Book - eBook and Print

Hello,

I was recommended to Scrivener by a friend as I was wrapping up technical editing of the first edition of a programming book (Writing High-Performance .NET Code) a couple of years ago.

I’m ready to work on the 2nd edition and I went through the Scrivener tutorial. I am intrigued. I love the organizational abilities, the focus on writing, and so much more. But… this is a programming book. It requires a ton of formatting. It has a ToC, index, shaded blocks, etc. in the print version.

My workflow for the first edition was this:

  1. Write it all in Word (i.e., docx is my master copy)
  2. PDF conversion was trivial (Required for the print edition, and I sell it as a PDF as well)
  3. Convert to Mobi – Save a copy of the Word file, change a bunch of formatting, use Kindle’s autoconverter and this mostly worked. I had to go back and forth on a few tweaks, but not too bad.
  4. Convert to ePub – I used some free tools to do the initial conversion, then calibre’s eBook editor to tweak. This required a ton of tweaking. There were too many styles, they were complex. I spent a lot of time simplifying, too much time playing with CSS.
  5. Spend time formatting for self-publish on CreateSpace. Lots of styles, headers, footers, page numbers, the works. It’s completely professional and looks awesome.

I’d like to flip this workflow on its head. My ideal workflow would be:

  1. Write book in Scrivener.
  2. Hit a button and it generates a completed ePub.
  3. Hit a button and it generates a completed mobi.
  4. Hit a button and it generates a Word doc.
  5. Spend most time on the Word doc formatting for publication, as before.

It seems like future updates and typo fixes would be much simpler this way (I resubmit versions for all eBook distributors as I fix bugs in the book. The print version does not get updated). I can’t ignore the print version–it’s a significant part of the sales.

So is anything like this doable in Scrivener? I had thought originally that steps 1-3 above would be a piece of cake, but I guess when the documentation says that formatting is rudimentary, they’re not kidding. One basic thing I have to do is switch between normal font for prose and a fixed-width font for code samples (sometimes inline in paragraphs). And I can’t seem to do even this–the resulting epub still only has a single font.

Is Scrivener just not meant for me, or what are my options? How far can I take this? I think even if I can’t use it, I’ll probably still start from the eBook as maser, with formatted doc as a separate output instead of the other way around.

If you want maximum flexibility, and especially if you are creating a technical book, you should seriously consider using a Scrivener+MultiMarkDown workflow — Chapter 22 of the Scrivener manual (Scrivener’s own manual is created in Scrivener+MMD–>LaTeX).

So inline code and code blocks can be freely created, and for code blocks they can be automatically syntax highlighted by providing the language name on compile. MMD does the final conversion to Word or HTML, and because you compile to plain text, you can easily use closely related tools which have even more functionality. [b]Pandoc/b is the most well known example, and the great advantage of Pandoc is it has an expanded formatting language that allows more formatting markup (e.g. custom inline and block styles that you can use for INFO, WARNING boxes etc.).

A cool thing about Pandoc is you can pass custom templates during compile, so you make a Word doc with the styling as you want, and when converting your Scrivener markdown file it applies the template and the Word document is fully styled (and Pandoc generates good semantic docx files (unlike Scrivener), figures, headings, captions, code blocks, block quotes etc all have attached style). Another option I’ve seen recommended on the forum is [b]AsciiDoctor/b, which is even more technical writing focused. Because mmd, pandoc, asciidoctor are command-line tools, they can be easily automated, for example in macOS using a Automator folder actions or Quicksilver or any other tool…). The next version of Scrivener which is in private beta testing is apparently going to get explicit Pandoc support too…

The main point here is that you benefit from the unparalleled writing environment of Scrivener, while still having access to an almost infinite set of flexible compilation end-format workflows. 8)


This is awesome. Thank you so much. I use MMD at work in our documentation, and for some reason didn’t think it was powerful enough to handle this, but I think it might work out. I’m going to start doing a sample chapter and seeing how far I can get. Thanks so much for this, and for the pointer to the other tools. I can definitely get an automated workflow going.

Now I’m wondering if it would even be possible to get a completely ready-for-print PDF out of a set of tools. I’m assuming page numbers are easy, but what about alternating page header rules, page numbers on different sides of the page for even/odd, chapters only start on odd pages. ToC and indexing is another issue… anyway, now I have a few pointers to look into.

Thanks again.

PDF generation using LaTeX would certainly fix those requirements, and the Scrivener manual does showcase almost all these… The source Scrivener project to generate the User manual PDF is available here:

literatureandlatte.com/support.php#Scrivener

…may give you some ideas. There is a dedicated MultiMarkDown Scrivener sub-forum where you can ask questions. Both MMD and Pandoc offer flexible LaTeX workflows, though I don’t have too much experience with LaTeX personally.