Writing My Book Using Quarto

The Perfect Book Writing Flow

I am somewhere between a programmer and a writer. That means I can program, but it isn’t my first goal in life. I can write, and that is closer to my goal in life, and so where I need to, I can program. I do not program for the joy of it, though. Never have. When I program it is strictly for a result or functionality I did not have before. So, when I go to publish something, I like a flow that gives me maximum ability to publish to different formats–pdf, html, epub, whatever. When XML first made its appearance, I remembered thinking “YES, FINALLY.” Ah, that was naive. (XML is great for everything I mentioned, it just happens to REALLY SUCK to write at any complexity)

Enter Latex

Latex is awesome for typesetting. The only problem with Latex, though, is that it is mostly made for a more “scienecy” type of writing. Equations, tables, charts, graphs all the things that bored you in textbooks Latex is good at. With some beating, one can coerce Latex to print other things fairly well like books. With some pandoc magic, you can even get it to convert to different formats with varying degrees of success. Then, the idea may strike you, why not write in something like markdown then convert it with pandoc to whatever else like latex? Some people do just that, but I have found that the results are too variable for my writing style. I don’t especially want to have to write specific Latex formatting guides either. All of that is very time-consuming and most often needed for whatever I am currently doing but not for things on down the road. Latex suffers from having many different kinds of interpreters and packages do not always place nice between successive incarnations of Latex.

Enter Quarto

Quarto, however, is a kind of synthesis between Latex and markdown with structured yaml thrown in for good measure. If you have built a static website with a static web builder, then you won’t have much trouble with Quarto. Quarto smoothly outputs different formats such as pdf or a website or many other variations.

The Problem With Quarto

Quarto would almost be a perfect tool except for the fact that it has certain stylistic assumptions about your book. For instance, if you have a dedication before your introduction, Quarto does not have a built-in facility to deal with this. Instead, it has a specially labeled section called “before-body.tex” where you can place formatted latex. This, however, can cause issues with your pdf generation later on down the road since certain things might duplicate. If you need a preface before the body, for instance, Quarto is not going to care for that since it all ready has ideas about where your preface should go. The same thing is true with an abstract and the “before body” element does not carry into constructing a website. Therefore, if you want an abstract in your website, you are going to have to make Quarto do some calisthenics it would prefer not to do. (it looks like in hindsight you can also have a before body for the html too although I’m not sure how that works or does not work with .tex files)

A Glossary

During the writing of my book, after some feedback from my wife, I thought it might be nice to have a glossary as per some of her suggestions. Quarto does not support this at the moment, and so I went to support to see if anyone else had had a similar hankering. Imagine my glee in finding this information in the repo with the first issue being mentioned all the way back in August of 2022. Since there had been no update on the milestones, I figured I’d better ask as my book, which was in no small way about the End of Days, was nearing completion. I want to make sure I give you the pictorial version of the reply I got here, so you have an insight into the type of support you might receive if you happen to also want to use Quarto:

Oh no, he just didn’t!! He gave me the ole “My time as a programmer is more important than your time as a user/author and if there is a change you will see it here schtick,” after no discernible info had been contributed since last year. At the time I checked this repo for this article, I did notice that there were exactly 666 issues outstanding, and that just today, in fact, the milestones had been changed from 1.3 to 1.4 for the glossary! I can’t make it up, man. Dude has important things to do as a programmer, and if you just happen to be writing a book about the End of Days, you will JUST HAVE TO WAIT BUDDY! 2025, according to one American General, is gonna be an interesting year. Don’t ask cscheid about any programming for a glossary if that breaks out though! It distracts his mystical Quarto programming flow and he does NOT have time for that! (I will follow up with him about the glossary then if all of our countries are not some composite of nuclear obsidian) He will probably be on milestone 1.6 by then for sure.

All that being said, cscheid is just one member of the Quarto team, and it is highly possible not everyone is an arrogant jerk that is developing Quarto. Being someone who fields the issues of users is not always a fun job either, and so I don’t fault him for that. I do fault him for not following up on my email where I tried to explain myself a little further. He simply wanted to make me look like I was some energetic, enthusiastic cheerleader who was overzealous in public. I may be a lot of things, but enthusiastic cheerleader ain’t one of um. Next time, try updating the news more regularly and maybe users won’t ask you annoying questions.

Having Said All of THAT

I did mostly enjoy using Quarto, and I decided to release the free version of my book using their scaffolding. It was a smooth publishing flow and I could see how academics that don’t know much about web hosting would really enjoy this aspect of Quarto. I simply enjoyed not re-writing or modifying the content to try to achieve some static website semblance that did not violate the basic aesthetic flow of the book or chop up the words in some undesirable way. The pdf output was also pretty easy to engender, although for the title page I had to assemble that AFTER I ran Quarto to produce the entire pdf and use “pdfarranger” to include a “cover”. There are some Quarto templates out there that say they do this, but I found them to be more trouble than just re-arranging the pdf in this fashion.

So Go Buy the Book

So now you know “How It Was Made.” Go buy the book!