用 AsciiDoc 编写的全新手册

第 2 部分

这是我为全新 Merlin Project 手册所做项目报告的第二部分。我会尝试每周五就该项目给出一份或长或短的进展更新。

该项目

在我们投入 AsciiDoc 之前，先快速看一眼我的项目。

• Git 仓库已搭建完成
• 各条目已确定，部分也已 在此 列出。
• 各项前提条件大致已知。
• 已创建初步的章节结构，现正逐步加以完善。
• 配图我先只使用 快速截图，必要时再重新制作。
• 已确定一个固定的写作日。

恰恰是最后一点对我而言是一个真正的挑战，因为我无论如何都得腾出写作的时间。如果只是 利用每一分空闲时间，我大概永远写不完。我需要一个固定的时间块，而我恰好为自己创造了它。从现在起，周三是我的手册写作日。看看这能坚持多久吧……

当然少不了一块看板。抱歉用的是英文，我们内部文档很多都是用英文撰写的。

Asci

iDoc 技巧

拆分文件

我不会把手册写在一个文件里，而是倾向于按章节拆分。此外，我把手册的变量和属性外置到一个单独的文件中，这样我既可以单独构建各个文件或在浏览器中查看，又 能使用所有变量和属性。这个文件在我这里通常名为 Attributes，为了能随时快速找到它，我给它加上一个 "_"，这样它在文件列表中始终排在最前面。

ifndef::_attributes[]
include::_attributes.de.adoc[]
endif::[]

1. 这里我查询变量 _attributes 是否已经设置。
2. 如果尚未设置，则包含该文件。

这样我便确保属性文件不会被多次加载，因为每个文件都以这几行开头。

我的快速周转流程

虽然我目前还独自编写手册，但所有文本和媒体都会进入 Git。也就是说，我早晨的写作开始于终端，或者，视手头当时有什么而定，使用 BBEdit Unix Worksheet，先来一个利落的 git pull。然后我打开 BBEdit 项目文件（它当然包含在仓库中），便能在左侧列表中看到所有包含的文件。

我把屏幕大致分成两半：左侧用于写作，右侧打开 Chrome。我只需把正在编辑文件的代理图标拖入浏览器窗口。得益于 Asciidoctor.js 扩展，每次在 BBEdit 中保存时，浏览器都会自动刷新。

今天就到这里，下周继续。

---

续篇：用 AsciiDoc 编写的全新手册，第 3 部分

---

如果您对这篇博客文章有任何疑问或希望参与讨论，欢迎您在我们的论坛中发帖。