使用 Emacs 和 Org Mode 编写一致的技术文档
Consistent Technical Documents Using Emacs and Org Mode
频道:spudlyo · 时长:22:43 · 发布:2019-11-17 · 播放:74079
简介
演示如何使用 org-babel 在 Emacs Org mode 中编写技术文档,使代码块和生成内容在变化时保持一致。作者分享了演示文件和他的 dotfiles。
HN 为什么推荐
HN 评论者推荐它,认为它实际展示了 Org mode 和文学编程能为文档做什么。
我认为它很好地展示了 Org 的强大之处。 — HN, 2021
中文字幕节选
大家好,在这个视频中我将演示 Emacs 的 org-mode 特别是如何结合 org-babel 来创建技术文档 比如文章、博客帖子和操作指南。在撰写关于编程或其他 技术主题的内容时,你经常需要将源代码块、程序输出和 原始数据与你的文字交织在一起。这些补充材料通常 是从其他来源复制粘贴到你的文档中的,随着情况变化, 保持它们更新可能既困难又繁琐,不一致和 错误很容易悄悄出现,当你将程序输出等动态信息 硬编码到写作中时。在这个例子中,我们将撰写一篇博客文章, 介绍如何使用 git 底层命令在 Python 中手动创建 git 对象。我选择 这个例子是因为有很多动态内容,比如字符串和 SHA-1 哈希需要处理。我使用的是 GNU Emacs 26.3,在 tmux 中的 终端框架。我也使用 GUI 框架,在 org 中看起来很棒,使用相同的 底层服务器进程,我将在视频结尾展示。如果你 不知道 org mode 是什么,可以把它看作是一种增强的 Markdown 语言。它是一种纯文本格式化语法,设计用于转换为 更花哨的格式,如 HTML 或 PDF。你可能已经使用过 Markdown 语言,也许甚至没有意识到,在创建 GitHub 或 GitLab 的 README 文件时,或在 Reddit 等在线讨论论坛上撰写消息时。 当我们说 org-mode 时,我们指的是 Emacs 处于一种模式,它知道你正在编辑 一个 org Markdown 语言的文件。这个模式通过自动 渲染你的缓冲区来帮助你,并给你一些键命令来轻松 操作文档结构。如果你在 Emacs 之外查看你的 Org mode 文件,你可以看到纯文本未渲染格式的样子。 我之前提到 Markdown 设计用于转换为其他 格式。让我们看看将 org 导出为 HTML 时的样子。哦, 1994 年打电话来说他们想要回他们的网站。不过别担心,你可以添加一些 那种老式的 Web 2.0 东西,比如 CSS 字体和 JavaScript。我已经设置好了 一个文件中的东西,告诉 org 在导出我们的 文档时加载并解析。setup file 指令可以引用 URL 或文件。这个文件有 一堆 HTML head 指令,告诉 HTML 导出器包含本地的 JavaScript 包副本,如 jQuery 和 Twitter Bootstrap,以及 一些 CSS,实现了这个非常酷的受“read the docs”启发的 org 主题, 叫做 read the org,由 Fabrice Niessen 制作。现在我们已经配置了 setup 文件, 让我们重新生成 HTML。嗯,是的,现在看起来好多了。既然 那已经解决了,让我们回到我们的文章。在 git 文章的这一部分,我们 想要演示如何手动完成 git init 的工作,通过 创建 .git 目录和需要放入其中的东西。org 有
HN 上的讨论
感谢推荐!我认为 org-babel 非常适合这项任务,可以做出非常棒的文档。你可以查看演讲中的视频[0]和一个包含更高级演示的 git 仓库[1]。[0]:[VIDEO] [1]:[LINK] — spudlyo, 2025-04
Org mode 能做很多不同的事情,但我发现一个有趣的用例是能够以在事物变化时保持一致的方式,在技术文档中混合散文和程序输出。大约一年前我做了一个视频[0],探讨了 Org 的文学编程功能,我认为它很好地展示了 Org 的强大。[0]:[VIDEO] — spudlyo, 2021-08
我做了一个视频[0],展示了 org-babel 的强大功能,它是 org 的一部分,让你可以在文档中嵌入动态代码块。在视频中,我写了一篇关于 git 如何存储数据的小文章[1],其中包含大量由 org 管理的动态内容。这有点像可重复研究或文学编程,但对我来说,这一切都是为了编写在事物变化时易于保持一致的技术文档。[0]:[VIDEO] [1]:[LINK] — spudlyo, 2021-03
Org mode 支持可导出为 HTML 的内联 LaTeX。这里有一个关于如何使用 Emacs 和 Org mode 编写技术文档的精彩演示 [VIDEO] — d0mine, 2020-06
这是我过去几周所做的,进展相当不错:从纯 Emacs 开始。打印/写出流行的速查表。只要确保你知道如何退出、访问文档以及在窗口/框架/缓冲区之间移动。获取 Melpa 并安装一些包。摆弄配置,添加键绑定,弄清楚钩子等等。从 GitHub 上的 dotfiles 复制一些 elisp 函数。对所有东西狂用文档命令。对需要大量折腾才能达到你在博客文章中看到的疯狂配置感到沮丧。通过消费更多关于自定义配置的内容来保持动力。发现 magit、parinfer 和 dired 的魔力。在 GitHub 上查找一些 org-mode/PIM 大神,用户名:novoid、alphapapa、karlicoss 安装 Doom。稍微摆弄一下。在 org 文件中记录你的学习笔记。再摆弄一下。回到纯 emacs 一会儿。然后试试 spacemacs。直接回到 Doom,因为它更快,而且你现在对 emacs 了… — rwnspace, 2020-04
相关视频
- 纯文本 - Dylan Beattie - NDC 哥本哈根 2022 · NDC Conferences · 59:19
- Evil Mode:或者,我如何学会停止担忧并爱上 Emacs · thoughtbot · 40:02
- 27C3:分析 Stuxnet 的冒险(微软的 Bruce Dang) · basti0007 · 1:14:56
- Emacs Rocks! 第17集:Magit · emacsrocks · 2:39
- 知识应该免费吗? · Medlife Crisis · 22:32
- RailsConf 2014 - Sandi Metz 谈所有的小细节 · Confreaks · 38:47
- “用确定性模拟测试分布式系统” by Will Wilson · Strange Loop Conference · 40:20
- 🚀 TDD,哪里出错了(Ian Cooper) · DevTernity Conference · 1:03:55
- Bret Victor - 在原则中发明 · Rui Oliveira · 54:20
- Bret Victor:编程的未来 · Joey Reid · 32:55
- 用 Clojure 的方式解决问题 - Rafal Dittwald · Clojure/north · 1:02:26
- 火线调试:系统失控时保持冷静 • Bryan Cantrill • GOTO 2017 · GOTO Conferences · 52:34
- Emery Berger 的“性能至关重要” · Strange Loop Conference · 42:15
- “Uncle” Bob Martin - “编程的未来” · Paul Stringer's Mobile Tech · 1:18:21
- Acme编辑器之旅 · Russ Cox · 23:16
- 技术演讲:Linus Torvalds 谈 git · Google · 1:10:15