Back in 2019, I wrote about Mike Hamrick’s excellent talk on using Emacs and Org mode for writing technical documents. I’ve mentioned it a couple times since and sometimes watch it again for some of the many great ideas embedded in it.
For the SeaGL 2023 conference, Hamrick updated his talk and showed how to produce a much more complicated document using Literate Document techniques. The goal was to produce a document showing how to build Emacs on a bare-bones Linux system. That means he has to worry about installing the necessary prerequisites, and getting everything configured for a successful Emacs build.
That sounds like a pain but is pretty straightforward. The wrinkle is that he wants to produce documents for both Red Hat and Debian based systems, which have different directory structures and utilities. He could, of course, write one and clone it making the necessary changes but we all know why that’s a terrible idea. Instead, he wrote a single document with code blocks that configure it for the required system.
In the end, he not only ends up with a nice looking document tailored to the target system, but the document includes code blocks that will actually do the install including downloading the prerequisites and making any necessary configuration changes.
The talk is pretty fast paced but he has a GitLab repo that contains everything from the talk including the final Org document so you needn’t stress about trying to take everything from the video. This is a really good talk and along with the 2019 version is something that everyone writing documents with Org mode should be familiar with. You should definitely invest the time to watch them both.