Org Mode 简明指南

重要提示: 若使用的Org版本已集成在Emacs发行版中, 请跳过本节直接阅读[激活]​部分. 若从网络下载了Org(无论是.zip或.tar压缩包, 还是Git仓库), 建议直接从解压目录运行. 需将 lisp/ 子目录加入Emacs加载路径, 请在init文件中添加以下代码:

(add-to-list 'load-path "~/path/to/orgdir/lisp")

若通过Git或压缩包获取Org, 需执行以下命令生成自动加载信息:

make autoloads

在Emacs init文件中添加以下代码, 为三个通用命令(不仅限于Org缓冲区)设置全局快捷键(请自行选择合适按键):

(global-set-key (kbd "C-c l") #'org-store-link)
(global-set-key (kbd "C-c a") #'org-agenda)
(global-set-key (kbd "C-c c") #'org-capture)

扩展名为 .org 的文件将自动启用Org模式.

若发现Org存在问题, 或有疑问, 建议, 构思, 请发送邮件至Org邮件列表emacs-orgmode@gnu.org. 提交错误报告的具体方式请参阅主手册.

标题定义了大纲树的结构. Org 中的标题从左边距开始, 以一个或多个星号后跟一个空格. 例如:

  • 顶级标题
  ** 二级标题
  * 三级标题
  一些文本
  * 三级标题
  更多文本
  • 另一个顶级标题

注意, 命名为 org-footnote-section 的标题(默认为"Footnotes")被视为特殊标题. 带有此标题的子树在导出时将被静默忽略.

有些人觉得多个星号太杂乱, 更喜欢使用空格后接单个星号作为标题开始符. 参见第15章 [杂项]​, 了解实现此设置的方法.

轮廓可以隐藏缓冲区中的部分文本. Org 使用两个命令, 绑定到 TAB 和 S-TAB 来更改缓冲区中的可见性.

• TAB 子树切换: 将当前子树在不同状态间轮换. 当使用前缀参数(C-u TAB)或按住 Shift 键调用时, 触发全局切换.
• S-TAB 或 C-u TAB 全局切换: 将整个缓冲区在不同状态间轮换.
• C-u C-u C-u TAB 显示所有内容, 包括抽屉.

参见变量 org-special-ctrl-a/e 以配置标题中 C-a 和 C-e 的特殊行为.

以下命令用于跳转到缓冲区中的其他标题:

• C-c C-n 下一个标题.
• C-c C-p 上一个标题.
• C-c C-f 同级下一个标题.
• C-c C-b 同级上一个标题.
• C-c C-u 向后跳转到更高一级标题.

• M-RET 插入与当前标题同级的新标题. 如果光标在普通列表项中, 则创建新列表项(参见第2.6节 [普通列表]​). 如果在行中间使用此命令, 行将被分割, 剩余部分成为新标题.
• M-S-RET 插入与当前标题同级的新 TODO 条目.
• TAB 在新空条目中: TAB 在合理级别间循环.
• M-LEFT 和 M-RIGHT 将当前标题提升或降级一级.
• M-UP 和 M-DOWN 将子树向上或向下移动, 即与同级的上一个或下一个子树交换.
• C-c C-w 将条目或区域重新归档到其他位置. 参见第9.2节 [重新归档和复制]​.
• C-x n s 和 C-x n w 将缓冲区缩小到当前子树或再次扩大.

当存在活动区域(Transient Mark mode)时, 升级和降级对区域内的所有标题生效.

如果不想分割行, 请自定义变量 org-M-RET-may-split-line.

Org 模式的一个重要功能是能够为选定信息构建稀疏树, 使整个文档尽可能折叠, 但选定信息及其上方的标题结构可见. 尝试一下, 你会立刻明白其工作原理.

Org 模式包含多个创建此类树的命令, 这些命令都可以通过调度器访问:

• C-c / 提示输入一个额外的键以选择创建稀疏树的命令.
• C-c / r Occur. 提示输入正则表达式并显示包含所有匹配项的稀疏树. 每个匹配项也会高亮显示; 按 C-c C-c 可清除高亮.

其他稀疏树命令基于 TODO 关键字, 标签或属性选择标题, 将在本文档后面讨论.

在轮廓树的条目中, 可以使用手工格式化的列表. 列表在下一行缩进与项目符号/编号相同或更少时结束. 列表在所有项目关闭或遇到两个空行时结束. 例如:

▼ <指环王>
我最喜欢的场景(按此顺序):
1. 洛汗骑兵的进攻
2. 伊欧玟与巫王的战斗
   ◦ 这已经是书中的可能性中的最爱场景
   ◦ 我非常喜欢米兰达·奥托.
这部电影中的重要演员:
– 伊利亚·伍德 :: 他扮演弗罗多
– 肖恩·阿斯汀 :: 他扮演山姆, 弗罗多的朋友.

以下命令在光标位于列表项第一行(带有项目符号或编号的行)时对列表项生效:

• TAB 列表项可以像标题级别一样折叠.
• M-RET 在当前级别插入新列表项. 如果带有前缀参数, 强制插入新标题(参见第2.4节 [结构编辑], 第3页).
• M-S-RET 插入带有复选框的新列表项(参见第5.6节 [复选框], 第12页).

如果链接看起来不像 URL, 则被视为当前文件的内部链接. 最重要的情况是类似 [[my-custom-id]] 的链接, 它指向具有"CUSTOM_ID"属性"my-custom-id"的条目.

类似 [[My Target]] 或 [[My Target][Find my target]] 的链接会在当前文件中进行文本搜索. 以下是一些示例:

http://www.astro.uva.nl/~dominik                    web
file:/home/dominik/images/jupiter.jpg               本地绝对路径
/home/dominik/images/jupiter.jpg                    本地绝对路径
file:papers/last.pdf                                本地相对路径
./papers/last.pdf                                   本地相对路径
file:projects.org                                   org文件
docview:papers/last.pdf::NNN                        使用docview打开第NNN页
id:B7423F4D-2E8A-471B-8810-C40F074717E9             跳转到id为xxx的标题
news:comp.emacs                                     usernet链接
mailto:adent@galaxy.net                             邮件链接
mhe-folder#id                                       HME 链接
rmail:folder#id                                     rmaiul链接
gnus:group#id                                       gnu文章
bbdb:R.*Tallman                                     BBDB正则链接
irc://irc.com#emacs/bob                             IRC链接
info:org#Hyperlinks                                 Info节点链接

文件链接可以包含额外信息, 以便在跟随链接时跳转到文件的特定位置. 这可以是行号或搜索选项, 位于双冒号之后. 例如:

file:~/code/main.c::255              跳转到文件的第225行
file:~/xx.org::My Target             跳转到<<My Target>>
[[file:~/xx.org::#my-custom-id]]     跳转到有custom id的条目上

Org 提供了创建正确语法链接, 将其插入 Org 文件以及跟随链接的方法.

主要功能是 org-store-link, 通过 M-x org-store-link 调用. 建议将其绑定到常用键(参见 [激活]​). 它会存储当前位置的链接, 供稍后插入 Org 缓冲区.

在 Org 缓冲区中, 以下命令用于创建, 导航或操作链接:

• C-c C-l 插入链接. 提示输入要插入缓冲区的链接. 可以使用上下键访问存储的链接. 系统会提示输入链接的描述部分. 如果使用 C-u 前缀参数, 会启用文件名完成以链接到文件.
• C-c C-l (光标在现有链接上)允许编辑链接和描述部分.
• C-c C-o 打开光标处的链接.
• C-c & 跳回到记录的位置. 连续多次使用此命令会在先前记录的位置环中移动.

任何以"TODO"开头的标题都会成为待办事项, 例如:

***▿  TODO  给 Sam Fortune 写信

处理待办条目的最重要命令包括:

• C-c C-t 在以下状态间轮换当前条目的 TODO 状态: 也可以通过议程缓冲区中的 t 命令键"远程"执行相同的轮换(参见第10.7节 [议程命令], 第25页).
• S-RIGHT 和 S-LEFT 更改 TODO 状态.
• C-c / t 或 M-x org-agenda t 显示全局待办列表. 从所有议程文件中收集待办事项(参见第10.4节 [全局待办列表], 第24页).
• M-S-RET 在当前标题下方插入新 TODO 条目.

更改 TODO 状态还可以触发标签更改. 有关详细信息, 参见选项 org-todo-state-tags-triggers 的文档字符串.

可以使用 TODO 关键字来表示顺序工作进度状态:

(setq org-todo-keywords
  '((sequence "TODO""FEEDBACK""VERIFY""|""DONE""DELEGATED")))

垂直线将"TODO"关键字(需要行动的状态)与"DONE"状态(无需进一步行动)分开. 如果不提供分隔线, 最后一个状态被用作"DONE"状态. 使用此设置, 命令 C-c C-t 将条目从"TODO"循环到"FEEDBACK", 然后到"VERIFY", 最后到"DONE"和"DELEGATED".

有时可能需要并行使用不同的 TODO 关键字集. 例如, 可能需要基本的"TODO"/"DONE", 同时还有一个用于修复错误的工作流程. 设置如下:

(setq org-todo-keywords
  '((sequence "TODO(t)""|""DONE(d)")
    (sequence "REPORT(r)""BUG(b)""KNOWNCAUSE(k)""|""FIXED(f)")))

关键字应各不相同, 这有助于 Org 模式跟踪给定条目应使用哪个子序列. 示例还展示了如何为特定状态定义快速访问键, 在每个关键字后添加括号中的字母–按 C-c C-t 后会提示输入该键.

要在单个文件中定义有效的 TODO 关键字, 请在文件中任何位置使用以下文本:

TODO: TODO(t) | DONE(d)
TODO: REPORT(r) BUG(b) KNOWNCAUSE(k) | FIXED(f)
TODO: | CANCELED(c)

更改这些行后, 将光标放在该行上使用 C-c C-c 使更改对 Org 模式生效.

要记录更改 TODO 状态时的时间戳和笔记, 请使用前缀参数调用命令 org-todo.

关闭条目: 最基本的日志记录是跟踪某个待办事项何时被标记为完成. 这可以通过以下设置实现:

(setq org-log-done 'time)

每次将条目从 TODO(未完成)状态转换为任何 DONE 状态时, 将在标题下方插入一行"CLOSED: [Timestamp]".

如果希望记录时间戳的同时附带笔记, 请使用:

(setq org-log-done 'note)

系统会提示输入笔记, 该笔记将以"Closing Note"标题存储在条目下方.

跟踪 TODO 状态更改: 可能需要跟踪 TODO 状态更改. 可以记录仅时间戳或带时间戳的笔记. 这些记录作为项目列表插入标题下方. 记录大量笔记时, 可以通过自定义变量 org-log-into-drawer 将笔记放入抽屉中.

状态日志记录需要按关键字进行配置. 通过在每个关键字后添加特殊标记"!"(表示时间戳)和"@"(表示笔记)来实现. 例如:

TODO: TODO(t!) WAIT(w@/!) | DONE(d!) CANCELED(c@)

定义 TODO 关键字和快速访问键, 并要求在条目设置为"DONE"时记录时间, 在切换到"WAIT"或"CANCELED"时记录笔记. 设置 org-todo-keywords 时也使用相同的语法.

如果广泛使用 Org 模式, 可能会积累足够多的待办事项, 需要对其进行优先级排序. 可以通过在待办事项标题中插入优先级 cookie 来实现, 例如:

***▿  TODO   #A  给 Sam Fortune 写信

通常建议将大型任务分解为较小的, 可管理的子任务. 可以通过在待办事项下创建轮廓树来实现, 包含详细的子任务. 为了跟踪已标记为完成的子任务比例, 可以在标题中插入"[/]"或"[%]". 每次子任务的 TODO 状态更改或在 cookie 上按 C-c # 时, 这些 cookie 都会更新. 例如:

▼ 组织派对     33%     
*▽  TODO  联系人     1/2     
*▽  TODO  Peter
*▽  TODO  Sarah
*▽  TODO  购买食物
*▽  DONE  与邻居交谈

普通列表(参见第2.6节 [普通列表], 第4页)中的每个项目都可以通过以字符串"[ ]"开头变成复选框. 复选框不包含在全局待办列表中, 因此常用于将任务拆分为简单的步骤. 例如:

▼  TODO  组织派对     2/4     
– □ 联系人     1/2     
  – □ Peter
  – ☑ Sarah
– ☑ 订购食物

复选框是层次化的, 因此如果一个复选框项目有子复选框, 切换子复选框会使父复选框反映子复选框的状态(无, 部分或全部选中).

以下命令适用于复选框:

• C-c C-c 切换光标处复选框的状态, 或使用前缀参数切换复选框的存在.
• M-S-RET 插入带有复选框的新列表项. 仅当光标已在普通列表项中时有效(参见第2.6节 [普通列表]​).

标签利用轮廓树的层次结构. 如果一个头条有某个标签, 其所有子头条都会继承该标签. 例如:

▼ 与法国小组会面 : work :
*▽ 弗兰克的总结 : boss : notes :
*▽  TODO  为他准备幻灯片 : action :

最后一个头条具有标签"work", "boss", "notes"和"action", 尽管未明确标记这些标签.

也可以设置整个文件条目应继承的标签, 就像在文件顶部使用"#+TAGS:"关键字, 例如:

TAGS: @work @home @tennisclub
TAGS: laptop car pc sailboat

默认情况下, Org 模式使用标准的 minibuffer 补全功能输入标签. 但它还实现了另一种更快捷的标签选择方法, 称为快速标签选择. 可以通过单次按键选择和取消选择标签. 为此, 建议为常用标签分配唯一字母. 可以在 Emacs 初始化文件中全局配置变量 org-tag-alist, 例如:

(setq org-tag-alist '(("@home". ?h)))

如果标签仅与当前文件相关, 可以设置"#+TAGS:"关键字, 例如:

TAGS: @work(w) @home(h) @tennisclub(t) laptop(l) pc(p)

标签可以定义为一组其他标签的组标签. 组标签可以视为其标签集的"更广泛的术语".

可以通过使用括号和在组标签与其相关标签之间插入冒号来设置组标签:

TAGS: [ GTD : Control Persp ]

或者, 如果组中的标签应互斥:

TAGS: [ Context : @home @work ]

搜索组标签时, 会返回组及其子组中所有成员的匹配项. 在议程视图中, 按组标签过滤会显示或隐藏至少带有一个组成员或其子组标签的头条.

如果想暂时忽略组标签, 可以使用 org-toggle-tags-groups, 绑定到 C-c C-x q.

• C-c / m 或 C-c \ 创建包含所有匹配标签搜索的头条的稀疏树. 使用 C-u 前缀参数, 忽略非 TODO 行的头条.
• M-x org-agenda m 创建所有议程文件中标签匹配的全局列表. 参见第10.5节 [匹配标签和属性], 第24页.
• M-x org-agenda M 与上述类似, 但仅检查 TODO 条目并强制检查子条目(参见选项 org-tags-match-list-sublevels).

这些命令都会提示输入匹配字符串, 支持基本的布尔逻辑, 如"+boss+urgent-project1", 查找带有"boss"和"urgent"标签但不带"project1"标签的条目, 或"Kathy|Sally"查找带有"Kathy"或"Sally"标签的条目. 搜索字符串的完整语法很丰富, 还支持匹配 TODO 关键字, 条目级别和属性. 有关更多示例, 参见第10.5节 [匹配标签和属性], 第24页.

时间戳是指定日期(可能包括时间或时间范围)的特殊格式, 例如 <2003-09-16 Tue> 或 <2003-09-16 Tue 09:39> 或 <2003-09-16 Tue 12:00-12:30>. 时间戳可以出现在 Org 树条目的头条或正文中. 其存在使条目在特定日期显示在议程中(参见 [周/日议程]​). 我们区分以下几种:

• 普通时间戳; 事件; 约会 简单时间戳仅为条目分配日期/时间. 这就像在纸质议程中写下约会或事件. 例如:

  ▼ 在电影院与 Peter 会面
   2006-11-01 Wed  19:15 
  ▼ 讨论气候变化
   2006-11-02 Thu  20:00-22:00 
  

• 带重复间隔的时间戳 时间戳可能包含重复间隔, 表明它不仅在给定日期适用, 而且在每隔 N 天(d), 周(w), 月(m)或年(y)重复. 例如:

  ▼ 在学校接 Sam
   2007-05-16 Wed  12:30 +1w 
  

• 日记式表达式条目 对于更复杂的日期规格, Org 模式支持使用 Emacs Calendar 包实现的特殊表达式日记条目. 例如, 带可选时间:

  ▼ 22:00-23:00 每月第二个星期四的书呆子会议
  <%(diary-float t 4 2)>
  

• 时间/日期范围 两个时间戳以"–"连接表示范围. 例如:

  ▼ 在阿姆斯特丹的会议
   2004-08-23 Mon      2004-08-26 Thu 
  

• 非活动时间戳 与普通时间戳类似, 但使用方括号而不是尖括号. 这些时间戳是非活动的, 不会触发条目显示在议程中. 例如:

  ▼ Gillian 第五次迟到
   2006-11-01 Wed 
  

要让 Org 模式识别时间戳, 必须采用特定格式. 以下命令均生成正确格式的时间戳:

• C-c . 提示输入日期并插入相应时间戳. 如果光标在现有时间戳上, 此命令会修改该时间戳而不是插入新的. 如果连续两次使用此命令, 将插入时间范围. 如果带前缀参数, 还会添加当前时间.
• C-c ! 与 C-c . 类似, 但插入非活动时间戳, 不会触发议程条目.
• S-LEFT 和 S-RIGHT 将光标处的日期更改一天.
• S-UP 和 S-DOWN 在时间戳的开头或括号处更改其类型. 在时间戳内部, 更改光标下的项目(年, 月, 日, 小时或分钟). 如果时间戳包含时间范围, 如"15:30-16:30", 修改第一个时间会同时移动第二个时间, 保持时间块长度不变. 要更改长度, 修改第二个时间.

时间戳前可以添加特殊关键字以便于计划:

• C-c C-d 在头条下方的行中插入"DEADLINE"关键字和时间戳. 含义: 任务(通常是待办事项, 但不一定)应在该日期完成. 在截止日期当天, 任务会列在议程中. 此外, 今天的议程会显示有关即将到来或错过的截止日期的警告, 从 org-deadline-warning-days 天前开始, 直到条目标记为完成. 例如:

  *▽  TODO  为<指南>撰写关于地球的文章
  DEADLINE:  2004-02-29 Sun 
  负责编辑: [bbdb:Ford Prefect]
  

• C-c C-s 在头条下方的行中插入"SCHEDULED"关键字和时间戳. 含义: 计划在给定日期开始处理该任务. 这与通常理解的安排会议不同, 在 Org 中安排会议只需插入不带关键字的时间戳. 例如:

  *▽  TODO  在新年前夜与 Trillian 约会
  SCHEDULED:  2004-12-25 Sat 
  

某些任务需要反复重复. Org 模式通过在"DEADLINE", "SCHEDULED"或普通时间戳中使用重复器来帮助组织此类任务. 例如:

*▽  TODO  支付租金
DEADLINE:  2005-10-01 Sat +1m 

"+1m"是重复器, 表示任务在"<2005-10-01 Sat>"有截止日期, 并从那时起每隔一个月重复.

Org 模式允许记录在特定任务上花费的时间:

• C-c C-x C-i 在当前条目上开始计时(clock-in). 插入"CLOCK"关键字和时间戳. 带 C-u 前缀参数时, 从最近计时的任务列表中选择任务.
• C-c C-x C-o 停止计时(clock-out). 在最后开始计时的地方插入另一个时间戳, 并直接计算结果时间, 插入为"=> HH:MM".
• C-c C-x C-e 更新当前计时任务的努力估算.
• C-c C-x C-q 取消当前计时. 如果错误开始计时或转而处理其他任务, 此命令很有用.
• C-c C-x C-j 跳转到当前计时任务的头条. 带 C-u 前缀参数时, 从最近计时的任务列表中选择目标任务.

在议程中(参见 [周/日议程]), 可以使用 l 键显示当天已完成或已计时的任务.

捕获允许以最小的中断快速存储笔记. 可以通过定义模板来为新条目设置不同的目标存储位置.

以下自定义设置了笔记的默认目标文件:

(setq org-default-notes-file (concat org-directory "/notes.org"))

还可以定义用于捕获新材料的全局键(参见 [激活], 第1页).

• M-x org-capture 启动捕获过程, 将你置于一个狭窄的间接缓冲区以进行编辑.
• C-c C-c 完成捕获过程, 将笔记存储在指定位置.
• C-c C-w 通过将笔记重新归档到其他位置完成捕获过程(参见第9.2节 [重新归档和复制]​).
• C-c C-k 中止捕获过程并返回到之前的状态.

可以为不同类型的捕获条目和目标位置使用模板. 例如, 想使用一个模板创建常规 TODO 条目, 并将其放在"/org/gtd.org"中的"Tasks"标题下; 还希望在"journal.org"中的日期树中捕获日记条目. 可能的配置如下:

(setq org-capture-templates
  '(
    ("t""Todo"entry (file+headline "~/org/gtd.org""Tasks")
     "* TODO %?\n  %i\n  %a")
    ("j""Journal"entry (file+datetree "~/org/journal.org")
     "* %?\nEntered on %U\n  %i\n  %a")))

如果从捕获菜单中按 t, Org 将为你准备如下模板:

  • TODO
  file:LINK TO WHERE YOU INITIATED CAPTURE

在模板扩展期间, 特殊 %-转义允许动态插入内容. 以下是一些可能的选项, 详情请参阅手册:

• %a 注解, 通常是使用 org-store-link 创建的链接
• %i 初始内容, 捕获时带 C-u 的区域
• %t, %T 时间戳, 仅日期或日期和时间
• %u, %U 与上述类似, 但为非活动时间戳
• %? 完成模板后将光标定位在此处

在审查捕获的数据时, 可能需要将某些条目重新归档或复制到其他列表, 例如项目中. 剪切, 找到正确位置然后粘贴笔记很麻烦. 为了简化此过程, 可以使用以下特殊命令:

• C-c C-w 将光标处的条目或区域重新归档到其他位置.
• C-c M-w 跳转到 org-refile 最后移动树的位置.
• C-c M-w 复制与重新归档类似, 但不删除原始笔记.

当项目(子)树完成时, 可能需要将其移出以避免干扰议程. 存档对于保持工作文件紧凑和全局搜索(如构建议程视图)快速至关重要.

最常见的存档动作是将项目树移动到另一个文件, 即存档文件:

• C-c C-x C-a 使用变量 org-archive-default-command 指定的命令存档当前条目.
• C-c C-x C-s 或简写 C-c $ 将光标处开始的子树存档到 org-archive-location 指定的位置.

默认存档位置是与当前文件同目录的文件, 文件名通过在当前文件名后追加"_archive"派生. 也可以选择将存档条目归档到哪个标题下, 甚至添加到文件的日期树中. 有关指定文件和标题的详细信息和示例, 参见变量 org-archive-location 的文档字符串.

还可以在缓冲区中使用选项设置此变量, 例如:

ARCHIVE: %s_done::

通常从变量 org-agenda-files 列出的所有议程文件中收集要显示的信息:

• C-c [ 将当前文件添加到议程文件列表的前面. 如果文件已在列表中, 则移到前面. 带前缀参数时, 文件被添加/移到列表末尾.
• C-c ] 从议程文件列表中移除当前文件.
• C-' 循环访问议程文件列表, 逐个访问文件.

视图通过调度器创建, 可通过 M-x org-agenda 访问, 最好绑定到全局键(参见 [激活], 第1页). 它显示一个菜单, 需要额外的字母来执行命令. 调度器提供以下默认命令:

• a 创建日历式议程(参见 [周/日议程]).
• t 创建所有待办事项的列表(参见第10.4节 [全局待办列表], 第24页).
• m 创建匹配给定表达式的头条列表(参见第10.5节 [匹配标签和属性], 第24页).
• s 创建由关键字和/或正则表达式的布尔表达式选择的条目列表.

周/日议程的目的是像纸质议程页面一样, 显示当前周或日的全部任务:

• M-x org-agenda a 从 Org 文件列表中为当前周编译议程. 议程显示每天的条目.

Org 模式理解日记的语法, 允许在 Org 文件中直接使用日记表达式条目:

▼ 假期
:PROPERTIES:
:CATEGORY: Holiday
:END:
%%(org-calendar-holiday) ; 假期名称的特殊函数
▼ 生日
:PROPERTIES:
:CATEGORY: Ann
:END:
%%(org-anniversary 1956 5 14) Arthur Dent 今年 %d 岁
%%(org-anniversary 1969 10 2) Mahatma Gandhi 将是 %d 岁

Org 可以与 Emacs 约会通知功能交互. 要添加议程文件的约会, 请使用命令 org-agenda-to-appt.

全局待办列表包含所有未完成的待办事项, 格式化并收集到一个地方. 远程编辑待办事项允许通过单次按键更改待办条目的状态. 有关待办列表中可用命令的详细信息, 参见第10.7节 [议程命令], 第25页.

• M-x org-agenda t 显示全局待办列表. 从所有议程文件中收集待办事项到一个缓冲区中.
• M-x org-agenda T 与上述类似, 但允许选择特定的 TODO 关键字.

如果议程文件中的头条带有标签(参见第6章 [标签], 第14页)或属性(参见第7章 [属性], 第16页), 可以根据这些元数据选择头条并收集到议程缓冲区中. 此处描述的匹配语法也适用于使用 C-c / m 创建稀疏树.

• M-x org-agenda m 生成匹配给定标签集的头条列表. 提示输入选择标准, 即标签的布尔逻辑表达式, 如"+work+urgent+withboss"或"work|home"(参见第6章 [标签], 第14页). 如果经常需要特定搜索, 可以为其定义自定义命令(参见第10.2节 [议程调度器], 第23页).
• M-x org-agenda M 与上述类似, 但仅选择也是待办事项的头条.

搜索字符串可以使用布尔运算符"&"表示 AND, "|"表示 OR. "&"的优先级高于"|". 目前不支持括号. 搜索的每个元素可以是标签, 匹配标签的正则表达式, 或类似"PROPERTY OPERATOR VALUE"的表达式, 访问属性值. 每个元素前可以加"-"表示排除, ""表示正向选择的语法糖. 当存在""或"-"时, AND 运算符"&"是可选的. 以下是一些仅使用标签的示例:

• "work+boss" 选择带有"work"标签但不带"boss"标签的头条.
• "work|laptop" 选择带有"work"或"laptop"标签的行.
• "work|laptop+night" 与上述类似, 但要求"laptop"行还带有"night"标签.

也可以同时测试属性, 详情参见手册.

此议程视图是 Org 模式条目的一般文本搜索工具, 特别适用于查找笔记.

• M-x org-agenda s~(~org-search-view)搜索包含"computer equipment"子字符串的条目.

搜索视图还可以使用布尔逻辑搜索条目中的特定关键字. 例如, 搜索字符串"+computer +wifi -ethernet -{8\.11[bg]}"查找包含关键字"computer"和"wifi"但不包含"ethernet"的笔记条目, 且不匹配正则表达式"8\.11b"或"8\.11g".

注意, 此命令还会搜索 org-agenda-text-search-extra-files 中列出的文件.

议程缓冲区中的条目链接回原始的 Org 文件或日记文件. 无法直接编辑议程缓冲区, 但提供了显示和跳转到原始条目位置的命令, 并可以从议程缓冲区"远程"编辑 Org 文件. 以下是众多命令中的一部分, 完整列表请探索议程菜单和手册.

• n 下一行(与 DOWN 和 C-n 相同).
• p 上一行(与 UP 和 C-p 相同).

• SPC 在另一个窗口中显示条目的原始位置. 带前缀参数时, 确保抽屉保持折叠.
• TAB 在另一个窗口中跳转到条目的原始位置.
• RET 跳转到条目的原始位置并删除其他窗口.

• o 删除其他窗口.
• v d 或简写 d 切换到日视图.
• v w 或简写 w 切换到周视图.
• f 向前移动时间, 显示当前时间段之后的跨度. 例如, 如果显示覆盖一周, 则切换到下一周.
• b 向后移动时间, 显示更早的日期.
• . 跳转到今天.
• j 提示输入日期并跳转到该日期.
• v l 或 v L 或简写 l 切换日志模式. 在日志模式中, 显示在启用日志时标记为完成的条目(参见变量 org-log-done)以及当天已计时的条目. 带 C-u 前缀参数时, 显示所有可能的日志条目, 包括状态更改.
• r 或 g 重新创建议程缓冲区, 例如反映条目时间戳修改后的变化.
• s 保存当前 Emacs 会话中的所有 Org 缓冲区以及 ID 的位置.

• 0--9 数字参数.
• t 更改议程和原始 Org 文件中条目的 TODO 状态.
• C-k 删除当前议程条目及其在原始 Org 文件中的整个子树.
• C-c C-w 重新归档光标处的条目.
• a 使用 org-archive-default-command 中指定的默认存档命令存档光标处的子树.
• $ 存档光标处头条对应的子树.
• C-c C-s 安排此条目. 带前缀参数时, 移除安排时间戳.
• C-c C-d 为此条目设置截止日期. 带前缀参数时, 移除截止日期.
• S-RIGHT 将与当前行关联的时间戳向前移动一天.
• S-LEFT 将与当前行关联的时间戳向后移动一天.
• I 开始当前条目的计时.
• o 停止先前开始的计时.
• x 取消当前运行的计时.
• J 在另一个窗口中跳转到运行中的计时.

• q 退出议程, 移除议程缓冲区.
• x 退出议程, 移除议程缓冲区及 Emacs 为编译议程加载的所有缓冲区.

自定义搜索的第一个应用是为经常使用的搜索定义键盘快捷键, 创建议程缓冲区或稀疏树(后者仅覆盖当前缓冲区).

可以通过变量 org-agenda-custom-commands 配置自定义命令. 可以通过从议程调度器(参见第10.2节 [议程调度器], 第23页)按 C 自定义此变量, 也可以在 Emacs 初始化文件中直接使用 Emacs Lisp 设置. 以下示例包含所有有效的议程视图:

(setq org-agenda-custom-commands
  '(
    ("w"todo "WAITING")
    ("u"tags "boss-urgent")
    ("v"tags-todo "boss-urgent")))

每个条目的初始字符串定义了在调度器命令后需要按的键, 通常是单个字符. 第二个参数是搜索类型, 后跟用于匹配的字符串或正则表达式. 上述示例定义了:

• w 全局搜索 TODO 关键字为"WAITING"的条目.
• u 全局标签搜索带有"boss"标签但不带"urgent"标签的头条.
• v 与上述相同, 但限制于也是待办事项的头条.

段落之间至少由一个空行分隔. 如果需要在段落内强制换行, 请在行末使用"\\".

要保留区域中的换行, 缩进和空行, 但使用常规格式, 可以使用以下结构, 也可用于格式化诗歌:

  VERSE
  头顶乌云密布
  黑色小鸟起起落落
  雪覆盖 Emacs
  ---AlexSchroeder
  VERSE

引用其他文档的段落时, 通常将其格式化为左右两侧缩进的段落. 可以在 Org 文档中这样包含引用:

  QUOTE
  一切都应尽可能简单,
  但不可过于简单 ---Albert Einstein
  QUOTE

要将文本居中, 可以这样做:

  CENTER
  一切都应尽可能简单, \\
  但不可过于简单
  CENTER

可以使单词变为"粗体", "斜体", "下划线", "逐字", "代码", 以及(如果需要)"删除线". 代码和逐字字符串中的文本不会被处理为 Org 特定语法; 它们会被逐字导出.

对于需要包含数学符号和公式的科学笔记, Org 模式支持在文件中嵌入 LaTeX 代码. 可以直接使用类似 LaTeX 的语法输入特殊符号, 公式和整个 LaTeX 环境. 例如:

太阳的半径是 \( R_s = 6.96 \times 10^8 \) 渲染为 \( R_s = 6.96 \times 10^8 \) 米. 另一方面, 半人马座阿尔法的半径是 \( R_{ac} = 1.28 \times R_s \) \( R_{ac} = 1.28 \times R_s \).

  SRC latex
    \begin{equation}
      % 任意环境,
      x = \sqrt{5}
      % 甚至表格, 图片
    \end{equation}
  SRC

如果 \( a = 2 \times b \) \( a = 2 \times b \) 并且 \( b = 2 \) \( b = 2 \), 那么解必须是 \( a = +\sqrt{2} \) \( a = +\sqrt{2} \) 或 \( a = -\sqrt{2} \) \( a = -\sqrt{2} \).

可以包含不应受标记影响的字面示例. 这些示例以等宽字体排版, 非常适合源代码等. 例如:

  EXAMPLE
  来自文本文件的一些示例.
  EXAMPLE

对于小型示例, 可以简单地以冒号加空格开头示例行. 冒号前也可以有额外的空格:

  这是一个示例
  : 来自文本文件的一些示例.

如果示例是编程语言的源代码, 或其他可以被 Emacs 中的 Font Lock 标记的文本, 可以要求示例看起来像 Emacs 缓冲区中的字体化效果:

   #+BEGIN_ SRC emacs-lisp
      (defun org-xor (a b)
        "Exclusive or."
        (if a (not b) b))
  SRC

要编辑示例, 使用 C-c ' 进入并离开支持该语言的特殊编辑缓冲区.

图片是到图片文件的链接, 没有描述部分, 例如:

./img/cat.jpg

如果需要为图片定义标题或内部交叉引用的标签(参见第4章 [超链接], 第8页), 请确保链接独占一行, 并在其前加上"CAPTION"和"NAME"关键字, 如下所示:

CAPTION: 这是下一张图片链接(或表格)的标题
NAME: fig:SED-HR4049
./img/a.jpg

脚注在以方括号中的脚注标记开始的段落中定义, 列 0 不允许缩进. 脚注引用只是文本中的方括号标记. 例如:

Org 主页[1] 现在看起来比以前好多了.
...
[1] 链接是: https://orgmode.org

以下命令处理脚注:

• C-c C-x f 脚注动作命令. 当光标在脚注引用上时, 跳转到定义处. 当在定义处时, 跳转到(第一个)引用. 否则, 创建新脚注. 带前缀参数时, 提供包括重新编号在内的额外选项菜单.
• C-c C-c 在定义和引用之间跳转.

导出调度器是 Org 导出的主要接口. 分层菜单呈现当前配置的导出格式. 选项以简单的开关形式显示在同一屏幕上.

• C-c C-e 调用导出调度器界面.

默认情况下, Org 导出整个缓冲区. 如果 Org 缓冲区有活动区域, 则仅导出该区域.

导出器识别缓冲区中的特殊行, 提供额外信息. 这些行可以放在文件中的任何位置:

TITLE: I'm in the Mood for Org

最主要的导出选项包括:

• TITLE 要显示的标题
• AUTHOR 作者(默认从 user-full-name 获取)
• DATE 日期, 固定或 Org 时间戳
• EMAIL 电子邮件地址(默认从 user-mail-address 获取)
• LANGUAGE 语言代码, 例如"en"

选项关键字集可以通过从导出调度器(参见第12.1节 [导出调度器], 第31页)按 # 使用"插入模板"命令插入.

目录包括文档中的所有头条. 其深度与文件中的头条级别相同. 如果需要使用不同的深度或完全关闭目录, 请相应设置变量 org-export-with-toc. 可以在每个文件的基础上使用"OPTIONS"关键字中的"toc"项实现相同的效果:

OPTIONS: toc:2 (仅在目录中包含两级)
OPTIONS: toc:nil (完全没有默认目录)

Org 通常在文件的第一个头条之前直接插入目录.

在导出期间, 可以包含另一个文件的内容. 例如, 要包含".emacs"文件, 可以使用:

INCLUDE: "~/.emacs"src emacs-lisp

第一个参数是要包含的文件名. 可选的第二个参数指定块类型: "example", "export"或"src". 可选的第三个参数指定用于格式化内容的源代码语言, 适用于"export"和"src"块类型.

可以使用 C-c ' 访问包含的文件.

以零个或多个空白字符开头, 后跟一个"#"和一个空格的行被视为注释, 因此不会被导出.

同样, #+BEGIN_COMMENT… #+END_COMMENT 之间的区域也不会被导出.

最后, 条目开头的"COMMENT"关键字(在任何其他关键字或优先级 cookie 之后)会注释掉整个子树. 以下命令帮助更改头条的注释状态:

• C-c ; 切换条目开头的"COMMENT"关键字.

ASCII 导出生成仅包含纯 ASCII 字符的输出文件. 这是最简单, 最直接的文本输出, 不包含任何 Org 标记. UTF-8 导出使用此编码标准中可用的额外字符和符号.

• C-c C-e t a 和 C-c C-e t u 导出为带有".txt"扩展名的 ASCII 文件. 对于"myfile.org", Org 导出到"myfile.txt", 覆盖而不警告. 对于"myfile.txt", Org 导出到"myfile.txt.txt"以防止数据丢失.

Org 模式包含一个与 XHTML 1.0 严格标准兼容的广泛 HTML 格式化的 HTML 导出器.

• C-c C-e h h 导出为带有".html"扩展名的 HTML 文件. 对于"myfile.org", Org 导出到"myfile.html", 覆盖而不警告. C-c C-e h o 导出为 HTML 并在网络浏览器中打开.

HTML 导出后端将"<"和">"转换为"&lt;"和"&gt;". 要在 Org 文件中包含原始 HTML 代码, 以便 HTML 导出后端可以插入该代码, 请使用以下内联语法: "...". 例如:

@@html:<b>@@粗体文本@@</b>@@

对于较大的原始 HTML 代码块, 使用以下 HTML 导出代码块:

HTML: 导出用的原始 HTML 代码
EXPORT html
这些标记之间的所有行都按字面导出
EXPORT

LaTeX 导出后端可以处理复杂文档, 合并标准或自定义 LaTeX 文档类, 使用替代 LaTeX 引擎生成文档, 并生成包含索引, 参考文献和目录的完全链接的 PDF 文件, 适用于交互式在线查看或高质量打印出版.

默认情况下, LaTeX 输出使用 article 类. 可以通过在文件中添加类似 #+LATEX_CLASS: myclass 的选项来更改类. 类必须列在 org-latex-classes 中.

• C-c C-e l l 导出为带有".tex"扩展名的 LaTeX 文件. 对于"myfile.org", Org 导出到"myfile.tex", 覆盖而不警告.
• C-c C-e l p 导出为 LaTeX 文件并将其转换为 PDF 文件.
• C-c C-e l o 导出为 LaTeX 文件并转换为 PDF, 然后使用默认查看器打开 PDF.

LaTeX 导出后端可以插入任意 LaTeX 代码, 参见第11.3节 [嵌入 LaTeX], 第28页. 在 Org 文件中嵌入此类代码有三种方式, 均使用不同的引用语法:

• 使用 @ 符号内联插入:

    @@latex:任意 LaTeX 代码@@
  

• 在 Org 文件中使用一个或多个关键字行插入:

    LATEX: 任意 LaTeX 代码
  

• 在 Org 文件中使用导出块插入, 后端按字面导出 begin 和 end 标记之间的代码:

    EXPORT latex
    任意 LaTeX 代码
    EXPORT
  

Org 模式的互操作性成功的很大一部分在于它能够轻松导出到外部应用程序或从中导入. iCalendar 导出后端从 Org 文件中获取日历数据并导出为标准 iCalendar 格式.

• C-c C-e i i 从当前 Org 缓冲区创建 iCalendar 条目并将其存储在同一目录中, 使用".ics"扩展名.
• C-c C-e i c 从 org-agenda-files 中的 Org 文件创建合并的 iCalendar 文件, 并将其写入 org-icalendar-combined-agenda-file 文件名.

头部参数以初始冒号后跟小写参数名指定.

头部参数可以通过多种方式设置; 如果发生重叠或冲突, Org 会优先考虑本地设置:

• 系统范围的头部参数 通过自定义变量 org-babel-default-header-args 或特定语言 LANG 的 org-babel-default-header-args:LANG 指定.
• 属性中的头部参数 可以使用"header-args"属性(参见第7章 [属性], 第16页)或特定语言 LANG 的"header-args:LANG"设置. 属性抽屉中设置的头部参数适用于子树级别及以下.
• 代码块中的头部参数 头部参数通常在代码块级别设置, 在"BEGIN_SRC"行上:

NAME: factorial
SRC haskell :results silent :exports code :var n=0
fac 0 = 1
fac n = n * fac (n - 1)
SRC

代码块头部参数可以使用"HEADER"关键字跨多行设置.

使用 C-c C-c 评估当前代码块并将结果插入 Org 文档. 默认情况下, 仅对"emacs-lisp"代码块启用求值, 但支持多种语言的代码块求值.

有关支持语言的完整列表, 参见手册. 以下是一个代码块及其结果的示例:

SRC emacs-lisp
  (+ 1 2 3 4)

#+END_SRC

以下语法用于通过"var"头部参数向代码块传递参数:

• :var NAME=ASSIGN

NAME 是绑定到代码块正文中的变量名. ASSIGN 是字面值, 如字符串, 数字, 表格引用, 列表, 字面示例, 另一个代码块(带或不带参数)或评估代码块的结果.

Org 如何处理代码块执行结果取决于多个头部参数的协同作用. 主要决定因素是"results"头部参数, 控制代码块结果的收集, 类型, 格式和处理:

• 收集方式: 可以选择"output"或"value"(默认).
• 类型: 可以选择"table", "list", "scalar"和"file". 如果未提供, Org 会尝试猜测.
• 格式: Org 如何处理结果. 可能的值包括"code", "drawer", "html", "latex", "link"和"raw".
• 处理方式: 如何插入格式化后的结果. 允许的值为"silent", "replace"(默认), "append"或"prepend".

输出到文件的代码块(例如图表, 图示和图片)可以接受":file FILENAME"头部参数, 在这种情况下, 结果保存到指定文件中, 并将文件的链接插入缓冲区.

可以导出代码块的代码, 代码块评估的结果, 代码和结果两者, 或都不导出. Org 默认对大多数语言导出代码.

Org 提供缓冲区内补全功能, 使用 M-TAB. 例如, 此命令会在头条开头补全 TODO 关键字, 在头条后补全标签.

要快速插入空的结构块, 例如 #+BEGIN_SRC … #+END_SRC, 或将现有文本包裹在这样的块中, 请使用:

• C-c C-, 提示输入块结构类型, 并在光标处插入块. 如果区域处于活动状态, 则将其包裹在块中.

Org 的默认带星号和无缩进的轮廓对于短文档可能显得过于杂乱. 对于书籍式长文档, 这种效果不明显. Org 提供了一种替代的星号和缩进方案, 如下表右侧所示. 它仅使用一个星号并将文本缩进与标题对齐:

▼ 顶级标题
*▽ 二级标题
*▽ 三级标题
    一些文本
*▽ 三级标题
    更多文本
▼ 另一个顶级标题

▼ 顶级标题
  二级标题
    三级标题
      一些文本
    三级标题
      更多文本
  另一个顶级标题

这种视图可以通过使用 Org Indent 模式(M-x org-indent-mode RET)动态实现, 为每行添加不可见的空格. 可以为所有文件启用 Org Indent 模式, 方法是自定义变量 org-startup-indented, 或为单个文件使用:

STARTUP: indent

如果希望缩进是硬空格字符, 使纯文本文件尽可能接近 Emacs 显示效果, Org 通过帮助缩进(使用 TAB)每个头条下的文本, 隐藏前导星号, 并仅使用 1, 3 等级别以获得每级两个字符的缩进来支持这一点. 要在文件中获得此支持, 请使用:

STARTUP: hidestars odd