How I Wrote My Book | Hacker News Reader

How I Wrote My Book

kevinwmcconnell.com

Very cool. I co-edit Peter Shirley's _Ray Tracing in One Weekend_ (https://raytracing.github.io/) and have taken a similar approach, though with a different toolset. At some point if I find the time, I'll write up a similar article on our approach and what we've learned. Our books are open-sourced on GitHub (https://github.com/raytracing/raytracing.github.io), and we also use GitHub to host our books.

Basically, we use Markdeep (https://casual-effects.com/markdeep/), a _very_ powerful Markdown implementation with a bunch of built-in features. The killer feature is that with a handful of boilerplate lines (UTF-8 declaration at the top, and JavaScript loader at the bottom), you get content that automatically self-transforms in the browser into a full HTML document. This eliminates any build step, and means you can treat it as you would any other HTML file, with optional CSS and other features. It also bundles in a LaTeX engine, ASCII diagram rendering, and a whole host of other features. If you look at the three ray tracing books, you can see how simple the source is, and how pleasing the final rendering.

Check out the books and the GitHub repo — it's a _great_ way to quickly and easily pound out a web book.

> But when writing a book, pretty soon you run into things that Markdown doesn’t natively know how to do, and so you have to either look for extra tooling to fill in the gaps, or build support for those things yourself. There are open source projects that address some of this, but I didn’t see anything that would do everything I needed.

I'm surprised there's no mention of Pandoc, which does pretty much what the author wanted (at least at a high level) and works with markdown:

https://pandoc.org/epub.html

I would recommend using Vale for linting prose in a text editor. It can approach grammarly like rules as well as handling spelling for technical documents fairly well.

https://github.com/errata-ai/vale

Oh cool, that looks really interesting! I hadn't seen it before, but will definitely try it out. Thanks for sharing.

> At the end of the day, Markdown’s biggest strength — simplicity — is also its limitation.

But also its strength again. It's missing features, sure, but the features it does have you can be very sure exist in all the export formats. Formatting is really something you should be doing at the end, otherwise it's a distraction.

I tend to use markdown for the initial writing of academic papers for example, only exporting to LaTeX .tex at the very last minute to address formatting.

I wrote mine in LaTeX. I remember that making terminal output fancy was a pain. Eventually I managed to even get scissors to indicate omitted output. I was proud of that. Example: https://bayimg.com/gAaLbAaHI

Then I had so many dependencies that I didn't want to update my computer anymore as it could break my build process and the Makefile which did everything from taking the .tex files, to image processing, to PDF generation and cover art integration. So I moved everything into a virtual machine. I still keep it around but I am too afraid to boot it nowadays. Would be pwnd in a second after years of no updates :)

Next time I write a book it'll be likely non-technical and then markdown should be fine.

My book was about IPv6 and since it is no longer up to date I stopped selling it. It's available at https://danrl.com/ipv6 (Book language is German, though)

I wrote a school textbook in asciidoc. It was a wonderful tool to use but it soon became rather painful and I wish I had used something more lightweight. 30s build times are misery for tweaking.

Whatever was going on in the background — Prawn::PDF or something — was very slow about churning PNGs to format them into a PDF. I added some build logic to make “draft” PDFs with low res PNGs to speed things along, but it felt messy.

Ultimately, I wish I had authored with HTML and CSS instead. Markdown isn’t a document format — it’s a means to creating HTML, sort of like an IDE except you write in test instead of use a specific editor runtime. The beauty is being able to drop HTML into your markdown and not have the processor trip over it. <aside>, <figure> etc all because first class entities as opposed to by products of some arbitrary ascii syntax fencing, and it brought me closer to the resultant HTML that made formatting with CSS much easier (in a later, much smaller project.)

Print CSS is still very challenging unless you have the budget for Prince. You can do a lot if you give up hope of having everything happen automatically a la LaTeX. When you focus on the content over the formatting, these worries tend to evaporate.

What's your opinion on doing it not "a la LaTeX" but actually in LaTeX? I mean, for writing the bulk of initial core text it's not much different than Markdown, but when you do get to the typography stage then it has all the things needed for the print layout.

Never written a book, but I have written a few reports in Latex, and I would say it is a miserable experience. Slow build times, horrible error messages, and so much markup for everything.

I have taken the stance that all writing should happen in Markdown/Asciidoc/Pandoc/whatever minimal flavor you like and once content is complete, then port everything to Latex if necessary. Pandoc can spit out a reasonable .tex file you can then massage into a final product.

I never wrote a book, but I wrote my dissertations (100+ pages each), resumes or any other article in Latex, using Miktex. It wasn't the best experience UI-wise and until I learned proper Latex (which I now have forgotten) the error messages were shit. But the build times with quick builds and splitting stuff in chapters was actually a great experience for me. Maybe it's 'rosy retrospection' or I've been out of the loop with the current happenings in typesetting but if tomorrow I need to start writing a technical book, I'd still pick Latex.

I've used Lyx to create Latex output. It was very nice.

This was an interesting read. Thanks for sharing the template repository too. The part about “Writing one sentence per line” made a lot of sense for the source text and for diffs being easier to handle.

Overall, the process of writing text and turning it into a book format like ePub and PDF seemed a lot easier with this post (of course, this post is not for books with mathematical equations and other more stringent typography and layout requirements).

For my book Hands on Scala, I did a totaly different approach: parsed markdown into HTML myself, used puppeteer to turn it into PDFs. I extended markdown with some macros to do the things I needed (e.g. named cross-references, two-column sections, graphviz diagram blocks, pulling in code snippets from the examples folder)

The build tool made it easy to import libraries like CommonMark-Java or ApachePDFBox to do what I wanted, wire in external tools like Puppeteer, and gave parallelism and incrementality for free. End result was <1s turnaround on editing chapters and <60s turnaround to regenerate the whole book from scratch, with the ability to spit out pdf/epub/web versions of the book in both 5-chapter-preview and 20-chapter-full versions. Since it's all HTML/CSS, and I'm a web developer, I could make it look any way I wanted.

The build pipeline is here, if anyone wants to take a look https://github.com/handsonscala/build. There's a link to the main website you can download samples to see how it ends up looking

I see that you have a physical copy on sale on amazon KDP - How do you manage getting a pdf into KDP (I understand it is possible just that it is not recommended / renders poorly)?

AsciiDoc looks like a cool option. I wrote mine in Libre Office Write. Then I wrote a small book with step by step instructions for how to do it.

Here’s the book. It’s available on Kindle Unlimited if you have that.

https://www.amazon.com/gp/product/B00A4112ZM

This is another book with Asciidoc that takes things a bit further: https://medium.com/sketch-app-sources/using-sketch-and-ascii...

This is awesome. You have successfully made writing a book look like fun (although I know it’s actually very hard). Now I just need something to write about.

This is arguably within the context of "how to write books" -- what did you do to draw illustrations and figures? (I've taken a look at Inkscape. What I want to do is have line drawings of crystallographic shapes, so a constraint-based illustrator would be ideal. I've never understood why the ideas behind Ivan Sutherland's Sketchbook have never seemed to make it into existing drawing packages.)

Thanks for this article, I will come back to it in the future. By the way, the link to the Spell Right extension actually links to the AsciiDoc extension.

> By the way, the link to the Spell Right extension actually links to the AsciiDoc extension.

D'oh! :) Thanks! I've fixed it.

This is an interesting approach to self promotion.

Instead of outright saying “I wrote a book, you should buy it!”, you generate some form of meta-content revolving around your book, that ideally fits the kind of content that would be appreciated by the people on whatever platform you’re doing the promotion on.

Admittedly this ain’t exactly rocket science and in this specific case the actual agenda is so obvious as to make ones eye roll but it does make you wonder about other more subtle techniques being applied.

And very quickly this can lead to a form of existential crisis where you wonder if anything you see, even say on hn, has any actual value or maybe its all just people finding ways to hijack and abuse basic human neural mechanisms in order to generate revenue off of others.

And then you wonder, what does that make them? If these people and what they do are solely defined by what others find “interesting”, or by what can be profitable - what does that mean about who they are? Like, they are essentially non-entities, with no real human substance to them: they are the descriptions of our worst tendencies and reflections of economic mechanisms. I think this is called “soulless”.

Maybe I should write a post about how I wrote this post. Like subscribe and leave a comment :)

> maybe its all just people finding ways to hijack and abuse basic human neural mechanisms in order to generate revenue off of others.

I'm not going to let your exceptionally cynical content hijack my neural mechanisms!

Reply on news.ycombinator.com