|
|
[[!meta title="Literate Documentation with Emacs and Org Mode"]]
[[!meta copyright="Copyright © 2023 Mike Hamrick"]]
[[!inline pages="internal(2023/info/doc-nav)" raw="yes"]]
<!-- Initially generated with emacsconf-publish-talk-page and then left alone for manual editing -->
<!-- You can manually edit this file to update the abstract, add links, etc. --->
# Literate Documentation with Emacs and Org Mode
Mike Hamrick
[[!inline pages="internal(2023/info/doc-before)" raw="yes"]]
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.
Wouldn’t it be great if the tool you used for writing knew how to run code in a variety of programming languages, collect and format output, and let you refer symbolically to all this dynamically generated content in your prose? In this talk I’ll demonstrate how to use GNU Emacs’ Org mode to create technical documents that do just that. We’ll explore the features of Babel, Org mode’s literate programming add-on, that makes it convenient to edit, evaluate, and manage embedded code, output, and data all from inside GNU Emacs.
We'll also show how these literate documents can be exported to LaTeX and ultimately PDF format to create professional looking output that looks stunning when printed or viewed.
Also shared at SeaGL 2023
# Discussion
## Questions and answers
- Q: Did you develop a variant of your document for Centos?
- A:
- Q: Great presentation. The preparation is outstanding. For someone
like me that never touched the org--mode side of emacs, what do you
feel its the more complex part to tackle? You made it seem simple
but the complexity there.. woof
- A:
- Q: How do you normally debug, e.g. view the logs or see failed
statuses, when the commands in the src blocks fail? Especially if
they output lots and lots of logs, and you need to see the full
history of the build.
- A:
- Q: Do you find yourself doing plain-text exports? I saw you doing
that as an example for a bit. How do you like to format them so they
come out looking nice?
- A:
- Q: IIUC if you commit that eval line to your config then theoretically you could open an Org file prepared by someone else and it would automatically run the code in a "startup" block that might be malicious, right?
- A: for sure. if you agree to have a block run when you load the document, you could get burned if it changes into something eveil.
### Notes and discussion
- Seems like we could use some kind of extension that would hash a source block and allow you to automatically run ones you've marked safe
- Property inheritance I still don't completely understand, heh.
- seeing section on Org MACRO, recall having trouble a while back invoking a MACRO from inside a MACRO; is this a limitation or was I holding it wrong?
- AFAIR, macros do support recursion
- actually my issue was passing TITLE to a MACRO <https://paste.rs/LZunR>
- yeah. "eval" macro arguments in particular are not expanded. you may raise it on the mailing list - looks like something worth considering
- I almost wanted to pre-process my org mode files with a more advanced macro system like m4. But then I came to my senses.
- When discussing Org mode as replacement of TexInfo, it has been rised (Texinfo uses m4) (<https://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html#External-Macro-Processors>) but why do you need m4 when there is Elisp... can just put a code block that will do all the work and eval on export
- A: True. You can write elisp to do all the macro replacement, but you end up editing the buffer when you do that, which has its own disadvantages.
- during export, it is a throwaway buffer
- A: oh, I didn't think of that. Ultimately though org macros have a ways to go before they're truly useful in all context you might want to use them.
- org-export-before-processing-hook runs before macro expansion but around the same time (we really need to document the export process step by step)
- Thanks for the awesome presentation, I can't wait to add some of this stuff to my documents
- I was pretty terrified to see that ChatGPT could write elisp
- Also, loved the presentation — great walk-through of the thought process & how to improve. Was happy when Macros made their way in
- Yeah. tramp would have been cool, but can be dangerous if you start doing sudo apt in the wrong machine
- I tried cross-compiling Emacs for Serenity. Emacs uses some intermediate binaries (like make-docfile) during its build process, which causes issues with cross-compiling that I couldn't quite figure out.
[[!inline pages="internal(2023/info/doc-after)" raw="yes"]]
[[!inline pages="internal(2023/info/doc-nav)" raw="yes"]]
|
