Consistent Technical Documents Using Emacs and Org Mode
Channel:spudlyo · Length:22:43 · Published:2019-11-17 · Views:74079
Summary
A demo of writing technical documents in Emacs Org mode using org-babel, so that code blocks and generated content stay consistent when things change. The author shares the demo files and his dotfiles.
Why HN recommends it
HN commenters recommend it as a practical illustration of what Org mode and literate programming can do for documentation.
I think does a pretty good job of illustrating the power of Org. — HN, 2021
Testing, debugging & developer tools · Software practice, open source & careers
Subtitles (excerpt)
hi there in this video I'm going to be demonstrating emacs's org-mode specifically how to use it with or babble to create technical documents like essays blog posts and how-to guides when writing about programming or other technical subjects you're often weaving blocks of source code program output and raw data in with your prose these supplementary materials are usually copied and pasted into your document from other sources which can be difficult and tedious to keep up to date as things change inconsistencies and errors can easily creep in when you hard code dynamic information like program output into your writing in this example we're going to be writing a blog post on how to manually create get objects using git plumbing commands on Python I chose this example because there's lots of dynamic content like strings and sha-1 hashes to contend with I'm using the GNU Emacs 26.3 and a terminal frame inside of tmux I also use GUI frames which can look pretty great in org with the same underlying server process which I'll show towards the end of the video if you don't know what org mode is you can think of it as an enhanced markdown language it's a plain text formatting syntax that is designed to be converted
On Hacker News
Thanks for the shout-out! I think org-babel is really well suited for this task, and can make some really great documentation. You can check out the video[0] from the talk and a git repo[1] with a more advanced demonstration. [0]: [VIDEO] [1]: [LINK] — spudlyo, 2025-04
Org mode does a lot of different things, but one use case I find interesting is to be able to mix prose and program output in a technical document in a way that keeps things consistent when things change. I made a video[0] a year or so ago that explores Org's literate programming features that I think does a pretty good job of illustrating the power of Org. [0]: [VIDEO] — spudlyo, 2021-08
I made a video[0] showing off the power of org-babel, which is the part of org that lets you embed dynamic code blocks in your document. In the video I write a little essay[1] on how git stores data that has a lot of dynamic content that is managed by org. It's a bit like reproducible research or literate programming, but for me it's all about writing technical documents that are easy to keep con… — spudlyo, 2021-03
Org mode supports inline Latex that can be exported to html. Here's a nice demo on how to write tech docs using Emacs and Org mode [VIDEO] — d0mine, 2020-06
This is what I've done the past couple weeks and it's going pretty well: Start with plain Emacs. Print/write out the popular cheatsheets. Just make sure you know how to exit, access the documentation, and move around the windows/frames/buffers. Get Melpa & install some packages. Play with the config, adding keybindings, figure out hooks and so on. Copy some elisp functions from dotfiles on Github… — rwnspace, 2020-04
Related videos
- Plain Text - Dylan Beattie - NDC Copenhagen 2022 · NDC Conferences · 59:19
- Evil Mode: Or, How I Learned to Stop Worrying and Love Emacs · thoughtbot · 40:02
- 27C3: Adventures in analyzing Stuxnet (Bruce Dang from Microsoft) · basti0007 · 1:14:56
- Emacs Rocks! Episode 17: Magit · emacsrocks · 2:39
- Should Knowledge Be Free? · Medlife Crisis · 22:32
- RailsConf 2014 - All the Little Things by Sandi Metz · Confreaks · 38:47
- "Testing Distributed Systems w/ Deterministic Simulation" by Will Wilson · Strange Loop Conference · 40:20
- 🚀 TDD, Where Did It All Go Wrong (Ian Cooper) · DevTernity Conference · 1:03:55
- Bret Victor - Inventing on Principle · Rui Oliveira · 54:20
- Bret Victor The Future of Programming · Joey Reid · 32:55
- Solving Problems the Clojure Way - Rafal Dittwald · Clojure/north · 1:02:26
- Debugging Under Fire: Keep your Head when Systems have Lost their Mind • Bryan Cantrill • GOTO 2017 · GOTO Conferences · 52:34
- "Performance Matters" by Emery Berger · Strange Loop Conference · 42:15
- "Uncle" Bob Martin - "The Future of Programming" · Paul Stringer's Mobile Tech · 1:18:21
- A Tour of the Acme Editor · Russ Cox · 23:16
- Tech Talk: Linus Torvalds on git · Google · 1:10:15