Indexes and hyperlinks
Why book formatting can be painful
In my book about publishing for technical people, most of the words I’m writing are to help you publish independently, as efficiently and professionally as possible. Another way to look at that majority of the book is that it describes what a traditional publisher does for you.
The tl;dr: Book formatting is hard, and AsciiDoc is cool.
One of the headaches that a publisher just whisks away is book formatting. If you’re only publishing an ebook or only publishing for print, then it’s not so bad. It’s when you want both that you find yourself in a trickier spot.
A simple example of how producing both formats is tricky: In an ebook, hyperlinks are ideally done just as they are on the web. Your link text is visible, and the reader can click or tap on the link to follow it. In print, though, you have to split the URL from the link text in order for the reader to know what you’re pointing to. Of course, you can get around this by just including the URL in both formats: Hyperlink (https://en.wikipedia.org/wiki/Hyperlink), but that clutters the ebook somewhat unnecessarily.
Indexes are a much trickier part of the interior of your book. For one, choosing which terms to put in the index is an art and skill unto itself, because your index needs to include the terms as the reader will think of them. If you’re making a cookbook, for example, your hash browns recipe should appear in the index under “hash browns”, but should also likely appear under “Potatoes, hash browns”. Traditional technical publishers regularly work with indexers who know how to pull out the most useful terms. Freelance indexers do exist, should you want to hire that out. So do freelance book formatters, for that matter.
If you plan to do it yourself, as I do for my book, you need to be able to mark up your index terms and produce an index such that all of the page numbers for a given term appear next to the terms. The ebook doesn’t really have to have an index, because people can simply search.
Vellum, which is an absolutely delightful book formatting tool for the Mac, doesn’t support hyperlinks as I’ve described or indexes. There are quite a few free tools on the web that will convert your book between formats, but I haven’t seen any that do indexes. Microsoft Word can do indexes, though it doesn’t quite do hyperlinks the way I’d prefer.
You know what a lot of writers do? They skip the index. This isn’t a terrible choice, but a lot of readers (of non-fiction in particular) love print books, and print non-fiction really benefits from an index. I’m working on finding the lowest-friction way for a do-it-yourself publisher to produce a book that is every bit as high-quality as its traditionally published competitors.
I’m more than 18,000 words into my first draft, and I’m currently working on the interior formatting chapter. This is going to be the most difficult chapter to write, because there are so many approaches with so many tradeoffs.
I’ll tell you what I’ve found so far: AsciiDoc may actually provide the best balance for a technical person. I was very impressed at how easily it was able to check off all of the boxes in my test. Oh, except it sorts the page numbers in the index alphabetically (a bug fixed a year ago, but not yet released!). Tradeoffs everywhere.
If you’ve got tips or opinions about formatting for ebook and print together, I’d love to hear them. You can either reply to this email or come to the TechWriters Discord and chat there.
More next week…
Kevin
p.s. If you’re landing on this page on the web, I’m writing a weeklyish newsletter discussing topics covered in my forthcoming book, albeit in a less polished and complete fashion. If you found this post helpful, you may want to subscribe: