这是最新版本 Org mode 的官方手册.

Org使用手册

本手册适用于Org版本9.4。

版权所有©2004-2020自由软件基金会

根据GNU自由文档许可证1.3版或自由软件基金会发布的任何更新版本的条款，允许复制、分发或修改本文档；没有固定章节，封面文本为“GNU手册”，封底文本如下(a)所示。该许可证的副本包含在标题为“GNU自由文档许可证”的部分中。

(a) FSF的封底正文是：“您有复制和修改本GNU手册的自由。”

— 详细的节点列表 —

介绍

文档结构

可见性循环

表格

电子表格

超链接

TODO项

TODO扩展

进度日志记录

标签

属性和列

列视图

列定义

日期和时间

创建时间戳

截止日期和日程安排

工作时间计时

转接和归档

归档

捕获和附件

捕获

捕获模板

附件

议程视图

内置议程视图

演示文稿和排序

自定义议程视图

富文本标记

LaTeX嵌入

导出

Beamer导出

HTML导出

LaTeX导出

OpenDocument文本导出

ODT导出中的数学格式设置

Texinfo导出

在外部缓冲区中导出

发布

配置

配置示例

使用源代码

杂项

净化视图

交互

协议

Org移动版

高度定制化

任意语法中的表格

1 简介

1.1概述

Org是Emacs的一个模式，它使用一种快速高效的纯文本标记语言，用来进行笔记管理、维护TODO列表以及项目规划。它也是一个创作系统，对文学式编程和可重复性研究提供独特的支持。

Org基于大纲模式实现，这样就可以保持大型文件的内容结构良好。可见性循环和结构编辑有助于与树配合使用。使用内置的表格编辑器可以轻松创建表格。类似纯文本URL的链接连接到网站，电子邮件，Usenet消息，BBDB记录以及与项目相关的任何文件。

Org围绕笔记文件开发组织任务，这些笔记文件以纯文本形式包含有关项目的列表或信息。项目计划和任务管理利用了元数据，这些元数据是作为大纲节点一部分存在。基于这些数据，可以在查询中提取特定记录并创建动态的 议程视图，该视图还集成了Emacs日历和日记。Org可以用来实践多种不同的项目规划方案，例如David Allen的GTD系统。

Org文件可以用作单一源创作系统，并可以导出多种不同的格式，例如HTML、LaTeX，Open Document和Markdown。新的导出后端可以从现有的后端衍生出来，也可以从头开始定义。

Org文件可以包含源代码块，这使Org特别适合编写带有代码示例的技术文档。Org源代码块功能齐全，可以对其进行求值，并将结果捕获到文件中。这使得创建单文件可重复性研究手册成为了可能。

Org使简单的事情变得更简单。初次启动时，它应该看起来像一个简单易用的大纲工具。虽然并不要求复杂性，但是在需要时有大量的功能可以使用。Org是一个工具箱。实际上，许多用户只运行Org的一部分功能（非常个人化），并且知道在需要时还会有更多功能。

所有这些都是通过严格的纯文本文件实现的，这是可移植且面向未来的文件格式。Org运行在Emacs之上。Emacs是最广泛的移植程序之一，因此Org模式可以在每个主流平台上使用。

有一个用于Org的网站，该网站提供指向Org最新版本的链接，以及其他信息，常见问题解答（FAQ），教程链接等。此页面位于https://orgmode.org.

本手册的早期版本（7.3）可作为平装书从Network Theory Ltd获得。.

1.2安装

Org包含在GNU Emacs的所有最新发行版中，因此您可能不需要安装它。大多数用户只需要激活Org并开始探索其众多功能。

如果出于某种原因要在此预打包版本之上安装Org，可以通过以下三种方法进行：

• 使用Emacs打包系统安装；
• 下载Org的档案文件，
• 或者使用Org的git仓库。

我们强烈建议坚持只使用一种安装方法。

使用Emacs打包系统

最新的Emacs发行版包括一个打包系统，可让您方便的安装Elisp库。输入命令 M-x list-packages，你便可以从“软件包清单”中安装Org。详情查阅(emacs)软件包清单。

重要提示:你需要在未访问' .org '文件的会话（即未加载Org内置函数的会话）中执行此操作。否则，自动加载的Org函数会破坏安装操作。

如果你想使用Org的软件包仓库，请访问 Org ELPA page。

将Org作为档案下载

你可以从 Org官网下载Org的最新版本。在这种情况下，请确保在Emacs初始化文件中正确设置了加载路径:

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

下载的档案包含Emacs中没有的贡献库。如果你使用它们，添加‘contrib/’目录到你的加载路径中::

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

（可选）您可以编译文件和/或将它们安装在系统中。运行‘make help’来列出编译和安装选项。

使用Org的git仓库

你可以克隆Org的仓库到本地，然后安装Org，像这样:

$ cd ~/src/
$ git clone https://code.orgmode.org/bzg/org-mode.git
$ cd org-mode/
$ make autoloads

请注意，在这种情况下，必须使用'make autoloads'：它在'org-version.el'中定义Org的版本，并在'org-loaddefs .el'中定义Org的自动加载。

请记住按照上述方法添加正确的加载路径。

你也可以使用'make'进行编译，使用'make doc'生成文档，使用'make config'创建本地配置，使用'make install'安装Org。请运行‘make help’ 来获得编译/安装选项的列表。

关于Org的构建系统的详细说明，请查看Worg上面的Org构建系统页面。

1.3激活

Org模式缓冲区需要打开字体锁定，这是Emacs中的默认设置s¹。

Org模式与某些其他Elisp软件包之间存在兼容性问题（请参见冲突）。请花一些时间检查这个列表。

为了获得更好的体验，有三个Org命令应该是在Emacs的任何地方都可以访问的，而不仅仅是在Org缓冲区内，它们是org-store-link， org-capture和org-agenda。为此，你需要把它们绑定到全局可用的按键上，例如为用户保留的按键（请参阅 (elisp)键绑定约定）。以下是建议的绑定，请根据自己的喜好修改按键。

(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模式，请在文件的第一行增加以下内容：

我的项目    -*- mode: org; -*-

不管文件名是什么，都会为该缓冲区选择组织模式。另请查阅org-insert-mode-line-in-empty-file变量。

如果某区域为活跃状态，则Org中的许多命令都可以在该区域上使用。要使用此功能，您需要打开“瞬变标记”模式，这是默认设置。如果您不喜欢它，可以通过使用鼠标选择一个区域或在光标之前按两次C-SPC来创建活动区域。

1.4反馈

如果你发现了Org的的问题，或者你有对Org的疑问、评价或者好的想法，请发送邮件到Org邮件列表emacs-orgmode@gnu.org。你可以从这个页面订阅此列表。如果你不是一个邮件组的成员，经过主持人的批准后，你的邮件将被传递到该列表。². 在此邮件列表上发送消息时，我们请您阅读并遵守GNU善意沟通准则

对于bug提交，请先尝试使用最新的Org版本重现该错误——如果您运行的是过时的版本，则很可能已经在后续版本修复了该bug。如果bug在新版本依旧存在，请准备一份报告，并提供尽可能多的信息，包括Emacs(M-x emacs-version)和Org (M-x org-version)的版本信息，以及在Emacs init文件中关于Org的相关配置。最简单的方式就是使用命令

M-x org-submit-bug-report <RET>

它将所有这些信息放入Emacs邮件缓冲区中，因此你只需要添加你的描述即可。如果您不是从Emacs内部发送电子邮件，请复制内容并将其粘贴到您的电子邮件程序中。

有时您可能会由于Emacs或Org模式设置错误而遇到问题。在报告错误之前，使用最少的自定义启动Emacs并重现问题非常有帮助。这样做通常可以帮助您确定问题出在您的自定义设置还是Org模式本身。您可以使用类似以下示例的命令启动典型的最小会话。

$ emacs -Q -l /path/to/minimal-org.el

但是，如果您使用的是随Emacs一起分发的Org模式，则无需进行最小设置。在这种情况下，以'emacs -Q'启动Emacs就足够了。'minimal-org.el”设置文件可以具有如下所示的内容。

;;; 最少的配置加载最新的'org-mode'

;; 激活调试
(setq debug-on-error t
      debug-on-signal nil
      debug-on-quit nil)

;; 添加最新的Org模式到加载路径中。
(add-to-list 'load-path (expand-file-name "/path/to/org-mode/lisp"))
(add-to-list 'load-path (expand-file-name "/path/to/org-mode/contrib/lisp" t))

如果发生错误，“回溯”可能会非常有用-请参阅下文，了解如何创建。通常，一个小的示例文件会有所帮助，同时提供以下方面的清晰信息：

1. 你到底是做什么的？
2. 你做了些什么？
3. 发生了什么？

感谢您帮助改进此程序。

如何创建有用的回溯

如果与Org一起使用时出现错误，并显示一条您不理解的消息，则可能是您遇到了错误。最好的报告方法是，除了上面提到的以外，还提供回溯。这是内置调试器提供的有关错误发生的位置和方式的信息。这是产生有用的回溯的方法：

1. 重新加载所有Org模式Lisp文件的未编译版本。如果回溯跟踪是用未编译的代码生成的，则包含更多信息。为此，请使用

   C-u M-x org-reload <RET>
   

   或者，从菜单中进入：Org→刷新/重新加载→重新加载未编译的Org。

2. 然后，激活调试器：

   M-x toggle-debug-on-error <RET>
   

   或者，从菜单进入：选项→错误时进入调试器。

3. 做你必须做的一切以解决错误。不要忘记记录你采取的步骤。
4. 遇到错误时，屏幕上会显示一个*Backtrace*缓冲区。将该缓冲区保存到文件中（例如，使用C-x C-w），并将其附加到错误报告中。

1.5本指南中的排版约定

TODO关键字, 标签, 属性等。

Org使用各种语法元素：TODO关键字，标签，属性名称，关键字，块等。在本指南中，我们使用以下约定：

‘TODO’

‘WAITING’

即使是用户定义的，也要使用大写字母写TODO关键字。

‘boss’

‘ARCHIVE’

标签要区分大小写。用户定义的标签以小写形式编写； 具有特殊含义的内置标签应按应在文档中出现的方式书写，通常使用全大写。

‘Release’

‘PRIORITY’

用户定义的属性以首字母大写形式； 具有特殊含义的内置属性使用全大写字母书写。

‘TITLE’

‘BEGIN’ … ‘END’

关键字和块以大写形式编写，以增强其可读性，但是您可以在Org文件中使用小写形式。

按键绑定和命令

该手册列出了用于访问一个功能的按键和相应的命令。Org模式通常根据上下文将相同的键用于不同的功能。绑定到此类键的命令具有通用名称，例如org-metaright。在手册中，我们将尽可能提供内部函数调用的通用命令例如，在文档结构一章中，将列出M-RIGHT来调用org-do-demote，在表格章节时，org-table-move-column-right 命令会被列出来。

2 文档结构

首先，Org是一个大纲。大纲可以使使文档按层次进行组织结构，至少对我而言，这是笔记和思想的最佳表示形式。这种结构的概述是通过折叠来实现的，即隐藏文档的大部分以仅显示一般文档结构和当前正在处理的部分。Org通过将显示和隐藏的功能压缩到org-cycle这个单一的命令上来简化大纲的使用，它的按键绑定为TAB。

2.1标题

标题定义了大纲树的结构。Org标题从左边距³开始，后面跟着一个或者多个星号和空格。例如：

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

org-footnote-section中定义的名称是保留的。不要将其作为你自己的笔记的标题。

有些人觉得星号太多了，他们更喜欢在大纲中使用空格后跟着一个星号作为标题的开头。这可以使用Org缩进辅模式来实现。有关详细信息，请参阅干净的视图。

标题是没有编号的。但是，你可能希望对其中的一些或全部进行动态编号。请参阅动态标题编号。

子树末尾之后的空行被认为是子树的一部分，并且在子树折叠时被隐藏。但是，如果您保留至少两个空行，则在折叠子树后仍有一个空行可见，以便构建折叠视图的结构。要修改此行为，请参阅变量org-cycle-separator-lines。

2.2可见性循环

2.2.1全局循环和局部循环

大纲可以让隐藏缓冲区中的部分文本成为可能。Org只使用两个命令来更改缓冲区中的可见性，分别是按键绑定TAB和S-TAB。

TAB (org-cycle)

子树循环:让子树在多个状态直接循环

,-> 折叠状态 -> 直属子元素 -> 完整子树 --.
'-----------------------------------'

必须位于标题上才能正常工作⁴。

S-TAB (org-global-cycle)

C-u TAB

全局循环：整个缓冲区在多个状态之间循环

,->  概述 -> 内容 -> 全部显示 --.
'--------------------------------------'

当S-TAB使用数字前缀参数N调用时，仅查看直到N级别的标题的内容。

请注意，在表格中(请参阅表格)，S-TAB会跳转到上一个字段。

您可以使用TAB运行全局循环，前提是光标位于缓冲区的最开始处，而不是在标题上，并且org-cycle-global-at-bob设置为非nil值。

C-u C-u TAB (org-set-startup-visibility)

切换回缓冲区的启动可见性(请参阅初始可见性)。

C-u C-u C-u TAB (outline-show-all)

全部展示，包括抽屉。

C-c C-r (org-reveal)

显示光标周围的上下文，显示当前条目、下面的标题和上面的层次结构。对于在由稀疏树命令(请参阅稀疏树)或议程命令(请参阅议程命令)暴露出来的位置操作时，它非常有用。使用前缀参数，在每个级别上显示所有同级标题。使用双前缀参数，还可以显示父级的整个子树。

C-c C-k (outline-show-branches)

显示子树的所有标题，但不显示子树的主体。

C-c TAB (outline-show-children)

显示该子树的所有直接子级。使用数字前缀参数N，将所有子级向下显示到N。

C-c C-x b (org-tree-to-indirect-buffer)

在间接缓冲区中显示当前子树⁵。使用数字前缀参数N，转到级别N，然后获取该树。如果N为负，则上升到该级别。使用C-u前缀，请勿删除以前使用的间接缓冲区。

C-c C-x v (org-copy-visible)

将区域中的可见性文本复制到剪切板中。

2.2.2初始可见性

当Emacs首次访问Org文件时，全局状态设置为showeverything，即所有文件内容均可见⁶。这可以通过变量org-start-folded进行配置，也可以通过在缓冲区中的任意位置添加以下行之一来针对每个文件进行配置：

#+STARTUP: overview
#+STARTUP: content
#+STARTUP: showall
#+STARTUP: showeverything

此外，任何具有“VISIBILITY”属性的条目(请参阅属性和列)都会相应地调整其可见性。此属性允许的值为“folded”、“children”、“content”和“all”。

C-u C-u TAB (org-set-startup-visibility)

切换回缓冲区的启动可见性，即，各个条目中的启动选项和“VISIBILITY”属性所要求的任何内容。

2.2.3捕捉不可见的编辑

有时，您可能会无意中编辑缓冲区的不可见部分，并对已编辑的内容以及如何撤消错误感到困惑。将org-catch-insible-edits设置为非nil有助于防止出现这种情况。请参阅此选项的文档字符串，了解组织应如何捕获不可见的编辑并对其进行处理。

2.3移动

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

C-c C-n (org-next-visible-heading)

下一个标题。

C-c C-p (org-previous-visible-heading)

上一个标题。

C-c C-f (org-forward-heading-same-level)

下一个同级标题。

C-c C-b (org-backward-heading-same-level)

上一个同级标题。

C-c C-u (outline-up-heading)

跳回到更高级别的标题

C-c C-j (org-goto)

在不更改当前大纲可见性的情况下跳到其他位置。显示在临时缓冲区中的文档结构，您可以在其中使用以下键查找目标：

TAB	可见性循环。
DOWN / UP	下一个/上一个可见标题。
RET	选择此位置。
/	执行稀疏树搜索

如果关闭org-goto-auto-isearch，则以下键起作用

n / p	下一个/上一个可见标题。
f / b	下一个/上一个同级标题。
u	往上一级。
0 … 9	数字参数。
q	退出。

另请参阅变量org-goto-interface。

2.4结构编辑

M-RET (org-meta-return)

插入新标题、项或行。

如果在行的开始处使用该命令，并且在光标处有标题或普通列表项(请参阅普通列表)，则在当前行之前创建新的标题/项。在常规文本行的开头使用时，会将该行转换为标题。

当在行中间使用此命令时，该行将被拆分，该行的剩余部分将成为新项或标题。如果不想拆分该行，请自定义org-M-ret-May-plit-line。

无条件地调用带有C-u前缀的命令会在当前子树的末尾插入一个新标题，从而保留其内容。使用双C-u C-u前缀，将在父子树的末尾创建新标题。

C-RET (org-insert-heading-respect-content)

在当前子树的末尾插入新标题。

M-S-RET (org-insert-todo-heading)

插入与当前标题级别相同的新TODO条目。另请参阅变量org-treat-insert-todo-heading-as-state-change.

C-S-RET (org-insert-todo-heading-respect-content)

插入与当前标题级别相同的新TODO条目。与C-ret类似，新标题插入到当前子树之后。

TAB (org-cycle)

在还没有文本的新条目中，第一次TAB将该条目降级为前一个条目的子项。下一次TAB使其成为父级，依此类推，一直到顶层。再来一次Tab，您将返回到初始级别。

M-LEFT (org-do-promote)

M-RIGHT (org-do-demote)

将当前标题提升或降低一个级别。

当存在活动区域时-即，当瞬变标记模式处于活动状态时-该区域中的所有标题都会执行升级和降级。要选择标题区域，最好将光标和标记同时放置在行的开头，标记在第一个标题的开头，然后指向要更改的最后一个标题之后的行。

M-S-LEFT (org-promote-subtree)

将当前子树提升一个级别。

M-S-RIGHT (org-demote-subtree)

将当前子树降低一个级别。

M-UP (org-move-subtree-up)

上移子树，即与同级的上一个子树互换。

M-DOWN (org-move-subtree-down)

下移子树，即与同级的下一个子树互换。

C-c @ (org-mark-subtree)

在光标位置标记该子树。重复执行标记命令将会标记的与该子树相同级别的后续子树。

C-c C-x C-w (org-cut-subtree)

删除子树，即将其从缓冲区中移除，但保存在剪切板中。使用数字前缀参数N，删除N个连续的子树。

C-c C-x M-w (org-copy-subtree)

将子树复制到剪切板。使用数字前缀参数N复制N个连续子树。

C-c C-x C-y (org-paste-subtree)

从剪切板上粘贴一棵子树。这会修改子树的级别，以确保树很好地适应在所粘贴的位置。粘贴时的级别也可以使用数字前缀参数指定，或者通过粘贴标题标记(如“****”)来指定。

C-y (org-yank)

根据变量org-yank-adjusted-subtree和org-yank-folded-subtree的不同，Org的内部yank命令使用与C-c-x C-y相同的命令巧妙地粘贴折叠的子树。使用默认设置时，不会进行任何级别调整，但会折叠粘贴的树，除非这样做会吞噬以前可见的文本。此命令的任何前缀参数都强制执行正常的粘贴操作，并传递前缀。强制执行一个普通粘贴的一个好方法是C-u C-y。如果在在一次粘贴之后使用yank-pop，它会简单的粘贴之前的内容，不会调整和折叠。

C-c C-x c (org-clone-subtree-with-time-shift)

通过制作多个同级副本来克隆子树。系统会提示您输入要制作的副本数量，您还可以指定条目中的任何时间戳是否应该移位。例如，这对于创建与要准备的一系列讲座相关的多个任务非常有用。有关更多详细信息，请参阅命令org-clone-subtree-with-time-Shift的文档说明。

C-c C-w (org-refile)

将条目或区域转接到其他位置。请参阅转接和复制。

C-c ^ (org-sort)

对同级条目进行排序。当存在活动区域时，将对该区域中的所有条目进行排序。否则，对当前标题的子项进行排序。该命令提示您输入排序方法，该方法可以按字母顺序、数字顺序，也可以首次有效时间戳、创建时间、计划时间、截止日期时间排序，同样也可以按优先级、按TODO关键字（按照关键字在设置中定义的顺序）或按属性的值进行排序。反向排序也是可能的。您还可以提供自己的函数来提取排序关键字。使用C-u前缀，排序区分大小写。

C-x n s (org-narrow-to-subtree)

将缓冲区聚焦到当前子树

C-x n b (org-narrow-to-block)

将缓冲区聚焦到当前块。

C-x n w (widen)

扩大缓冲区以取消聚焦。

C-c * (org-toggle-heading)

将普通行或普通列表项转换为标题-使其在其所在位置成为副标题。还可以通过去掉星号来将标题转换为正常行。如果存在活动区域，会将该区域中的所有行都变成标题。如果区域中的第一行是列表项，则仅将列表项行变为标题。最后，如果第一行是标题，则从该区域的所有标题中删除星号。

请注意，当光标位于表格中时(请参见表格)，Meta修饰标键具有不同的功能。

2.5稀疏树

An important feature of Org mode is the ability to construct sparse trees for selected information in an outline tree, so that the entire document is folded as much as possible, but the selected information is made visible along with the headline structure above it⁷. Just try it out and you will see immediately how it works.

Org mode contains several commands creating such trees, all these commands can be accessed through a dispatcher:

C-c / (org-sparse-tree)

This prompts for an extra key to select a sparse-tree creating command.

C-c / r or C-c / / (org-occur)

Prompts for a regexp and shows a sparse tree with all matches. If the match is in a headline, the headline is made visible. If the match is in the body of an entry, headline and body are made visible. In order to provide minimal context, also the full hierarchy of headlines above the match is shown, as well as the headline following the match. Each match is also highlighted; the highlights disappear when the buffer is changed by an editing command, or by pressing C-c C-c⁸. When called with a C-u prefix argument, previous highlights are kept, so several calls to this command can be stacked.

M-g n or M-g M-n (next-error)

Jump to the next sparse tree match in this buffer.

M-g p or M-g M-p (previous-error)

Jump to the previous sparse tree match in this buffer.

For frequently used sparse trees of specific search strings, you can use the variable org-agenda-custom-commands to define fast keyboard access to specific sparse trees. These commands will then be accessible through the agenda dispatcher (see Agenda Dispatcher). 例如：

(setq org-agenda-custom-commands
      '(("f" occur-tree "FIXME")))

defines the key f as a shortcut for creating a sparse tree matching the string ‘FIXME’.

The other sparse tree commands select headings based on TODO keywords, tags, or properties and are discussed later in this manual.

To print a sparse tree, you can use the Emacs command ps-print-buffer-with-faces which does not print invisible parts of the document. Or you can use the command C-c C-e C-v to export only the visible part of the document and print the resulting file.

2.6普通列表

Within an entry of the outline tree, hand-formatted lists can provide additional structure. They also provide a way to create lists of checkboxes (see Checkboxes). Org supports editing such lists, and every exporter (see Exporting) can parse and format them.

Org knows ordered lists, unordered lists, and description lists.

• Unordered list items start with ‘-’, ‘+’, or ‘*’⁹ as bullets.
• Ordered list items start with a numeral followed by either a period or a right parenthesis¹⁰, such as ‘1.’ or ‘1)’¹¹ If you want a list to start with a different value—e.g., 20—start the text of the item with ‘[@20]’¹². Those constructs can be used in any item of the list in order to enforce a particular numbering.
• Description list items are unordered list items, and contain the separator ‘::’ to distinguish the description term from the description.

Items belonging to the same list must have the same indentation on the first line. In particular, if an ordered list reaches number ‘10.’, then the 2-digit numbers must be written left-aligned with the other numbers in the list. An item ends before the next line that is less or equally indented than its bullet/number.

A list ends whenever every item has ended, which means before any line less or equally indented than items at top level. It also ends before two blank lines. In that case, all items are closed. Here is an example:

* Lord of the Rings
My favorite scenes are (in this order)
1. The attack of the Rohirrim
2. Eowyn's fight with the witch king
   + this was already my favorite scene in the book
   + I really like Miranda Otto.
3. Peter Jackson being shot by Legolas
   - on DVD only
   He makes a really funny face when it happens.
But in the end, no individual scenes matter but the film as a whole.
Important actors in this film are:
- Elijah Wood :: He plays Frodo
- Sean Astin :: He plays Sam, Frodo's friend.  I still remember him
     very well from his role as Mikey Walsh in /The Goonies/.

Org supports these lists by tuning filling and wrapping commands to deal with them correctly, and by exporting them properly (see Exporting). Since indentation is what governs the structure of these lists, many structural constructs like ‘#+BEGIN_’ blocks can be indented to signal that they belong to a particular item.

If you find that using a different bullet for a sub-list—than that used for the current list-level—improves readability, customize the variable org-list-demote-modify-bullet. To get a greater difference of indentation between items and theirs sub-items, customize org-list-indent-offset.

The following commands act on items when point is in the first line of an item—the line with the bullet or number. Some of them imply the application of automatic rules to keep list structure intact. If some of these actions get in your way, configure org-list-automatic-rules to disable them individually.

TAB (org-cycle)

Items can be folded just like headline levels. Normally this works only if point is on a plain list item. For more details, see the variable org-cycle-include-plain-lists. If this variable is set to integrate, plain list items are treated like low-level headlines. The level of an item is then given by the indentation of the bullet/number. Items are always subordinate to real headlines, however; the hierarchies remain completely separated. In a new item with no text yet, the first TAB demotes the item to become a child of the previous one. Subsequent TABs move the item to meaningful levels in the list and eventually get it back to its initial position.

M-RET (org-insert-heading)

Insert new item at current level. With a prefix argument, force a new heading (see Structure Editing). If this command is used in the middle of an item, that item is split in two, and the second part becomes the new item¹³. If this command is executed before item’s body, the new item is created before the current one.

M-S-RET

Insert a new item with a checkbox (see Checkboxes).

S-UP

S-DOWN

Jump to the previous/next item in the current list, but only if org-support-shift-select is off¹⁴. If not, you can still use paragraph jumping commands like C-UP and C-DOWN to quite similar effect.

M-UP

M-DOWN

Move the item including subitems up/down¹⁵, i.e., swap with previous/next item of same indentation. If the list is ordered, renumbering is automatic.

M-LEFT

M-RIGHT

Decrease/increase the indentation of an item, leaving children alone.

M-S-LEFT

M-S-RIGHT

Decrease/increase the indentation of the item, including subitems. Initially, the item tree is selected based on current indentation. When these commands are executed several times in direct succession, the initially selected region is used, even if the new indentation would imply a different hierarchy. To use the new hierarchy, break the command chain by moving point.

As a special case, using this command on the very first item of a list moves the whole list. This behavior can be disabled by configuring org-list-automatic-rules. The global indentation of a list has no influence on the text after the list.

C-c C-c

If there is a checkbox (see Checkboxes) in the item line, toggle the state of the checkbox. In any case, verify bullets and indentation consistency in the whole list.

C-c -

Cycle the entire list level through the different itemize/enumerate bullets (‘-’, ‘+’, ‘*’, ‘1.’, ‘1)’) or a subset of them, depending on org-plain-list-ordered-item-terminator, the type of list, and its indentation. With a numeric prefix argument N, select the Nth bullet from this list. If there is an active region when calling this, all lines are converted to list items. With a prefix argument, the selected text is changed into a single item. If the first line already was a list item, any item marker is removed from the list. Finally, even without an active region, a normal line is converted into a list item.

C-c *

Turn a plain list item into a headline—so that it becomes a subheading at its location. See Structure Editing, for a detailed explanation.

C-c C-*

Turn the whole plain list into a subtree of the current heading. Checkboxes (see Checkboxes) become ‘TODO’, respectively ‘DONE’, keywords when unchecked, respectively checked.

S-LEFT

S-RIGHT

This command also cycles bullet styles when point is in on the bullet or anywhere in an item line, details depending on org-support-shift-select.

C-c ^

Sort the plain list. Prompt for the sorting method: numerically, alphabetically, by time, or by custom function.

2.7抽屉

Sometimes you want to keep information associated with an entry, but you normally do not want to see it. For this, Org mode has drawers. They can contain anything but a headline and another drawer. Drawers look like this:

** This is a headline
Still outside the drawer
:DRAWERNAME:
This is inside the drawer.
:END:
After the drawer.

You can interactively insert a drawer at point by calling org-insert-drawer, which is bound to C-c C-x d. With an active region, this command puts the region inside the drawer. With a prefix argument, this command calls org-insert-property-drawer, which creates a ‘PROPERTIES’ drawer right below the current headline. Org mode uses this special drawer for storing properties (see Properties and Columns). You cannot use it for anything else.

Completion over drawer keywords is also possible using M-TAB¹⁶.

Visibility cycling (see Visibility Cycling) on the headline hides and shows the entry, but keep the drawer collapsed to a single line. In order to look inside the drawer, you need to move point to the drawer line and press TAB there.

You can also arrange for state change notes (see Tracking TODO state changes) and clock times (see Clocking Work Time) to be stored in a ‘LOGBOOK’ drawer. If you want to store a quick note there, in a similar way to state changes, use

C-c C-z

Add a time-stamped note to the ‘LOGBOOK’ drawer.

2.8块

Org mode uses ‘#+BEGIN’ … ‘#+END’ blocks for various purposes from including source code examples (see Literal Examples) to capturing time logging information (see Clocking Work Time). These blocks can be folded and unfolded by pressing TAB in the ‘#+BEGIN’ line. You can also get all blocks folded at startup by configuring the variable org-hide-block-startup or on a per-file basis by using

#+STARTUP: hideblocks
#+STARTUP: nohideblocks

3 表格

Org comes with a fast and intuitive table editor. Spreadsheet-like calculations are supported using the Emacs Calc package (see (calc)GNU Emacs Calculator Manual).

3.1内置表格编辑器

Org makes it easy to format tables in plain ASCII. Any line with ‘|’ as the first non-whitespace character is considered part of a table. ‘|’ is also the column separator¹⁷. Moreover, a line starting with ‘|-’ is a horizontal rule. It separates rows explicitly. Rows before the first horizontal rule are header lines. A table might look like this:

| Name  | Phone | Age |
|-------+-------+-----|
| Peter |  1234 |  17 |
| Anna  |  4321 |  25 |

A table is re-aligned automatically each time you press TAB, RET or C-c C-c inside the table. TAB also moves to the next field—RET to the next row—and creates new table rows at the end of the table or before horizontal lines. The indentation of the table is set by the first line. Horizontal rules are automatically expanded on every re-align to span the whole table width. So, to create the above table, you would only type

|Name|Phone|Age|
|-

and then press TAB to align the table and start filling in fields. Even faster would be to type ‘|Name|Phone|Age’ followed by C-c RET.

When typing text into a field, Org treats DEL, Backspace, and all character keys in a special way, so that inserting and deleting avoids shifting other fields. Also, when typing immediately after point was moved into a new field with TAB, S-TAB or RET, the field is automatically made blank. If this behavior is too unpredictable for you, configure the option org-table-auto-blank-field.

Creation and conversion

C-c | (org-table-create-or-convert-from-region)

Convert the active region to table. If every line contains at least one TAB character, the function assumes that the material is tab separated. If every line contains a comma, comma-separated values (CSV) are assumed. If not, lines are split at whitespace into fields. You can use a prefix argument to force a specific separator: C-u forces CSV, C-u C-u forces TAB, C-u C-u C-u prompts for a regular expression to match the separator, and a numeric argument N indicates that at least N consecutive spaces, or alternatively a TAB will be the separator.

If there is no active region, this command creates an empty Org table. But it is easier just to start typing, like | N a m e | P h o n e | A g e RET | - TAB.

Re-aligning and field motion

C-c C-c (org-table-align)

Re-align the table without moving point.

TAB (org-table-next-field)

Re-align the table, move to the next field. Creates a new row if necessary.

C-c SPC (org-table-blank-field)

Blank the field at point.

S-TAB (org-table-previous-field)

Re-align, move to previous field.

RET (org-table-next-row)

Re-align the table and move down to next row. Creates a new row if necessary. At the beginning or end of a line, RET still inserts a new line, so it can be used to split a table.

M-a (org-table-beginning-of-field)

Move to beginning of the current table field, or on to the previous field.

M-e (org-table-end-of-field)

Move to end of the current table field, or on to the next field.

Column and row editing

M-LEFT (org-table-move-column-left)

Move the current column left.

M-RIGHT (org-table-move-column-right)

Move the current column right.

M-S-LEFT (org-table-delete-column)

Kill the current column.

M-S-RIGHT (org-table-insert-column)

Insert a new column at point position. Move the recent column and all cells to the right of this column to the right.

M-UP (org-table-move-row-up)

Move the current row up.

M-DOWN (org-table-move-row-down)

Move the current row down.

M-S-UP (org-table-kill-row)

Kill the current row or horizontal line.

S-UP (org-table-move-cell-up)

Move cell up by swapping with adjacent cell.

S-DOWN (org-table-move-cell-down)

Move cell down by swapping with adjacent cell.

S-LEFT (org-table-move-cell-left)

Move cell left by swapping with adjacent cell.

S-RIGHT (org-table-move-cell-right)

Move cell right by swapping with adjacent cell.

M-S-DOWN (org-table-insert-row)

Insert a new row above the current row. With a prefix argument, the line is created below the current one.

C-c - (org-table-insert-hline)

Insert a horizontal line below current row. With a prefix argument, the line is created above the current line.

C-c RET (org-table-hline-and-move)

Insert a horizontal line below current row, and move point into the row below that line.

C-c ^ (org-table-sort-lines)

Sort the table lines in the region. The position of point indicates the column to be used for sorting, and the range of lines is the range between the nearest horizontal separator lines, or the entire table. If point is before the first column, you are prompted for the sorting column. If there is an active region, the mark specifies the first line and the sorting column, while point should be in the last line to be included into the sorting. The command prompts for the sorting type, alphabetically, numerically, or by time. You can sort in normal or reverse order. You can also supply your own key extraction and comparison functions. When called with a prefix argument, alphabetic sorting is case-sensitive.

Regions

C-c C-x M-w (org-table-copy-region)

Copy a rectangular region from a table to a special clipboard. Point and mark determine edge fields of the rectangle. If there is no active region, copy just the current field. The process ignores horizontal separator lines.

C-c C-x C-w (org-table-cut-region)

Copy a rectangular region from a table to a special clipboard, and blank all fields in the rectangle. So this is the “cut” operation.

C-c C-x C-y (org-table-paste-rectangle)

Paste a rectangular region into a table. The upper left corner ends up in the current field. All involved fields are overwritten. If the rectangle does not fit into the present table, the table is enlarged as needed. The process ignores horizontal separator lines.

M-RET (org-table-wrap-region)

Split the current field at point position and move the rest to the line below. If there is an active region, and both point and mark are in the same column, the text in the column is wrapped to minimum width for the given number of lines. A numeric prefix argument may be used to change the number of desired lines. If there is no region, but you specify a prefix argument, the current field is made blank, and the content is appended to the field above.

Calculations

C-c + (org-table-sum)

Sum the numbers in the current column, or in the rectangle defined by the active region. The result is shown in the echo area and can be inserted with C-y.

S-RET (org-table-copy-down)

When current field is empty, copy from first non-empty field above. When not empty, copy current field down to next row and move point along with it.

Depending on the variable org-table-copy-increment, integer and time stamp field values, and fields prefixed or suffixed with a whole number, can be incremented during copy. Also, a 0 prefix argument temporarily disables the increment.

This key is also used by shift-selection and related modes (see Conflicts).

杂项

C-c ` (org-table-edit-field)

Edit the current field in a separate window. This is useful for fields that are not fully visible (see Column Width and Alignment). When called with a C-u prefix, just make the full field visible, so that it can be edited in place. When called with two C-u prefixes, make the editor window follow point through the table and always show the current field. The follow mode exits automatically when point leaves the table, or when you repeat this command with C-u C-u C-c `.

M-x org-table-import

Import a file as a table. The table should be TAB or whitespace separated. Use, for example, to import a spreadsheet table or data from a database, because these programs generally can write TAB-separated text files. This command works by inserting the file into the buffer and then converting the region to a table. Any prefix argument is passed on to the converter, which uses it to determine the separator.

C-c | (org-table-create-or-convert-from-region)

Tables can also be imported by pasting tabular text into the Org buffer, selecting the pasted text with C-x C-x and then using the C-c | command (see Creation and conversion).

M-x org-table-export

Export the table, by default as a TAB-separated file. Use for data exchange with, for example, spreadsheet or database programs. The format used to export the file can be configured in the variable org-table-export-default-format. You may also use properties ‘TABLE_EXPORT_FILE’ and ‘TABLE_EXPORT_FORMAT’ to specify the file name and the format for table export in a subtree. Org supports quite general formats for exported tables. The exporter format is the same as the format used by Orgtbl radio tables, see Translator functions, for a detailed description.

M-x org-table-header-line-mode

Turn on the display of the first data row of the table at point in the window header line when this first row is not visible anymore in the buffer. You can activate this minor mode by default by setting the option org-table-header-line-p to t.

3.2列宽和对齐方式

The width of columns is automatically determined by the table editor. The alignment of a column is determined automatically from the fraction of number-like versus non-number fields in the column.

Editing a field may modify alignment of the table. Moving a contiguous row or column—i.e., using TAB or RET—automatically re-aligns it. If you want to disable this behavior, set org-table-automatic-realign to nil. In any case, you can always align manually a table:

C-c C-c (org-table-align)

Align the current table.

Setting the option org-startup-align-all-tables re-aligns all tables in a file upon visiting it. You can also set this option on a per-file basis with:

#+STARTUP: align
#+STARTUP: noalign

Sometimes a single field or a few fields need to carry more text, leading to inconveniently wide columns. Maybe you want to hide away several columns or display them with a fixed width, regardless of content, as shown in the following example.

|---+---------------------+--------|           |---+-------…+…|
|   | <6>                 |        |           |   | <6>   …|…|
| 1 | one                 | some   |   ----\   | 1 | one   …|…|
| 2 | two                 | boring |   ----/   | 2 | two   …|…|
| 3 | This is a long text | column |           | 3 | This i…|…|
|---+---------------------+--------|           |---+-------…+…|

To set the width of a column, one field anywhere in the column may contain just the string ‘<N>’ where N specifies the width as a number of characters. You control displayed width of columns with the following tools:

C-c TAB (org-table-toggle-column-width)

Shrink or expand current column.

If a width cookie specifies a width W for the column, shrinking it displays the first W visible characters only. Otherwise, the column is shrunk to a single character.

When called before the first column or after the last one, ask for a list of column ranges to operate on.

C-u C-c TAB (org-table-shrink)

Shrink all columns with a column width. Expand the others.

C-u C-u C-c TAB (org-table-expand)

Expand all columns.

To see the full text of a shrunk field, hold the mouse over it: a tool-tip window then shows the full contents of the field. Alternatively, C-h . (display-local-help) reveals them, too. For convenience, any change near the shrunk part of a column expands it.

Setting the option org-startup-shrink-all-tables shrinks all columns containing a width cookie in a file the moment it is visited. You can also set this option on a per-file basis with:

#+STARTUP: shrink

If you would like to overrule the automatic alignment of number-rich columns to the right and of string-rich columns to the left, you can use ‘<r>’, ‘<c>’ or ‘<l>’ in a similar fashion. You may also combine alignment and field width like this: ‘<r10>’.

Lines which only contain these formatting cookies are removed automatically upon exporting the document.

3.3列组

When Org exports tables, it does so by default without vertical lines because that is visually more satisfying in general. Occasionally however, vertical lines can be useful to structure a table into groups of columns, much like horizontal lines can do for groups of rows. In order to specify column groups, you can use a special row where the first field contains only ‘/’. The further fields can either contain ‘<’ to indicate that this column should start a group, ‘>’ to indicate the end of a column, or ‘<>’ (no space between ‘<’ and ‘>’) to make a column a group of its own. Upon export, boundaries between column groups are marked with vertical lines. Here is an example:

| N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
|---+-----+-----+-----+---------+------------|
| / |  <  |     |  >  |       < |          > |
| 1 |  1  |  1  |  1  |       1 |          1 |
| 2 |  4  |  8  | 16  |  1.4142 |     1.1892 |
| 3 |  9  | 27  | 81  |  1.7321 |     1.3161 |
|---+-----+-----+-----+---------+------------|
#+TBLFM: $2=$1^2::$3=$1^3::$4=$1^4::$5=sqrt($1)::$6=sqrt(sqrt(($1)))

It is also sufficient to just insert the column group starters after every vertical line you would like to have:

| N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
|---+-----+-----+-----+---------+------------|
| / | <   |     |     | <       |            |

3.4Orgtbl辅模式

If you like the intuitive way the Org table editor works, you might also want to use it in other modes like Text mode or Mail mode. The minor mode Orgtbl mode makes this possible. You can always toggle the mode with M-x orgtbl-mode. To turn it on by default, for example in Message mode, use

(add-hook 'message-mode-hook 'turn-on-orgtbl)

Furthermore, with some special setup, it is possible to maintain tables in arbitrary syntax with Orgtbl mode. For example, it is possible to construct LaTeX tables with the underlying ease and power of Orgtbl mode, including spreadsheet capabilities. For details, see Tables in Arbitrary Syntax.

3.5电子表格

The table editor makes use of the Emacs Calc package to implement spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms to derive fields from other fields. While fully featured, Org’s implementation is not identical to other spreadsheets. For example, Org knows the concept of a column formula that will be applied to all non-header fields in a column without having to copy the formula to each relevant field. There is also a formula debugger, and a formula editor with features for highlighting fields in the table corresponding to the references at point in the formula, moving these references by arrow keys.

3.5.1引用文件

To compute fields in the table from other fields, formulas must reference other fields or ranges. In Org, fields can be referenced by name, by absolute coordinates, and by relative coordinates. To find out what the coordinates of a field are, press C-c ? in that field, or press C-c } to toggle the display of a grid.

Field references

Formulas can reference the value of another field in two ways. Like in any other spreadsheet, you may reference fields with a letter/number combination like ‘B3’, meaning the second field in the third row. However, Org prefers to use another, more general representation that looks like this:¹⁸

@ROW$COLUMN

Column specifications can be absolute like ‘$1’, ‘$2’, …, ‘$N’, or relative to the current column, i.e., the column of the field which is being computed, like ‘$+1’ or ‘$-2’. ‘$<’ and ‘$>’ are immutable references to the first and last column, respectively, and you can use ‘$>>>’ to indicate the third column from the right.

The row specification only counts data lines and ignores horizontal separator lines, or “hlines”. Like with columns, you can use absolute row numbers ‘@1’, ‘@2’, …, ‘@N’, and row numbers relative to the current row like ‘@+3’ or ‘@-1’. ‘@<’ and ‘@>’ are immutable references the first and last row in the table, respectively. You may also specify the row relative to one of the hlines: ‘@I’ refers to the first hline, ‘@II’ to the second, etc. ‘@-I’ refers to the first such line above the current line, ‘@+I’ to the first such line below the current line. You can also write ‘@III+2’ which is the second data line after the third hline in the table.

‘@0’ and ‘$0’ refer to the current row and column, respectively, i.e., to the row/column for the field being computed. Also, if you omit either the column or the row part of the reference, the current row/column is implied.

Org’s references with unsigned numbers are fixed references in the sense that if you use the same reference in the formula for two different fields, the same field is referenced each time. Org’s references with signed numbers are floating references because the same reference operator can reference different fields depending on the field being calculated by the formula.

Here are a few examples:

Range references

You may reference a rectangular range of fields by specifying two field references connected by two dots ‘..’. The ends are included in the range. If both fields are in the current row, you may simply use ‘$2..$7’, but if at least one field is in a different row, you need to use the general ‘@ROW$COLUMN’ format at least for the first field, i.e., the reference must start with ‘@’ in order to be interpreted correctly. Examples:

Range references return a vector of values that can be fed into Calc vector functions. Empty fields in ranges are normally suppressed, so that the vector contains only the non-empty fields. For other options with the mode switches ‘E’, ‘N’ and examples, see Formula syntax for Calc.

Field coordinates in formulas

One of the very first actions during evaluation of Calc formulas and Lisp formulas is to substitute ‘@#’ and ‘$#’ in the formula with the row or column number of the field where the current result will go to. The traditional Lisp formula equivalents are org-table-current-dline and org-table-current-column. Examples:

‘if(@# % 2, $#, string(""))’

Insert column number on odd rows, set field to empty on even rows.

‘$2 = '(identity remote(FOO, @@#$1))’

Copy text or values of each row of column 1 of the table named FOO into column 2 of the current table.

‘@3 = 2 * remote(FOO, @1$$#)’

Insert the doubled value of each column of row 1 of the table named FOO into row 3 of the current table.

For the second and third examples, table FOO must have at least as many rows or columns as the current table. Note that this is inefficient¹⁹ for large number of rows.

Named references

‘$name’ is interpreted as the name of a column, parameter or constant. Constants are defined globally through the variable org-table-formula-constants, and locally—for the file—through a line like this example:

#+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6

Also, properties (see Properties and Columns) can be used as constants in table formulas: for a property ‘Xyz’ use the name ‘$PROP_Xyz’, and the property will be searched in the current outline entry and in the hierarchy above it. If you have the ‘constants.el’ package, it will also be used to resolve constants, including natural constants like ‘$h’ for Planck’s constant, and units like ‘$km’ for kilometers²⁰. Column names and parameters can be specified in special table lines. These are described below, see Advanced features. All names must start with a letter, and further consist of letters and numbers.

Remote references

You may also reference constants, fields and ranges from a different table, either in the current file or even in a different file. The syntax is

remote(NAME,REF)

where NAME can be the name of a table in the current file as set by a ‘#+NAME:’ line before the table. It can also be the ID of an entry, even in a different file, and the reference then refers to the first table in that entry. REF is an absolute field or range reference as described above for example ‘@3$3’ or ‘$somename’, valid in the referenced table.

When NAME has the format ‘@ROW$COLUMN’, it is substituted with the name or ID found in this field of the current table. For example ‘remote($1, @@>$2)’ ⇒ ‘remote(year_2013, @@>$1)’. The format ‘B3’ is not supported because it can not be distinguished from a plain table name or ID.

3.5.2可计算的公式语法

A formula can be any algebraic expression understood by the Emacs Calc package. Note that Calc has the non-standard convention that ‘/’ has lower precedence than ‘*’, so that ‘a/b*c’ is interpreted as ‘(a/(b*c))’. Before evaluation by calc-eval (see (calc)Calling Calc from Your Lisp Programs), variable substitution takes place according to the rules described above.

The range vectors can be directly fed into the Calc vector functions like vmean and vsum.

A formula can contain an optional mode string after a semicolon. This string consists of flags to influence Calc and other modes during execution. By default, Org uses the standard Calc modes (precision 12, angular units degrees, fraction and symbolic modes off). The display format, however, has been changed to ‘(float 8)’ to keep tables compact. The default settings can be configured using the variable org-calc-default-modes.

‘p20’

Set the internal Calc calculation precision to 20 digits.

‘n3’, ‘s3’, ‘e2’, ‘f4’

Normal, scientific, engineering or fixed format of the result of Calc passed back to Org. Calc formatting is unlimited in precision as long as the Calc calculation precision is greater.

‘D’, ‘R’

Degree and radian angle modes of Calc.

‘F’, ‘S’

Fraction and symbolic modes of Calc.

‘T’, ‘t’, ‘U’

Duration computations in Calc or Lisp, Durations and time values.

‘E’

If and how to consider empty fields. Without ‘E’ empty fields in range references are suppressed so that the Calc vector or Lisp list contains only the non-empty fields. With ‘E’ the empty fields are kept. For empty fields in ranges or empty field references the value ‘nan’ (not a number) is used in Calc formulas and the empty string is used for Lisp formulas. Add ‘N’ to use 0 instead for both formula types. For the value of a field the mode ‘N’ has higher precedence than ‘E’.

‘N’

Interpret all fields as numbers, use 0 for non-numbers. See the next section to see how this is essential for computations with Lisp formulas. In Calc formulas it is used only occasionally because there number strings are already interpreted as numbers without ‘N’.

‘L’

Literal, for Lisp formulas only. See the next section.

Unless you use large integer numbers or high-precision calculation and display for floating point numbers you may alternatively provide a printf format specifier to reformat the Calc result after it has been passed back to Org instead of letting Calc already do the formatting²¹. A few examples:

Calc also contains a complete set of logical operations (see (calc)Logical Operations). For example

‘if($1 < 20, teen, string(""))’

‘"teen"’ if age ‘$1’ is less than 20, else the Org table result field is set to empty with the empty string.

‘if("$1" =​= "nan" || "$2" =​= "nan", string(""), $1 + $2); E f-1’

Sum of the first two columns. When at least one of the input fields is empty the Org table result field is set to empty. ‘E’ is required to not convert empty fields to 0. ‘f-1’ is an optional Calc format string similar to ‘%.1f’ but leaves empty results empty.

‘if(typeof(vmean($1..$7)) =​= 12, string(""), vmean($1..$7); E’

Mean value of a range unless there is any empty field. Every field in the range that is empty is replaced by ‘nan’ which lets ‘vmean’ result in ‘nan’. Then ‘typeof =’ 12= detects the ‘nan’ from vmean and the Org table result field is set to empty. Use this when the sample set is expected to never have missing values.

‘if("$1..$7" =​= "[]", string(""), vmean($1..$7))’

Mean value of a range with empty fields skipped. Every field in the range that is empty is skipped. When all fields in the range are empty the mean value is not defined and the Org table result field is set to empty. Use this when the sample set can have a variable size.

‘vmean($1..$7); EN’

To complete the example before: Mean value of a range with empty fields counting as samples with value 0. Use this only when incomplete sample sets should be padded with 0 to the full size.

You can add your own Calc functions defined in Emacs Lisp with defmath and use them in formula syntax for Calc.

3.5.3Emacs Lisp形式的公式

It is also possible to write a formula in Emacs Lisp. This can be useful for string manipulation and control structures, if Calc’s functionality is not enough.

If a formula starts with a single-quote followed by an opening parenthesis, then it is evaluated as a Lisp form. The evaluation should return either a string or a number. Just as with Calc formulas, you can specify modes and a printf format after a semicolon.

With Emacs Lisp forms, you need to be conscious about the way field references are interpolated into the form. By default, a reference is interpolated as a Lisp string (in double-quotes) containing the field. If you provide the ‘N’ mode switch, all referenced elements are numbers—non-number fields will be zero—and interpolated as Lisp numbers, without quotes. If you provide the ‘L’ flag, all fields are interpolated literally, without quotes. For example, if you want a reference to be interpreted as a string by the Lisp form, enclose the reference operator itself in double-quotes, like ‘"$3"’. Ranges are inserted as space-separated fields, so you can embed them in list or vector syntax.

Here are a few examples—note how the ‘N’ mode is used when we do computations in Lisp:

‘'(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))’

Swap the first two characters of the content of column 1.

‘'(+ $1 $2);N’

Add columns 1 and 2, equivalent to Calc’s ‘$1+$2’.

‘'(apply '+ '($1..$4));N’

Compute the sum of columns 1 to 4, like Calc’s ‘vsum($1..$4)’.

3.5.4持续时间和时间值

If you want to compute time values use the ‘T’, ‘t’, or ‘U’ flag, either in Calc formulas or Elisp formulas:

|  Task 1 |   Task 2 |    Total |
|---------+----------+----------|
|    2:12 |     1:47 | 03:59:00 |
|    2:12 |     1:47 |    03:59 |
| 3:02:20 | -2:07:00 |     0.92 |
#+TBLFM: @2$3=$1+$2;T::@3$3=$1+$2;U::@4$3=$1+$2;t

Input duration values must be of the form ‘HH:MM[:SS]’, where seconds are optional. With the ‘T’ flag, computed durations are displayed as ‘HH:MM:SS’ (see the first formula above). With the ‘U’ flag, seconds are omitted so that the result is only ‘HH:MM’ (see second formula above). Zero-padding of the hours field depends upon the value of the variable org-table-duration-hour-zero-padding.

With the ‘t’ flag, computed durations are displayed according to the value of the option org-table-duration-custom-format, which defaults to hours and displays the result as a fraction of hours (see the third formula in the example above).

Negative duration values can be manipulated as well, and integers are considered as seconds in addition and subtraction.

3.5.5字段和范围公式

To assign a formula to a particular field, type it directly into the field, preceded by ‘:=’, for example ‘vsum(@II..III)’. When you press TAB or RET or C-c C-c with point still in the field, the formula is stored as the formula for this field, evaluated, and the current field is replaced with the result.

Formulas are stored in a special ‘TBLFM’ keyword located directly below the table. If you type the equation in the fourth field of the third data line in the table, the formula looks like ‘@3$4=$1+$2’. When inserting/deleting/swapping column and rows with the appropriate commands, absolute references (but not relative ones) in stored formulas are modified in order to still reference the same field. To avoid this from happening, in particular in range references, anchor ranges at the table borders (using ‘@<’, ‘@>’, ‘$<’, ‘$>’), or at hlines using the ‘@I’ notation. Automatic adaptation of field references does not happen if you edit the table structure with normal editing commands—you must fix the formulas yourself.

Instead of typing an equation into the field, you may also use the following command

C-u C-c = (org-table-eval-formula)

Install a new formula for the current field. The command prompts for a formula with default taken from the ‘TBLFM’ keyword, applies it to the current field, and stores it.

The left-hand side of a formula can also be a special expression in order to assign the formula to a number of different fields. There is no keyboard shortcut to enter such range formulas. To add them, use the formula editor (see Editing and debugging formulas) or edit the ‘TBLFM’ keyword directly.

‘$2=’

Column formula, valid for the entire column. This is so common that Org treats these formulas in a special way, see Column formulas.

‘@3=’

Row formula, applies to all fields in the specified row. ‘@>=’ means the last row.

‘@1$2..@4$3=’

Range formula, applies to all fields in the given rectangular range. This can also be used to assign a formula to some but not all fields in a row.

‘$NAME=’

Named field, see Advanced features.

3.5.6列公式

When you assign a formula to a simple column reference like ‘$3=’, the same formula is used in all fields of that column, with the following very convenient exceptions: (i) If the table contains horizontal separator hlines with rows above and below, everything before the first such hline is considered part of the table header and is not modified by column formulas. Therefore a header is mandatory when you use column formulas and want to add hlines to group rows, like for example to separate a total row at the bottom from the summand rows above. (ii) Fields that already get a value from a field/range formula are left alone by column formulas. These conditions make column formulas very easy to use.

To assign a formula to a column, type it directly into any field in the column, preceded by an equal sign, like ‘=$1+$2’. When you press TAB or RET or C-c C-c with point still in the field, the formula is stored as the formula for the current column, evaluated and the current field replaced with the result. If the field contains only ‘=’, the previously stored formula for this column is used. For each column, Org only remembers the most recently used formula. In the ‘TBLFM’ keyword, column formulas look like ‘$4=$1+$2’. The left-hand side of a column formula can not be the name of column, it must be the numeric column reference or ‘$>’.

Instead of typing an equation into the field, you may also use the following command:

C-c = (org-table-eval-formula)

Install a new formula for the current column and replace current field with the result of the formula. The command prompts for a formula, with default taken from the ‘TBLFM’ keyword, applies it to the current field and stores it. With a numeric prefix argument, e.g., C-5 C-c =, the command applies it to that many consecutive fields in the current column.

3.5.7查找函数

Org has three predefined Emacs Lisp functions for lookups in tables.

‘(org-lookup-first VAL S-LIST R-LIST &optional PREDICATE)’

Searches for the first element S in list S-LIST for which

(PREDICATE VAL S)

is non-nil; returns the value from the corresponding position in list R-LIST. The default PREDICATE is equal. Note that the parameters VAL and S are passed to PREDICATE in the same order as the corresponding parameters are in the call to org-lookup-first, where VAL precedes S-LIST. If R-LIST is nil, the matching element S of S-LIST is returned.

‘(org-lookup-last VAL S-LIST R-LIST &optional PREDICATE)’

Similar to org-lookup-first above, but searches for the last element for which PREDICATE is non-nil.

‘(org-lookup-all VAL S-LIST R-LIST &optional PREDICATE)’

Similar to org-lookup-first, but searches for all elements for which PREDICATE is non-nil, and returns all corresponding values. This function can not be used by itself in a formula, because it returns a list of values. However, powerful lookups can be built when this function is combined with other Emacs Lisp functions.

If the ranges used in these functions contain empty fields, the ‘E’ mode for the formula should usually be specified: otherwise empty fields are not included in S-LIST and/or R-LIST which can, for example, result in an incorrect mapping from an element of S-LIST to the corresponding element of R-LIST.

These three functions can be used to implement associative arrays, count matching cells, rank results, group data, etc. For practical examples see this tutorial on Worg.

3.5.8编辑和调试公式

You can edit individual formulas in the minibuffer or directly in the field. Org can also prepare a special buffer with all active formulas of a table. When offering a formula for editing, Org converts references to the standard format (like ‘B3’ or ‘D&’) if possible. If you prefer to only work with the internal format (like ‘@3$2’ or ‘$4’), configure the variable org-table-use-standard-references.

C-c = or C-u C-c = (org-table-eval-formula)

Edit the formula associated with the current column/field in the minibuffer. See Column formulas, and Field and range formulas.

C-u C-u C-c = (org-table-eval-formula)

Re-insert the active formula (either a field formula, or a column formula) into the current field, so that you can edit it directly in the field. The advantage over editing in the minibuffer is that you can use the command C-c ?.

C-c ? (org-table-field-info)

While editing a formula in a table field, highlight the field(s) referenced by the reference at point position in the formula.

C-c } (org-table-toggle-coordinate-overlays)

Toggle the display of row and column numbers for a table, using overlays. These are updated each time the table is aligned; you can force it with C-c C-c.

C-c { (org-table-toggle-formula-debugger)

Toggle the formula debugger on and off. See below.

C-c ' (org-table-edit-formulas)

Edit all formulas for the current table in a special buffer, where the formulas are displayed one per line. If the current field has an active formula, point in the formula editor marks it. While inside the special buffer, Org automatically highlights any field or range reference at point position. You may edit, remove and add formulas, and use the following commands:

C-c C-c or C-x C-s (org-table-fedit-finish)

Exit the formula editor and store the modified formulas. With C-u prefix, also apply the new formulas to the entire table.

C-c C-q (org-table-fedit-abort)

Exit the formula editor without installing changes.

C-c C-r (org-table-fedit-toggle-ref-type)

Toggle all references in the formula editor between standard (like ‘B3’) and internal (like ‘@3$2’).

TAB (org-table-fedit-lisp-indent)

Pretty-print or indent Lisp formula at point. When in a line containing a Lisp formula, format the formula according to Emacs Lisp rules. Another TAB collapses the formula back again. In the open formula, TAB re-indents just like in Emacs Lisp mode.

M-TAB (lisp-complete-symbol)

Complete Lisp symbols, just like in Emacs Lisp mode.

S-UP, S-DOWN, S-LEFT, S-RIGHT

Shift the reference at point. For example, if the reference is ‘B3’ and you press S-RIGHT, it becomes ‘C3’. This also works for relative references and for hline references.

M-S-UP (org-table-fedit-line-up)

Move the test line for column formulas up in the Org buffer.

M-S-DOWN (org-table-fedit-line-down)

Move the test line for column formulas down in the Org buffer.

M-UP (org-table-fedit-scroll-up)

Scroll up the window displaying the table.

M-DOWN (org-table-fedit-scroll-down)

Scroll down the window displaying the table.

C-c }

Turn the coordinate grid in the table on and off.

Making a table field blank does not remove the formula associated with the field, because that is stored in a different line—the ‘TBLFM’ keyword line. During the next recalculation, the field will be filled again. To remove a formula from a field, you have to give an empty reply when prompted for the formula, or to edit the ‘TBLFM’ keyword.

You may edit the ‘TBLFM’ keyword directly and re-apply the changed equations with C-c C-c in that line or with the normal recalculation commands in the table.

Using multiple ‘TBLFM’ lines

You may apply the formula temporarily. This is useful when you want to switch the formula applied to the table. Place multiple ‘TBLFM’ keywords right after the table, and then press C-c C-c on the formula to apply. Here is an example:

| x | y |
|---+---|
| 1 |   |
| 2 |   |
#+TBLFM: $2=$1*1
#+TBLFM: $2=$1*2

Pressing C-c C-c in the line of ‘#+TBLFM: $2=$1*2’ yields:

| x | y |
|---+---|
| 1 | 2 |
| 2 | 4 |
#+TBLFM: $2=$1*1
#+TBLFM: $2=$1*2

If you recalculate this table, with C-u C-c *, for example, you get the following result from applying only the first ‘TBLFM’ keyword.

| x | y |
|---+---|
| 1 | 1 |
| 2 | 2 |
#+TBLFM: $2=$1*1
#+TBLFM: $2=$1*2

Debugging formulas

When the evaluation of a formula leads to an error, the field content becomes the string ‘#ERROR’. If you would like to see what is going on during variable substitution and calculation in order to find a bug, turn on formula debugging in the Tbl menu and repeat the calculation, for example by pressing C-u C-u C-c = RET in a field. Detailed information are displayed.

3.5.9更新表格

Recalculation of a table is normally not automatic, but needs to be triggered by a command. To make recalculation at least semi-automatic, see Advanced features.

In order to recalculate a line of a table or the entire table, use the following commands:

C-c * (org-table-recalculate)

Recalculate the current row by first applying the stored column formulas from left to right, and all field/range formulas in the current row.

C-u C-c * or C-u C-c C-c

Recompute the entire table, line by line. Any lines before the first hline are left alone, assuming that these are part of the table header.

C-u C-u C-c * or C-u C-u C-c C-c (org-table-iterate)

Iterate the table by recomputing it until no further changes occur. This may be necessary if some computed fields use the value of other fields that are computed later in the calculation sequence.

M-x org-table-recalculate-buffer-tables

Recompute all tables in the current buffer.

M-x org-table-iterate-buffer-tables

Iterate all tables in the current buffer, in order to converge table-to-table dependencies.

3.5.10高级功能

If you want the recalculation of fields to happen automatically, or if you want to be able to assign names²² to fields and columns, you need to reserve the first column of the table for special marking characters.

C-# (org-table-rotate-recalc-marks)

Rotate the calculation mark in first column through the states ‘#’, ‘*’, ‘!’, ‘$’. When there is an active region, change all marks in the region.

Here is an example of a table that collects exam results of students and makes use of these features:

|---+---------+--------+--------+--------+-------+------|
|   | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note |
|---+---------+--------+--------+--------+-------+------|
| ! |         |     P1 |     P2 |     P3 |   Tot |      |
| # | Maximum |     10 |     15 |     25 |    50 | 10.0 |
| ^ |         |     m1 |     m2 |     m3 |    mt |      |
|---+---------+--------+--------+--------+-------+------|
| # | Peter   |     10 |      8 |     23 |    41 |  8.2 |
| # | Sam     |      2 |      4 |      3 |     9 |  1.8 |
|---+---------+--------+--------+--------+-------+------|
|   | Average |        |        |        |  25.0 |      |
| ^ |         |        |        |        |    at |      |
| $ | max=50  |        |        |        |       |      |
|---+---------+--------+--------+--------+-------+------|
#+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@-II..@-I);%.1f

Important: Please note that for these special tables, recalculating the table with C-u C-c * only affects rows that are marked ‘#’ or ‘*’, and fields that have a formula assigned to the field itself. The column formulas are not applied in rows with empty first field.

The marking characters have the following meaning:

‘!’

The fields in this line define names for the columns, so that you may refer to a column as ‘$Tot’ instead of ‘$6’.

‘^’

This row defines names for the fields above the row. With such a definition, any formula in the table may use ‘$m1’ to refer to the value ‘10’. Also, if you assign a formula to a names field, it is stored as ‘$name = ...’.

‘_’

Similar to ‘^’, but defines names for the fields in the row below.

‘$’

Fields in this row can define parameters for formulas. For example, if a field in a ‘$’ row contains ‘max=50’, then formulas in this table can refer to the value 50 using ‘$max’. Parameters work exactly like constants, only that they can be defined on a per-table basis.

‘#’

Fields in this row are automatically recalculated when pressing TAB or RET or S-TAB in this row. Also, this row is selected for a global recalculation with C-u C-c *. Unmarked lines are left alone by this command.

‘*’

Selects this line for global recalculation with C-u C-c *, but not for automatic recalculation. Use this when automatic recalculation slows down editing too much.

‘/’

Do not export this line. Useful for lines that contain the narrowing ‘<N>’ markers or column group markers.

Finally, just to whet your appetite for what can be done with the fantastic Calc package, here is a table that computes the Taylor series of degree n at location x for a couple of functions.

|---+-------------+---+-----+--------------------------------------|
|   | Func        | n | x   | Result                               |
|---+-------------+---+-----+--------------------------------------|
| # | exp(x)      | 1 | x   | 1 + x                                |
| # | exp(x)      | 2 | x   | 1 + x + x^2 / 2                      |
| # | exp(x)      | 3 | x   | 1 + x + x^2 / 2 + x^3 / 6            |
| # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |
| # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2    |
| * | tan(x)      | 3 | x   | 0.0175 x + 1.77e-6 x^3               |
|---+-------------+---+-----+--------------------------------------|
#+TBLFM: $5=taylor($2,$4,$3);n3

3.6Org图表

Org Plot can produce graphs of information stored in Org tables, either graphically or in ASCII art.

Graphical plots using Gnuplot

Org Plot can produce 2D and 3D graphs of information stored in Org tables using Gnuplot and Gnuplot mode. To see this in action, ensure that you have both Gnuplot and Gnuplot mode installed on your system, then call C-c " g or M-x org-plot/gnuplot on the following table.

#+PLOT: title:"Citas" ind:1 deps:(3) type:2d with:histograms set:"yrange [0:]"
| Sede      | Max cites | H-index |
|-----------+-----------+---------|
| Chile     |    257.72 |   21.39 |
| Leeds     |    165.77 |   19.68 |
| Sao Paolo |     71.00 |   11.50 |
| Stockholm |    134.19 |   14.33 |
| Morelia   |    257.56 |   17.67 |

Notice that Org Plot is smart enough to apply the table’s headers as labels. Further control over the labels, type, content, and appearance of plots can be exercised through the ‘PLOT’ keyword preceding a table. See below for a complete list of Org Plot options. For more information and examples see the Org Plot tutorial.

Plot options

‘set’

Specify any Gnuplot option to be set when graphing.

‘title’

Specify the title of the plot.

‘ind’

Specify which column of the table to use as the ‘x’ axis.

‘deps’

Specify the columns to graph as a Lisp style list, surrounded by parentheses and separated by spaces for example ‘dep:(3 4)’ to graph the third and fourth columns. Defaults to graphing all other columns aside from the ‘ind’ column.

‘type’

Specify whether the plot is ‘2d’, ‘3d’, or ‘grid’.

‘with’

Specify a ‘with’ option to be inserted for every column being plotted, e.g., ‘lines’, ‘points’, ‘boxes’, ‘impulses’. Defaults to ‘lines’.

‘file’

If you want to plot to a file, specify ‘"path/to/desired/output-file"’.

‘labels’

List of labels to be used for the ‘deps’. Defaults to the column headers if they exist.

‘line’

Specify an entire line to be inserted in the Gnuplot script.

‘map’

When plotting ‘3d’ or ‘grid’ types, set this to ‘t’ to graph a flat mapping rather than a ‘3d’ slope.

‘timefmt’

Specify format of Org mode timestamps as they will be parsed by Gnuplot. Defaults to ‘%Y-%m-%d-%H:%M:%S’.

‘script’

If you want total control, you can specify a script file—place the file name between double-quotes—which will be used to plot. Before plotting, every instance of ‘$datafile’ in the specified script will be replaced with the path to the generated data file. Note: even if you set this option, you may still want to specify the plot type, as that can impact the content of the data file.

ASCII bar plots

While point is on a column, typing C-c `` a or M-x orgtbl-ascii-plot create a new column containing an ASCII-art bars plot. The plot is implemented through a regular column formula. When the source column changes, the bar plot may be updated by refreshing the table, for example typing C-u C-c *.

| Sede          | Max cites |              |
|---------------+-----------+--------------|
| Chile         |    257.72 | WWWWWWWWWWWW |
| Leeds         |    165.77 | WWWWWWWh     |
| Sao Paolo     |     71.00 | WWW;         |
| Stockholm     |    134.19 | WWWWWW:      |
| Morelia       |    257.56 | WWWWWWWWWWWH |
| Rochefourchat |      0.00 |              |
#+TBLFM: $3='(orgtbl-ascii-draw $2 0.0 257.72 12)

The formula is an Elisp call.

Function: orgtbl-ascii-draw value min max &optional width

Draw an ASCII bar in a table.

VALUE is the value to plot.

MIN is the value displayed as an empty bar. MAX is the value filling all the WIDTH. Sources values outside this range are displayed as ‘too small’ or ‘too large’.

WIDTH is the number of characters of the bar plot. It defaults to ‘12’.

4 超链接

Like HTML, Org provides support for links inside a file, external links to other files, Usenet articles, emails, and much more.

4.1链接格式

Org recognizes plain URIs, possibly wrapped within angle brackets²³, and activate them as clickable links.

The general link format, however, looks like this:

[[LINK][DESCRIPTION]]

or alternatively

[[LINK]]

Some ‘\’, ‘[’ and ‘]’ characters in the LINK part need to be “escaped”, i.e., preceded by another ‘\’ character. More specifically, the following characters, and only them, must be escaped:

1. all ‘[’ and ‘]’ characters,
2. every ‘\’ character preceding either ‘]’ or ‘[’,
3. every ‘\’ character at the end of the link.

Functions inserting links (see Handling Links) properly escape ambiguous characters. You only need to bother about the rules above when inserting directly, or yanking, a URI within square brackets. When in doubt, you may use the function org-link-escape, which turns a link string into its escaped form.

Once a link in the buffer is complete, with all brackets present, Org changes the display so that ‘DESCRIPTION’ is displayed instead of ‘[[LINK][DESCRIPTION]]’ and ‘LINK’ is displayed instead of ‘[[LINK]]’. Links are highlighted in the org-link face, which, by default, is an underlined face.

You can directly edit the visible part of a link. This can be either the LINK part, if there is no description, or the DESCRIPTION part otherwise. To also edit the invisible LINK part, use C-c C-l with point on the link (see Handling Links).

If you place point at the beginning or just behind the end of the displayed text and press BS, you remove the—invisible—bracket at that location²⁴. This makes the link incomplete and the internals are again displayed as plain text. Inserting the missing bracket hides the link internals again. To show the internal structure of all links, use the menu: Org → Hyperlinks → Literal links.

4.2内部链接

A link that does not look like a URL—i.e., does not start with a known scheme or a file name—refers to the current document. You can follow it with C-c C-o when point is on the link, or with a mouse click (see Handling Links).

Org provides several refinements to internal navigation within a document. Most notably, a construct like ‘[[#my-custom-id]]’ specifically targets the entry with the ‘CUSTOM_ID’ property set to ‘my-custom-id’. Also, an internal link looking like ‘[[*Some section]]’ points to a headline with the name ‘Some section’²⁵.

When the link does not belong to any of the cases above, Org looks for a dedicated target: the same string in double angular brackets, like ‘<<My Target>>’.

If no dedicated target exists, the link tries to match the exact name of an element within the buffer. Naming is done, unsurprisingly, with the ‘NAME’ keyword, which has to be put in the line before the element it refers to, as in the following example

#+NAME: My Target
| a  | table      |
|----+------------|
| of | four cells |

Ultimately, if none of the above succeeds, Org searches for a headline that is exactly the link text but may also include a TODO keyword and tags, or initiates a plain text search, according to the value of org-link-search-must-match-exact-headline.

Note that you must make sure custom IDs, dedicated targets, and names are unique throughout the document. Org provides a linter to assist you in the process, if needed. See Org Syntax.

During export, internal links are used to mark objects and assign them a number. Marked objects are then referenced by links pointing to them. In particular, links without a description appear as the number assigned to the marked object²⁶. In the following excerpt from an Org buffer

1. one item
2. <<target>>another item
Here we refer to item [[target]].

The last sentence will appear as ‘Here we refer to item 2’ when exported.

In non-Org files, the search looks for the words in the link text. In the above example the search would be for ‘target’.

Following a link pushes a mark onto Org’s own mark ring. You can return to the previous position with C-c &. Using this command several times in direct succession goes back to positions recorded earlier.

4.3无线电目标

Org can automatically turn any occurrences of certain target names in normal text into a link. So without explicitly creating a link, the text connects to the target radioing its position. Radio targets are enclosed by triple angular brackets. For example, a target ‘<<<My Target>>>’ causes each occurrence of ‘my target’ in normal text to become activated as a link. The Org file is scanned automatically for radio targets only when the file is first loaded into Emacs. To update the target list during editing, press C-c C-c with point on or at a target.

4.4外部链接

Org supports links to files, websites, Usenet and email messages, BBDB database entries and links to both IRC conversations and their logs. External links are URL-like locators. They start with a short identifying string followed by a colon. There can be no space after the colon.

Here is the full set of built-in link types:

‘file’

File links. File name may be remote, absolute, or relative.

Additionally, you can specify a line number, or a text search. In Org files, you may link to a headline name, a custom ID, or a code reference instead.

As a special case, “file” prefix may be omitted if the file name is complete, e.g., it starts with ‘./’, or ‘/’.

‘attachment’

Same as file links but for files and folders attached to the current node (see Attachments). Attachment links are intended to behave exactly as file links but for files relative to the attachment directory.

‘bbdb’

Link to a BBDB record, with possible regexp completion.

‘docview’

Link to a document opened with DocView mode. You may specify a page number.

‘doi’

Link to an electronic resource, through its handle.

‘elisp’

Execute an Elisp command upon activation.

‘gnus’, ‘rmail’, ‘mhe’

Link to messages or folders from a given Emacs’ MUA.

‘help’

Display documentation of a symbol in ‘*Help*’ buffer.

‘http’, ‘https’

Web links.

‘id’

Link to a specific headline by its ID property, in an Org file.

‘info’

Link to an Info manual, or to a specific node.

‘irc’

Link to an IRC channel.

‘mailto’

Link to message composition.

‘news’

Usenet links.

‘shell’

Execute a shell command upon activation.

The following table illustrates the link types above, along with their options:

On top of these built-in link types, additional ones are available through the ‘contrib/’ directory (see Installation). For example, these links to VM or Wanderlust messages are available when you load the corresponding libraries from the ‘contrib/’ directory:

For information on customizing Org to add new link types, see Adding Hyperlink Types.

A link should be enclosed in double brackets and may contain descriptive text to be displayed instead of the URL (see Link Format), for example:

[[http://www.gnu.org/software/emacs/][GNU Emacs]]

If the description is a file name or URL that points to an image, HTML export (see HTML Export) inlines the image as a clickable button. If there is no description at all and the link points to an image, that image is inlined into the exported HTML file.

Org also recognizes external links amid normal text and activates them as links. If spaces must be part of the link (for example in ‘bbdb:R.*Stallman’), or if you need to remove ambiguities about the end of the link, enclose the link in square or angular brackets.

4.5处理链接

Org provides methods to create a link in the correct syntax, to insert it into an Org file, and to follow the link.

The main function is org-store-link, called with M-x org-store-link. Because of its importance, we suggest to bind it to a widely available key (see Activation). It stores a link to the current location. The link is stored for later insertion into an Org buffer—see below. The kind of link that is created depends on the current buffer:

Org mode buffers

For Org files, if there is a ‘<<target>>’ at point, the link points to the target. Otherwise it points to the current headline, which is also the description²⁸.

If the headline has a ‘CUSTOM_ID’ property, store a link to this custom ID. In addition or alternatively, depending on the value of org-id-link-to-org-use-id, create and/or use a globally unique ‘ID’ property for the link²⁹. So using this command in Org buffers potentially creates two links: a human-readable link from the custom ID, and one that is globally unique and works even if the entry is moved from file to file. Later, when inserting the link, you need to decide which one to use.

Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus

Pretty much all Emacs mail clients are supported. The link points to the current article, or, in some Gnus buffers, to the group. The description is constructed according to the variable org-link-email-description-format. By default, it refers to the addressee and the subject.

Web browsers: W3, W3M and EWW

Here the link is the current URL, with the page title as the description.

Contacts: BBDB

Links created in a BBDB buffer point to the current entry.

Chat: IRC

For IRC links, if the variable org-irc-link-to-logs is non-nil, create a ‘file’ style link to the relevant point in the logs for the current conversation. Otherwise store an ‘irc’ style link to the user/channel/server under the point.

Other files

For any other file, the link points to the file, with a search string (see Search Options) pointing to the contents of the current line. If there is an active region, the selected words form the basis of the search string. You can write custom Lisp functions to select the search string and perform the search for particular file types (see Custom Searches).

You can also define dedicated links to other files. See Adding Hyperlink Types.

Agenda view

When point is in an agenda view, the created link points to the entry referenced by the current line.

From an Org buffer, the following commands create, navigate or, more generally, act on links.

C-c C-l (org-insert-link)

Insert a link³⁰. This prompts for a link to be inserted into the buffer. You can just type a link, using text for an internal link, or one of the link type prefixes mentioned in the examples above. The link is inserted into the buffer, along with a descriptive text³¹. If some text was selected at this time, it becomes the default description.

Inserting stored links

All links stored during the current session are part of the history for this prompt, so you can access them with UP and DOWN (or M-p, M-n).

Completion support

Completion with TAB helps you to insert valid link prefixes like ‘http’ or ‘ftp’, including the prefixes defined through link abbreviations (see Link Abbreviations). If you press RET after inserting only the prefix, Org offers specific completion support for some link types³². For example, if you type f i l e RET—alternative access: C-u C-c C-l, see below—Org offers file name completion, and after b b d b RET you can complete contact names.

C-u C-c C-l

When C-c C-l is called with a C-u prefix argument, insert a link to a file. You may use file name completion to select the name of the file. The path to the file is inserted relative to the directory of the current Org file, if the linked file is in the current directory or in a sub-directory of it, or if the path is written relative to the current directory using ‘../’. Otherwise an absolute path is used, if possible with ‘~/’ for your home directory. You can force an absolute path with two C-u prefixes.

C-c C-l (with point on existing link)

When point is on an existing link, C-c C-l allows you to edit the link and description parts of the link.

C-c C-o (org-open-at-point)

Open link at point. This launches a web browser for URL (using browse-url-at-point), run VM/MH-E/Wanderlust/Rmail/Gnus/BBDB for the corresponding links, and execute the command in a shell link. When point is on an internal link, this command runs the corresponding search. When point is on the tags part of a headline, it creates the corresponding tags view (see Matching tags and properties). If point is on a timestamp, it compiles the agenda for that date. Furthermore, it visits text and remote files in ‘file’ links with Emacs and select a suitable application for local non-text files. Classification of files is based on file extension only. See option org-file-apps. If you want to override the default application and visit the file with Emacs, use a C-u prefix. If you want to avoid opening in Emacs, use a C-u C-u prefix.

If point is on a headline, but not on a link, offer all links in the headline and entry text. If you want to setup the frame configuration for following links, customize org-link-frame-setup.

RET

When org-return-follows-link is set, RET also follows the link at point.

mouse-2 or mouse-1

On links, mouse-1 and mouse-2 opens the link just as C-c C-o does.

鼠标右键

Like mouse-2, but force file links to be opened with Emacs, and internal links to be displayed in another window³³.

C-c % (org-mark-ring-push)

Push the current position onto the Org mark ring, to be able to return easily. Commands following an internal link do this automatically.

C-c & (org-mark-ring-goto)

Jump back to a recorded position. A position is recorded by the commands following internal links, and by C-c %. Using this command several times in direct succession moves through a ring of previously recorded positions.

C-c C-x C-n (org-next-link)

C-c C-x C-p (org-previous-link)

Move forward/backward to the next link in the buffer. At the limit of the buffer, the search fails once, and then wraps around. The key bindings for this are really too long; you might want to bind this also to M-n and M-p.

(with-eval-after-load 'org
  (define-key org-mode-map (kbd "M-n") 'org-next-link)
  (define-key org-mode-map (kbd "M-p") 'org-previous-link))

4.6使用Org之外的链接

You can insert and follow links that have Org syntax not only in Org, but in any Emacs buffer. For this, Org provides two functions: org-insert-link-global and org-open-at-point-global.

You might want to bind them to globally available keys. See Activation for some advice.

4.7链接缩写

Long URL can be cumbersome to type, and often many similar links are needed in a document. For this you can use link abbreviations. An abbreviated link looks like this

[[linkword:tag][description]]

where the tag is optional. The linkword must be a word, starting with a letter, followed by letters, numbers, ‘-’, and ‘_’. Abbreviations are resolved according to the information in the variable org-link-abbrev-alist that relates the linkwords to replacement text. Here is an example:

(setq org-link-abbrev-alist
      '(("bugzilla"  . "http://10.1.2.9/bugzilla/show_bug.cgi?id=")
        ("url-to-ja" . "http://translate.google.fr/translate?sl=en&tl=ja&u=%h")
        ("google"    . "http://www.google.com/search?q=")
        ("gmap"      . "http://maps.google.com/maps?q=%s")
        ("omap"      . "http://nominatim.openstreetmap.org/search?q=%s&polygon=1")
        ("ads"       . "https://ui.adsabs.harvard.edu/search/q=%20author%3A\"%s\"")))

If the replacement text contains the string ‘%s’, it is replaced with the tag. Using ‘%h’ instead of ‘%s’ percent-encodes the tag (see the example above, where we need to encode the URL parameter). Using ‘%(my-function)’ passes the tag to a custom Lisp function, and replace it by the resulting string.

If the replacement text do not contain any specifier, it is simply appended to the string in order to create the link.

Instead of a string, you may also specify a Lisp function to create the link. Such a function will be called with the tag as the only argument.

With the above setting, you could link to a specific bug with ‘[[bugzilla:129]]’, search the web for ‘OrgMode’ with ‘[[google:OrgMode]]’, show the map location of the Free Software Foundation ‘[[gmap:51 Franklin Street, Boston]]’ or of Carsten office ‘[[omap:Science Park 904, Amsterdam, The Netherlands]]’ and find out what the Org author is doing besides Emacs hacking with ‘[[ads:Dominik,C]]’.

If you need special abbreviations just for a single Org buffer, you can define them in the file with

#+LINK: bugzilla  http://10.1.2.9/bugzilla/show_bug.cgi?id=
#+LINK: google    http://www.google.com/search?q=%s

In-buffer completion (see Completion) can be used after ‘[’ to complete link abbreviations. You may also define a Lisp function that implements special (e.g., completion) support for inserting such a link with C-c C-l. Such a function should not accept any arguments, and should return the full link with a prefix. You can set the link completion function like this:

(org-link-set-parameter "type" :complete #'some-completion-function)

4.8文件链接中的搜索选项

File links can contain additional information to make Emacs jump to a particular location in the file when following a link. This can be a line number or a search option after a double colon³⁴. For example, when the command org-store-link creates a link (see Handling Links) to a file, it encodes the words in the current line as a search string that can be used to find this line back later when following the link with C-c C-o.

Note that all search options apply for Attachment links in the same way that they apply for File links.

Here is the syntax of the different ways to attach a search to a file link, together with explanations for each:

[[file:~/code/main.c::255]]
[[file:~/xx.org::My Target]]
[[file:~/xx.org::*My Target]]
[[file:~/xx.org::#my-custom-id]]
[[file:~/xx.org::/regexp/]]
[[attachment:main.c::255]]

‘255’

Jump to line 255.

‘My Target’

Search for a link target ‘<<My Target>>’, or do a text search for ‘my target’, similar to the search in internal links, see Internal Links. In HTML export (see HTML Export), such a file link becomes a HTML reference to the corresponding named anchor in the linked file.

‘*My Target’

In an Org file, restrict search to headlines.

‘#my-custom-id’

Link to a heading with a ‘CUSTOM_ID’ property

‘/REGEXP/’

Do a regular expression search for REGEXP. This uses the Emacs command occur to list all matches in a separate window. If the target file is in Org mode, org-occur is used to create a sparse tree with the matches.

As a degenerate case, a file link with an empty file name can be used to search the current file. For example, ‘[[file:::find me]]’ does a search for ‘find me’ in the current file, just as ‘[[find me]]’ would.

4.9自定义搜索

The default mechanism for creating search strings and for doing the actual search related to a file link may not work correctly in all cases. For example, BibTeX database files have many entries like year="1993" which would not result in good search strings, because the only unique identification for a BibTeX entry is the citation key.

If you come across such a problem, you can write custom functions to set the right search string for a particular file type, and to do the search for the string in the file. Using add-hook, these functions need to be added to the hook variables org-create-file-search-functions and org-execute-file-search-functions. See the docstring for these variables for more information. Org actually uses this mechanism for BibTeX database files, and you can use the corresponding code as an implementation example. See the file ‘ol-bibtex.el’.

5 TODO项

Org mode does not maintain TODO lists as separate documents³⁵. Instead, TODO items are an integral part of the notes file, because TODO items usually come up while taking notes! With Org mode, simply mark any entry in a tree as being a TODO item. In this way, information is not duplicated, and the entire context from which the TODO item emerged is always present.

Of course, this technique for managing TODO items scatters them throughout your notes file. Org mode compensates for this by providing methods to give you an overview of all the things that you have to do.

5.1基本TODO功能

Any headline becomes a TODO item when it starts with the word ‘TODO’, for example:

*** TODO Write letter to Sam Fortune

The most important commands to work with TODO entries are:

C-c C-t (org-todo)

Rotate the TODO state of the current item among

,-> (unmarked) -> TODO -> DONE --.
'--------------------------------'

If TODO keywords have fast access keys (see Fast access to TODO states), prompt for a TODO keyword through the fast selection interface; this is the default behavior when org-use-fast-todo-selection is non-nil.

The same state changing can also be done “remotely” from the agenda buffer with the t command key (see Agenda Commands).

S-RIGHT S-LEFT

Select the following/preceding TODO state, similar to cycling. Useful mostly if more than two TODO states are possible (see TODO Extensions). See also Conflicts, for a discussion of the interaction with shift-selection. See also the variable org-treat-S-cursor-todo-selection-as-state-change.

C-c / t (org-show-todo-tree)

View TODO items in a sparse tree (see Sparse Trees). Folds the entire buffer, but shows all TODO items—with not-DONE state—and the headings hierarchy above them. With a prefix argument, or by using C-c / T, search for a specific TODO. You are prompted for the keyword, and you can also give a list of keywords like ‘KWD1|KWD2|...’ to list entries that match any one of these keywords. With a numeric prefix argument N, show the tree for the Nth keyword in the variable org-todo-keywords. With two prefix arguments, find all TODO states, both un-done and done.

M-x org-agenda t(org-todo-list)

显示全局TODO列表。Collects the TODO items (with not-DONE states) from all agenda files (see Agenda Views) into a single buffer. The new buffer is in Org Agenda mode, which provides commands to examine and manipulate the TODO entries from the new buffer (see Agenda Commands). See Global TODO list, for more information.

S-M-RET (org-insert-todo-heading)

Insert a new TODO entry below the current one.

Changing a TODO state can also trigger tag changes. See the docstring of the option org-todo-state-tags-triggers for details.

5.2TODO关键字的扩展使用

By default, marked TODO entries have one of only two states: TODO and DONE. Org mode allows you to classify TODO items in more complex ways with TODO keywords (stored in org-todo-keywords). With special setup, the TODO keyword system can work differently in different files.

Note that tags are another way to classify headlines in general and TODO items in particular (see Tags).

5.2.1TODO关键字作为工作流状态

You can use TODO keywords to indicate different, possibly sequential states in the process of working on an item, for example³⁶:

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

The vertical bar separates the TODO keywords (states that need action) from the DONE states (which need no further action). If you do not provide the separator bar, the last state is used as the DONE state.

With this setup, the command C-c C-t cycles an entry from ‘TODO’ to ‘FEEDBACK’, then to ‘VERIFY’, and finally to ‘DONE’ and ‘DELEGATED’. You may also use a numeric prefix argument to quickly select a specific state. For example C-3 C-c C-t changes the state immediately to ‘VERIFY’. Or you can use S-RIGHT and S-LEFT to go forward and backward through the states. If you define many keywords, you can use in-buffer completion (see Completion) or a special one-key selection scheme (see Fast access to TODO states) to insert these words into the buffer. Changing a TODO state can be logged with a timestamp, see Tracking TODO state changes, for more information.

5.2.2TODO关键字作为类型

The second possibility is to use TODO keywords to indicate different types of action items. For example, you might want to indicate that items are for “work” or “home”. Or, when you work with several people on a single project, you might want to assign action items directly to persons, by using their names as TODO keywords. This type of functionality is actually much better served by using tags (see Tags), so the TODO implementation is kept just for backward compatibility.

Using TODO types, it would be set up like this:

(setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE")))

In this case, different keywords do not indicate states, but rather different types. So the normal work flow would be to assign a task to a person, and later to mark it DONE. Org mode supports this style by adapting the workings of the command C-c C-t³⁷. When used several times in succession, it still cycles through all names, in order to first select the right type for a task. But when you return to the item after some time and execute C-c C-t again, it will switch from any name directly to ‘DONE’. Use prefix arguments or completion to quickly select a specific name. You can also review the items of a specific TODO type in a sparse tree by using a numeric prefix to C-c / t. For example, to see all things Lucy has to do, you would use C-3 C-c / t. To collect Lucy’s items from all agenda files into a single buffer, you would use the numeric prefix argument as well when creating the global TODO list: C-3 M-x org-agenda t.

5.2.3一个文件中的多个关键字集

Sometimes you may want to use different sets of TODO keywords in parallel. For example, you may want to have the basic TODO/DONE, but also a workflow for bug fixing, and a separate state indicating that an item has been canceled—so it is not DONE, but also does not require action. Your setup would then look like this:

(setq org-todo-keywords
      '((sequence "TODO" "|" "DONE")
        (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED")
        (sequence "|" "CANCELED")))

The keywords should all be different, this helps Org mode keep track of which subsequence should be used for a given entry. In this setup, C-c C-t only operates within a sub-sequence, so it switches from ‘DONE’ to (nothing) to ‘TODO’, and from ‘FIXED’ to (nothing) to ‘REPORT’. Therefore you need a mechanism to initially select the correct sequence. In addition to typing a keyword or using completion (see Completion), you may also apply the following commands:

C-u C-u C-c C-t

C-S-RIGHT

C-S-LEFT

These keys jump from one TODO sub-sequence to the next. In the above example, C-u C-u C-c C-t or C-S-RIGHT would jump from ‘TODO’ or ‘DONE’ to ‘REPORT’, and any of the words in the second row to ‘CANCELED’. Note that the C-S- key binding conflict with shift-selection (see Conflicts).

S-RIGHT

S-LEFT

S-LEFT and S-RIGHT walk through all keywords from all sub-sequences, so for example S-RIGHT would switch from ‘DONE’ to ‘REPORT’ in the example above. For a discussion of the interaction with shift-selection, see Conflicts.

5.2.4快速访问TODO状态

If you would like to quickly change an entry to an arbitrary TODO state instead of cycling through the states, you can set up keys for single-letter access to the states. This is done by adding the selection character after each keyword, in parentheses³⁸. 例如：

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

If you then press C-c C-t followed by the selection key, the entry is switched to this state. SPC can be used to remove any TODO keyword from an entry³⁹.

5.2.5设置单个文件的关键字

It can be very useful to use different aspects of the TODO mechanism in different files. For file-local settings, you need to add special lines to the file which set the keywords and interpretation for that file only. For example, to set one of the two examples discussed above, you need one of the following lines, starting in column zero anywhere in the file:

#+TODO: TODO FEEDBACK VERIFY | DONE CANCELED

You may also write ‘#+SEQ_TODO’ to be explicit about the interpretation, but it means the same as ‘#+TODO’, or

#+TYP_TODO: Fred Sara Lucy Mike | DONE

A setup for using several sets in parallel would be:

#+TODO: TODO | DONE
#+TODO: REPORT BUG KNOWNCAUSE | FIXED
#+TODO: | CANCELED

To make sure you are using the correct keyword, type ‘#+’ into the buffer and then use M-TAB to complete it (see Completion).

Remember that the keywords after the vertical bar—or the last keyword if no bar is there—must always mean that the item is DONE, although you may use a different word. After changing one of these lines, use C-c C-c with point still in the line to make the changes known to Org mode⁴⁰.

5.2.6TODO关键字的字符样式

Org mode highlights TODO keywords with special faces: org-todo for keywords indicating that an item still has to be acted upon, and org-done for keywords indicating that an item is finished. If you are using more than two different states, you might want to use special faces for some of them. This can be done using the variable org-todo-keyword-faces. 例如：

(setq org-todo-keyword-faces
      '(("TODO" . org-warning) ("STARTED" . "yellow")
        ("CANCELED" . (:foreground "blue" :weight bold))))

While using a list with face properties as shown for ‘CANCELED’ should work, this does not always seem to be the case. If necessary, define a special face and use that. A string is interpreted as a color. The variable org-faces-easy-properties determines if that color is interpreted as a foreground or a background color.

5.2.7TODO依赖关系

The structure of Org files—hierarchy and lists—makes it easy to define TODO dependencies. Usually, a parent TODO task should not be marked as done until all TODO subtasks, or children tasks, are marked as done. Sometimes there is a logical sequence to (sub)tasks, so that one subtask cannot be acted upon before all siblings above it have been marked as done. If you customize the variable org-enforce-todo-dependencies, Org blocks entries from changing state to DONE while they have TODO children that are not DONE. Furthermore, if an entry has a property ‘ORDERED’, each of its TODO children is blocked until all earlier siblings are marked as done. Here is an example:

* TODO Blocked until (two) is done
** DONE one
** TODO two

* Parent
:PROPERTIES:
:ORDERED:  t
:END:
** TODO a
** TODO b, needs to wait for (a)
** TODO c, needs to wait for (a) and (b)

You can ensure an entry is never blocked by using the ‘NOBLOCKING’ property (see Properties and Columns):

* This entry is never blocked
:PROPERTIES:
:NOBLOCKING: t
:END:

C-c C-x o (org-toggle-ordered-property)

Toggle the ‘ORDERED’ property of the current entry. A property is used for this behavior because this should be local to the current entry, not inherited from entries above like a tag (see Tags). However, if you would like to track the value of this property with a tag for better visibility, customize the variable org-track-ordered-property-with-tag.

C-u C-u C-u C-c C-t

Change TODO state, regardless of any state blocking.

If you set the variable org-agenda-dim-blocked-tasks, TODO entries that cannot be marked as done because of unmarked children are shown in a dimmed font or even made invisible in agenda views (see Agenda Views).

You can also block changes of TODO states by using checkboxes (see Checkboxes). If you set the variable org-enforce-todo-checkbox-dependencies, an entry that has unchecked checkboxes is blocked from switching to DONE.

If you need more complex dependency structures, for example dependencies between entries in different trees or files, check out the contributed module ‘org-depend.el’.

5.3进度日志记录

To record a timestamp and a note when changing a TODO state, call the command org-todo with a prefix argument.

C-u C-c C-t (org-todo)

Prompt for a note and record a the time of the TODO state change. The note is inserted as a list item below the headline, but can also be placed into a drawer, see Tracking TODO state changes.

If you want to be more systematic, Org mode can automatically record a timestamp and optionally a note when you mark a TODO item as DONE, or even each time you change the state of a TODO item. This system is highly configurable, settings can be on a per-keyword basis and can be localized to a file or even a subtree. For information on how to clock working time for a task, see Clocking Work Time.

5.3.1关闭项

The most basic automatic logging is to keep track of when a certain TODO item was marked as done. This can be achieved with⁴¹

(setq org-log-done 'time)

Then each time you turn an entry from a TODO (not-done) state into any of the DONE states, a line ‘CLOSED: [timestamp]’ is inserted just after the headline. If you turn the entry back into a TODO item through further state cycling, that line is removed again. If you turn the entry back to a non-TODO state (by pressing C-c C-t SPC for example), that line is also removed, unless you set org-closed-keep-when-no-todo to non-nil. If you want to record a note along with the timestamp, use⁴²

(setq org-log-done 'note)

You are then prompted for a note, and that note is stored below the entry with a ‘Closing Note’ heading.

5.3.2跟踪TODO状态更改

You might want to automatically keep track of when a state change occurred and maybe take a note about this change. You can either record just a timestamp, or a time-stamped note. These records are inserted after the headline as an itemized list, newest first⁴³. When taking a lot of notes, you might want to get the notes out of the way into a drawer (see Drawers). Customize the variable org-log-into-drawer to get this behavior—the recommended drawer for this is called ‘LOGBOOK’⁴⁴. You can also overrule the setting of this variable for a subtree by setting a ‘LOG_INTO_DRAWER’ property.

Since it is normally too much to record a note for every state, Org mode expects configuration on a per-keyword basis for this. This is achieved by adding special markers ‘!’ (for a timestamp) or ‘@’ (for a note with timestamp) in parentheses after each keyword. For example, with the setting

(setq org-todo-keywords
      '((sequence "TODO(t)" "WAIT(w@/!)" "|" "DONE(d!)" "CANCELED(c@)")))

To record a timestamp without a note for TODO keywords configured with ‘@’, just type C-c C-c to enter a blank note when prompted.

You not only define global TODO keywords and fast access keys, but also request that a time is recorded when the entry is set to ‘DONE’, and that a note is recorded when switching to ‘WAIT’ or ‘CANCELED’⁴⁵. The setting for ‘WAIT’ is even more special: the ‘!’ after the slash means that in addition to the note taken when entering the state, a timestamp should be recorded when leaving the ‘WAIT’ state, if and only if the target state does not configure logging for entering it. So it has no effect when switching from ‘WAIT’ to ‘DONE’, because ‘DONE’ is configured to record a timestamp only. But when switching from ‘WAIT’ back to ‘TODO’, the ‘/!’ in the ‘WAIT’ setting now triggers a timestamp even though ‘TODO’ has no logging configured.

You can use the exact same syntax for setting logging preferences local to a buffer:

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

In order to define logging settings that are local to a subtree or a single item, define a ‘LOGGING’ property in this entry. Any non-empty ‘LOGGING’ property resets all logging settings to nil. You may then turn on logging for this specific tree using ‘STARTUP’ keywords like ‘lognotedone’ or ‘logrepeat’, as well as adding state specific settings like ‘TODO(!)’. 例如：

* TODO Log each state with only a time
  :PROPERTIES:
  :LOGGING: TODO(!) WAIT(!) DONE(!) CANCELED(!)
  :END:
* TODO Only log when switching to WAIT, and when repeating
  :PROPERTIES:
  :LOGGING: WAIT(@) logrepeat
  :END:
* TODO No logging at all
  :PROPERTIES:
  :LOGGING: nil
  :END:

5.3.3追踪你的习惯

Org has the ability to track the consistency of a special category of TODO, called “habits.” To use habits, you have to enable the habits module by customizing the variable org-modules.

A habit has the following properties:

1. The habit is a TODO item, with a TODO keyword representing an open state.
2. The property ‘STYLE’ is set to the value ‘habit’ (see Properties and Columns).
3. The TODO has a scheduled date, usually with a ‘.+’ style repeat interval. A ‘++’ style may be appropriate for habits with time constraints, e.g., must be done on weekends, or a ‘+’ style for an unusual habit that can have a backlog, e.g., weekly reports.
4. The TODO may also have minimum and maximum ranges specified by using the syntax ‘.+2d/3d’, which says that you want to do the task at least every three days, but at most every two days.
5. State logging for the DONE state is enabled (see Tracking TODO state changes), in order for historical data to be represented in the consistency graph. If it is not enabled it is not an error, but the consistency graphs are largely meaningless.

To give you an idea of what the above rules look like in action, here’s an actual habit with some history:

** TODO Shave
   SCHEDULED: <2009-10-17 Sat .+2d/4d>
   :PROPERTIES:
   :STYLE:    habit
   :LAST_REPEAT: [2009-10-19 Mon 00:36]
   :END:
   - State "DONE"       from "TODO"       [2009-10-15 Thu]
   - State "DONE"       from "TODO"       [2009-10-12 Mon]
   - State "DONE"       from "TODO"       [2009-10-10 Sat]
   - State "DONE"       from "TODO"       [2009-10-04 Sun]
   - State "DONE"       from "TODO"       [2009-10-02 Fri]
   - State "DONE"       from "TODO"       [2009-09-29 Tue]
   - State "DONE"       from "TODO"       [2009-09-25 Fri]
   - State "DONE"       from "TODO"       [2009-09-19 Sat]
   - State "DONE"       from "TODO"       [2009-09-16 Wed]
   - State "DONE"       from "TODO"       [2009-09-12 Sat]

What this habit says is: I want to shave at most every 2 days—given by the ‘SCHEDULED’ date and repeat interval—and at least every 4 days. If today is the 15th, then the habit first appears in the agenda (see Agenda Views) on Oct 17, after the minimum of 2 days has elapsed, and will appear overdue on Oct 19, after four days have elapsed.

What’s really useful about habits is that they are displayed along with a consistency graph, to show how consistent you’ve been at getting that task done in the past. This graph shows every day that the task was done over the past three weeks, with colors for each day. The colors used are:

Blue

If the task was not to be done yet on that day.

Green

If the task could have been done on that day.

Yellow

If the task was going to be overdue the next day.

Red

If the task was overdue on that day.

In addition to coloring each day, the day is also marked with an asterisk if the task was actually done that day, and an exclamation mark to show where the current day falls in the graph.

There are several configuration variables that can be used to change the way habits are displayed in the agenda.

org-habit-graph-column

The buffer column at which the consistency graph should be drawn. This overwrites any text in that column, so it is a good idea to keep your habits’ titles brief and to the point.

org-habit-preceding-days

The amount of history, in days before today, to appear in consistency graphs.

org-habit-following-days

The number of days after today that appear in consistency graphs.

org-habit-show-habits-only-for-today

If non-nil, only show habits in today’s agenda view. The default value is t. Pressing C-u K in the agenda toggles this variable.

Lastly, pressing K in the agenda buffer causes habits to temporarily be disabled and do not appear at all. Press K again to bring them back. They are also subject to tag filtering, if you have habits which should only be done in certain contexts, for example.

5.4优先顺序

If you use Org mode extensively, you may end up with enough TODO items that it starts to make sense to prioritize them. Prioritizing can be done by placing a priority cookie into the headline of a TODO item right after the TODO keyword, like this:

*** TODO [#A] Write letter to Sam Fortune

By default, Org mode supports three priorities: ‘A’, ‘B’, and ‘C’. ‘A’ is the highest priority. An entry without a cookie is treated as equivalent if it had priority ‘B’. Priorities make a difference only for sorting in the agenda (see Weekly/daily agenda). Outside the agenda, they have no inherent meaning to Org mode. The cookies are displayed with the face defined by the variable org-priority-faces, which can be customized.

You can also use numeric values for priorities, such as

*** TODO [#1] Write letter to Sam Fortune

When using numeric priorities, you need to set org-priority-highest, org-priority-lowest and org-priority-default to integers, which must all be strictly inferior to 65.

Priorities can be attached to any outline node; they do not need to be TODO items.

C-c , (org-priority)

Set the priority of the current headline. The command prompts for a priority character ‘A’, ‘B’ or ‘C’. When you press SPC instead, the priority cookie, if one is set, is removed from the headline. The priorities can also be changed “remotely” from the agenda buffer with the , command (see Agenda Commands).

S-UP (org-priority-up)

S-DOWN (org-priority-down)

Increase/decrease the priority of the current headline⁴⁶. Note that these keys are also used to modify timestamps (see Creating Timestamps). See also Conflicts, for a discussion of the interaction with shift-selection.

You can change the range of allowed priorities by setting the variables org-priority-highest, org-priority-lowest, and org-priority-default. For an individual buffer, you may set these values (highest, lowest, default) like this (please make sure that the highest priority is earlier in the alphabet than the lowest priority):

#+PRIORITIES: A C B

Or, using numeric values:

#+PRIORITIES: 1 10 5

5.5将任务分解为子任务

It is often advisable to break down large tasks into smaller, manageable subtasks. You can do this by creating an outline tree below a TODO item, with detailed subtasks on the tree⁴⁷. To keep an overview of the fraction of subtasks that have already been marked as done, insert either ‘[/]’ or ‘[%]’ anywhere in the headline. These cookies are updated each time the TODO status of a child changes, or when pressing C-c C-c on the cookie. 例如：

* Organize Party [33%]
** TODO Call people [1/2]
*** TODO Peter
*** DONE Sarah
** TODO Buy food
** DONE Talk to neighbor

If a heading has both checkboxes and TODO children below it, the meaning of the statistics cookie become ambiguous. Set the property ‘COOKIE_DATA’ to either ‘checkbox’ or ‘todo’ to resolve this issue.

If you would like to have the statistics cookie count any TODO entries in the subtree (not just direct children), configure the variable org-hierarchical-todo-statistics. To do this for a single subtree, include the word ‘recursive’ into the value of the ‘COOKIE_DATA’ property.

* Parent capturing statistics [2/20]
  :PROPERTIES:
  :COOKIE_DATA: todo recursive
  :END:

If you would like a TODO entry to automatically change to DONE when all children are done, you can use the following setup:

(defun org-summary-todo (n-done n-not-done)
  "Switch entry to DONE when all subentries are done, to TODO otherwise."
  (let (org-log-done org-log-states)   ; turn off logging
    (org-todo (if (= n-not-done 0) "DONE" "TODO"))))

(add-hook 'org-after-todo-statistics-hook 'org-summary-todo)

Another possibility is the use of checkboxes to identify (a hierarchy of) a large number of subtasks (see Checkboxes).

5.6复选框

Every item in a plain list⁴⁸ (see Plain Lists) can be made into a checkbox by starting it with the string ‘[ ]’. This feature is similar to TODO items (see TODO Items), but is more lightweight. Checkboxes are not included into the global TODO list, so they are often great to split a task into a number of simple steps. Or you can use them in a shopping list.

Here is an example of a checkbox list.

* TODO Organize party [2/4]
  - [-] call people [1/3]
    - [ ] Peter
    - [X] Sarah
    - [ ] Sam
  - [X] order food
  - [ ] think about what music to play
  - [X] talk to the neighbors

Checkboxes work hierarchically, so if a checkbox item has children that are checkboxes, toggling one of the children checkboxes makes the parent checkbox reflect if none, some, or all of the children are checked.

The ‘[2/4]’ and ‘[1/3]’ in the first and second line are cookies indicating how many checkboxes present in this entry have been checked off, and the total number of checkboxes present. This can give you an idea on how many checkboxes remain, even without opening a folded entry. The cookies can be placed into a headline or into (the first line of) a plain list item. Each cookie covers checkboxes of direct children structurally below the headline/item on which the cookie appears⁴⁹. You have to insert the cookie yourself by typing either ‘[/]’ or ‘[%]’. With ‘[/]’ you get an ‘n out of m’ result, as in the examples above. With ‘[%]’ you get information about the percentage of checkboxes checked (in the above example, this would be ‘[50%]’ and ‘[33%]’, respectively). In a headline, a cookie can count either checkboxes below the heading or TODO states of children, and it displays whatever was changed last. Set the property ‘COOKIE_DATA’ to either ‘checkbox’ or ‘todo’ to resolve this issue.

If the current outline node has an ‘ORDERED’ property, checkboxes must be checked off in sequence, and an error is thrown if you try to check off a box while there are unchecked boxes above it.

The following commands work with checkboxes:

C-c C-c (org-toggle-checkbox)

Toggle checkbox status or—with prefix argument—checkbox presence at point. With a single prefix argument, add an empty checkbox or remove the current one⁵⁰. With a double prefix argument, set it to ‘[-]’, which is considered to be an intermediate state.

C-c C-x C-b (org-toggle-checkbox)

Toggle checkbox status or—with prefix argument—checkbox presence at point. With double prefix argument, set it to ‘[-]’, which is considered to be an intermediate state.

• If there is an active region, toggle the first checkbox in the region and set all remaining boxes to the same status as the first. With a prefix argument, add or remove the checkbox for all items in the region.
• If point is in a headline, toggle checkboxes in the region between this headline and the next—so not the entire subtree.
• If there is no active region, just toggle the checkbox at point.

C-c C-x C-r (org-toggle-radio-button)

Toggle checkbox status by using the checkbox of the item at point as a radio button: when the checkbox is turned on, all other checkboxes on the same level will be turned off. With a universal prefix argument, toggle the presence of the checkbox. With a double prefix argument, set it to ‘[-]’.

C-c C-c can be told to consider checkboxes as radio buttons by setting ‘#+ATTR_ORG: :radio t’ right before the list or by calling M-x org-list-checkbox-radio-mode to activate this minor mode.

M-S-RET (org-insert-todo-heading)

Insert a new item with a checkbox. This works only if point is already in a plain list item (see Plain Lists).

C-c C-x o (org-toggle-ordered-property)

Toggle the ‘ORDERED’ property of the entry, to toggle if checkboxes must be checked off in sequence. A property is used for this behavior because this should be local to the current entry, not inherited like a tag. However, if you would like to track the value of this property with a tag for better visibility, customize org-track-ordered-property-with-tag.

C-c # (org-update-statistics-cookies)

Update the statistics cookie in the current outline entry. When called with a C-u prefix, update the entire file. Checkbox statistic cookies are updated automatically if you toggle checkboxes with C-c C-c and make new ones with M-S-RET. TODO statistics cookies update when changing TODO states. If you delete boxes/entries or add/change them by hand, use this command to get things back into sync.

6 标签

实现交叉关联信息的标注和上下文的一个很好的方法是将标签分配给标题。Org mode对标签有广泛的支持。

每个标题都可以包含一个标签列表；它们出现在标题的末尾。标签是包含字母、数字、“_”和“@”的普通单词。标签必须前后各有一个冒号，例如，“:work:”。可以指定几个标签，如“:work:ururent:”。默认情况下，标签以粗体显示，颜色与标题相同。您可以使用变量org-tag-faces为特定标签指定特殊的字符样式，方法与为TODO关键字指定的方式大致相同(请参阅为TODO关键字设置字符样式)。

6.1标签继承

标签利用大纲树的层次结构。如果标题具有某个标签，则所有子标题也会继承该标签。例如，在列表中

* Meeting with the French group      :work:
** Summary by Frank                  :boss:notes:
*** TODO Prepare slides for him      :action:

最后一个标题将具有标签“work”、“boss”、“notes”和“action”，即使最后一个标题没有用这些标签显式标签。您还可以设置文件中的所有条目都应该继承的标签，就像这些标签是在围绕整个文件的假设级别0中定义的一样。使用这样的行⁵¹

#+FILETAGS: :Peter:Boss:Secret:

要将标签继承限制为特定标签，或将其完全关闭，请使用变量org-use-tag-inheritation和org-tag-exclude-from-heritation。

如果在打开标记继承的情况下在标签搜索期间匹配标题，则同一树中的所有子级别(对于简单匹配表单)也会匹配⁵²。然后，匹配的列表可能会变得非常长。如果您只希望看到子树优先的标签匹配，请配置变量org-tag-Match-list-subblelevel(不推荐)。

当议程搜索尝试匹配标签或标签-待办事项议程类型中的标签时，标签继承是相关的。在其他议程类型中，org-use-tag-inheritance的设置无效。不过，您可能希望在议程中正确设置标签，以便标记过滤可以很好地处理继承的标签。设置org-agenda-use-tag-inheritance来控制这一点：默认值包括所有议程类型，但是将其设置为nil可以真正加快议程生成的速度。

6.2设置标签

只需在缓冲区中的标题末尾键入标签即可。冒号之后，M-TAB提供标签的补全。还有一个用于插入标签的特殊命令：

C-c C-q (org-set-tags-command)

为当前标题输入新标签。组织模式提供完成或特殊的单键界面来设置标签，如下所示。按RET后，将插入标签并与org-tag-column对齐。当使用C-u前缀调用时，当前缓冲区中的所有标签都与该列对齐，这只是为了让事情看起来更好看。标签在升级、降级和待办事项状态更改后自动重新对齐(请参阅TODO基础知识)。

C-c C-c (org-set-tags-command)

当光标位于标题中时，其作用与C-c C-q相同。

Org支持基于标签列表的标签插入。默认情况下，此列表是动态构建的，包含缓冲区⁵³中当前使用的所有标签。您还可以使用变量org-tag-ist全局指定标签的硬列表。最后，您可以使用“TAGS”关键字为给定文件设置默认标签，如

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

如果您已使用变量org-tag-ist全局定义了首选的标签集，但希望在特定文件中使用动态标签列表，请向该文件添加空的“TAGS”关键字：

#+TAGS:

除了由“TAGS”关键字在每个文件基础上定义的标签之外，如果您有希望在每个文件中使用的首选标签集，则可以使用变量org-tag-persistent-alist指定标签列表。您可以通过将“STARTUP”关键字添加到该文件来逐个文件关闭此功能：

#+STARTUP: noptag

默认情况下，Org mode使用标准的迷你缓冲区完成功能来输入标签。但是，它还实现了另一种更快的标签选择方法，称为快速标记选择。这使您只需按一次键即可选择和取消选择标签。要使其正常工作，您应该为大多数常用的标签分配唯一的字母。您可以通过在Emacs init文件中配置变量org-tag-ist来全局执行此操作。例如，您可能会发现需要用“@home”标记不同文件中的许多项目。在这种情况下，您可以设置如下内容：

(setq org-tag-alist '(("@work" . ?w) ("@home" . ?h) ("laptop" . ?l)))

如果标签仅与您正在处理的文件相关，则可以将“TAGS”关键字设置为：

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

标签界面在启动窗口中显示可用标签。如果要在特定标签后开始新行，请在标签列表中插入“\n”

#+TAGS: @work(w) @home(h) @tennisclub(t) \n laptop(l) pc(p)

或者将它们写成两行：

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

还可以使用大括号将互斥的标记组合在一起，如在以下内容中所示：

#+TAGS: { @work(w)  @home(h)  @tennisclub(t) }  laptop(l)  pc(p)

您指示最多应选择“@work”、“@home”和“@tennisClub”中的一个。允许多个这样的组。

不要忘记将光标放在这些行中的一行上按C-c-c以激活任何更改。

要在变量org-tag-ist中设置这些互斥的组，必须使用虚拟标签:startgroup和:endgroup，而不是大括号。同样，您可以使用:newline来指示换行符。前面的示例将通过以下配置进行全局设置：

(setq org-tag-alist '((:startgroup . nil)
                      ("@work" . ?w) ("@home" . ?h)
                      ("@tennisclub" . ?t)
                      (:endgroup . nil)
                      ("laptop" . ?l) ("pc" . ?p)))

如果至少有一个标签有选择键，则按C-c C-c会自动显示一个特殊界面，其中列出继承的标签、当前标题的标签以及具有相应键的所有有效标签的列表⁵⁴。

按分配给标签的键可以在当前行的标签列表中添加或删除它们。选择一组互斥标签中的标签将关闭该组中的任何其他标签。

在此界面中，您还可以使用以下专用键：

TAB

在迷你缓冲区中输入标签，即使该标签不在预定义列表中也是如此。您可以补全缓冲区中存在的所有标记。您还可以添加几个标记：只需用逗号分隔它们。

SPC

清除此行的所有标记。

RET

接受修改后的集合。

C-g

在不安装更改的情况下中止。

q

如果q未分配给标记，它将像C-g一样中止。

!

关闭互斥标记组。使用此选项(作为例外)从这样的组中分配多个标记。

C-c

在下一次更改后切换自动退出(见下文)。如果您使用的是专家模式，则第一个C-c将显示选择窗口。

此方法允许您使用很少的键将标签分配给标题。使用上面的设置，您可以清除当前标签，并仅使用以下键设置‘@home’、‘Laptop’和‘pc’标记：C-c-cSPCh l pRET。从“@home”切换到“@work”将使用C-c C-c wRET或使用C-c w进行切换。可以使用C-c-cTABs a r a hret添加非预定义标签arah’。

如果您发现大多数情况下只需要按一次键来修改标签列表，那么可以设置变量org-fast-tag-election-single-key。然后，您不必再按RET退出快速标签选择-它在第一次更改后退出。如果您偶尔需要更多键，请按C-c关闭当前标签选择过程的自动退出(实际上：使用C-c-c C-c而不是C-c C-c开始选择)。如果将变量设置为值expert，则甚至不会显示用于单键标签选择的特殊窗口，只有当您额外按C-c时才会出现该窗口。

6.3标签层次结构

Tags can be defined in hierarchies. A tag can be defined as a group tag for a set of other tags. The group tag can be seen as the “broader term” for its set of tags. Defining multiple group tags and nesting them creates a tag hierarchy.

One use-case is to create a taxonomy of terms (tags) that can be used to classify nodes in a document or set of documents.

When you search for a group tag, it return matches for all members in the group and its subgroups. In an agenda view, filtering by a group tag displays or hide headlines tagged with at least one of the members of the group or any of its subgroups. This makes tag searches and filters even more flexible.

You can set group tags by using brackets and inserting a colon between the group tag and its related tags—beware that all whitespaces are mandatory so that Org can parse this line correctly:

#+TAGS: [ GTD : Control Persp ]

In this example, ‘GTD’ is the group tag and it is related to two other tags: ‘Control’, ‘Persp’. Defining ‘Control’ and ‘Persp’ as group tags creates a hierarchy of tags:

#+TAGS: [ Control : Context Task ]
#+TAGS: [ Persp : Vision Goal AOF Project ]

That can conceptually be seen as a hierarchy of tags:

• ‘GTD’
  • ‘Persp’
    • ‘Vision’
    • ‘Goal’
    • ‘AOF’
    • ‘Project’
  • ‘Control’
    • ‘Context’
    • ‘Task’

You can use the :startgrouptag, :grouptags and :endgrouptag keyword directly when setting org-tag-alist directly:

(setq org-tag-alist '((:startgrouptag)
                      ("GTD")
                      (:grouptags)
                      ("Control")
                      ("Persp")
                      (:endgrouptag)
                      (:startgrouptag)
                      ("Control")
                      (:grouptags)
                      ("Context")
                      ("Task")
                      (:endgrouptag)))

The tags in a group can be mutually exclusive if using the same group syntax as is used for grouping mutually exclusive tags together; using curly brackets.

#+TAGS: { Context : @Home @Work @Call }

When setting org-tag-alist you can use :startgroup and :endgroup instead of :startgrouptag and :endgrouptag to make the tags mutually exclusive.

Furthermore, the members of a group tag can also be regular expressions, creating the possibility of a more dynamic and rule-based tag structure. The regular expressions in the group must be specified within curly brackets. Here is an expanded example:

#+TAGS: [ Vision : {V@.+} ]
#+TAGS: [ Goal : {G@.+} ]
#+TAGS: [ AOF : {AOF@.+} ]
#+TAGS: [ Project : {P@.+} ]

Searching for the tag ‘Project’ now lists all tags also including regular expression matches for ‘P@.+’, and similarly for tag searches on ‘Vision’, ‘Goal’ and ‘AOF’. For example, this would work well for a project tagged with a common project-identifier, e.g., ‘P@2014_OrgTags’.

If you want to ignore group tags temporarily, toggle group tags support with org-toggle-tags-groups, bound to C-c C-x q. If you want to disable tag groups completely, set org-group-tags to nil.

6.4标签搜索

Once a system of tags has been set up, it can be used to collect related information into special lists.

C-c / m or C-c \ (org-match-sparse-tree)

Create a sparse tree with all headlines matching a tags search. With a C-u prefix argument, ignore headlines that are not a TODO line.

M-x org-agenda m）（org-tags-view）

Create a global list of tag matches from all agenda files. See Matching tags and properties.

M-x org-agenda M(org-tags-view).

Create a global list of tag matches from all agenda files, but check only TODO items and force checking subitems (see the option org-tags-match-list-sublevels).

These commands all prompt for a match string which allows basic Boolean logic like ‘+boss+urgent-project1’, to find entries with tags ‘boss’ and ‘urgent’, but not ‘project1’, or ‘Kathy|Sally’ to find entries which are tagged, like ‘Kathy’ or ‘Sally’. The full syntax of the search string is rich and allows also matching against TODO keywords, entry levels and properties. For a complete description with many examples, see Matching tags and properties.

7 属性和列

A property is a key-value pair associated with an entry. Properties can be set so they are associated with a single entry, with every entry in a tree, or with the whole buffer.

There are two main applications for properties in Org mode. First, properties are like tags, but with a value. Imagine maintaining a file where you document bugs and plan releases for a piece of software. Instead of using tags like ‘release_1’, ‘release_2’, you can use a property, say ‘Release’, that in different subtrees has different values, such as ‘1.0’ or ‘2.0’. Second, you can use properties to implement (very basic) database capabilities in an Org buffer. Imagine keeping track of your music CDs, where properties could be things such as the album, artist, date of release, number of tracks, and so on.

Properties can be conveniently edited and viewed in column view (see Column View).

7.1属性语法

Properties are key–value pairs. When they are associated with a single entry or with a tree they need to be inserted into a special drawer (see Drawers) with the name ‘PROPERTIES’, which has to be located right below a headline, and its planning line (see Deadlines and Scheduling) when applicable. Each property is specified on a single line, with the key—surrounded by colons—first, and the value after it. Keys are case-insensitive. Here is an example:

* CD collection
** Classic
*** Goldberg Variations
    :PROPERTIES:
    :Title:     Goldberg Variations
    :Composer:  J.S. Bach
    :Artist:    Glenn Gould
    :Publisher: Deutsche Grammophon
    :NDisks:    1
    :END:

Depending on the value of org-use-property-inheritance, a property set this way is associated either with a single entry, or with the sub-tree defined by the entry, see Property Inheritance.

You may define the allowed values for a particular property ‘Xyz’ by setting a property ‘Xyz_ALL’. This special property is inherited, so if you set it in a level 1 entry, it applies to the entire tree. When allowed values are defined, setting the corresponding property becomes easier and is less prone to typing errors. For the example with the CD collection, we can pre-define publishers and the number of disks in a box like this:

* CD collection
  :PROPERTIES:
  :NDisks_ALL:  1 2 3 4
  :Publisher_ALL: "Deutsche Grammophon" Philips EMI
  :END:

Properties can be inserted on buffer level. That means they apply before the first headline and can be inherited by all entries in a file. Property blocks defined before first headline needs to be located at the top of the buffer, allowing only comments above.

Properties can also be defined using lines like:

#+PROPERTY: NDisks_ALL 1 2 3 4

If you want to add to the value of an existing property, append a ‘+’ to the property name. The following results in the property ‘var’ having the value ‘foo=1 bar=2’.

#+PROPERTY: var  foo=1
#+PROPERTY: var+ bar=2

It is also possible to add to the values of inherited properties. The following results in the ‘Genres’ property having the value ‘Classic Baroque’ under the ‘Goldberg Variations’ subtree.

* CD collection
** Classic
    :PROPERTIES:
    :Genres: Classic
    :END:
*** Goldberg Variations
    :PROPERTIES:
    :Title:     Goldberg Variations
    :Composer:  J.S. Bach
    :Artist:    Glenn Gould
    :Publisher: Deutsche Grammophon
    :NDisks:    1
    :Genres+:   Baroque
    :END:

Note that a property can only have one entry per drawer.

Property values set with the global variable org-global-properties can be inherited by all entries in all Org files.

The following commands help to work with properties:

M-TAB (pcomplete)

After an initial colon in a line, complete property keys. All keys used in the current file are offered as possible completions.

C-c C-x p (org-set-property)

Set a property. This prompts for a property name and a value. If necessary, the property drawer is created as well.

C-u M-x org-insert-drawer

Insert a property drawer into the current entry. The drawer is inserted early in the entry, but after the lines with planning information like deadlines. If before first headline the drawer is inserted at the top of the drawer after any potential comments.

C-c C-c (org-property-action)

With point in a property drawer, this executes property commands.

C-c C-c s (org-set-property)

Set a property in the current entry. Both the property and the value can be inserted using completion.

S-RIGHT (org-property-next-allowed-values)

S-LEFT (org-property-previous-allowed-value)

Switch property at point to the next/previous allowed value.

C-c C-c d (org-delete-property)

Remove a property from the current entry.

C-c C-c D (org-delete-property-globally)

Globally remove a property, from all entries in the current file.

C-c C-c c (org-compute-property-at-point)

Compute the property at point, using the operator and scope from the nearest column format definition.

7.2特殊属性

Special properties provide an alternative access method to Org mode features, like the TODO state or the priority of an entry, discussed in the previous chapters. This interface exists so that you can include these states in a column view (see Column View), or to use them in queries. The following property names are special and should not be used as keys in the properties drawer:

7.3属性搜索

To create sparse trees and special lists with selection based on properties, the same commands are used as for tag searches (see Tag Searches).

C-c / m or C-c \ (org-match-sparse-tree)

Create a sparse tree with all matching entries. With a C-u prefix argument, ignore headlines that are not a TODO line.

M-x org-agenda m）（org-tags-view）

Create a global list of tag/property matches from all agenda files.

M-x org-agenda M(org-tags-view).

Create a global list of tag matches from all agenda files, but check only TODO items and force checking of subitems (see the option org-tags-match-list-sublevels).

The syntax for the search string is described in Matching tags and properties.

There is also a special command for creating sparse trees based on a single property:

C-c / p

Create a sparse tree based on the value of a property. This first prompts for the name of a property, and then for a value. A sparse tree is created with all entries that define this property with the given value. If you enclose the value in curly braces, it is interpreted as a regular expression and matched against the property values.

7.4属性继承

The outline structure of Org documents lends itself to an inheritance model of properties: if the parent in a tree has a certain property, the children can inherit this property. Org mode does not turn this on by default, because it can slow down property searches significantly and is often not needed. However, if you find inheritance useful, you can turn it on by setting the variable org-use-property-inheritance. It may be set to t to make all properties inherited from the parent, to a list of properties that should be inherited, or to a regular expression that matches inherited properties. If a property has the value nil, this is interpreted as an explicit un-define of the property, so that inheritance search stops at this value and returns nil.

Org mode has a few properties for which inheritance is hard-coded, at least for the special applications for which they are used:

COLUMNS

The ‘COLUMNS’ property defines the format of column view (see Column View). It is inherited in the sense that the level where a ‘COLUMNS’ property is defined is used as the starting point for a column view table, independently of the location in the subtree from where columns view is turned on.

CATEGORY

For agenda view, a category set through a ‘CATEGORY’ property applies to the entire subtree.

ARCHIVE

For archiving, the ‘ARCHIVE’ property may define the archive location for the entire subtree (see Moving subtrees).

LOGGING

The ‘LOGGING’ property may define logging settings for an entry or a subtree (see Tracking TODO state changes).

7.5列视图

A great way to view and edit properties in an outline tree is column view. In column view, each outline node is turned into a table row. Columns in this table provide access to properties of the entries. Org mode implements columns by overlaying a tabular structure over the headline of each item. While the headlines have been turned into a table row, you can still change the visibility of the outline tree. For example, you get a compact table by switching to “contents” view—S-TAB S-TAB, or simply c while column view is active—but you can still open, read, and edit the entry below each headline. Or, you can switch to column view after executing a sparse tree command and in this way get a table only for the selected items. Column view also works in agenda buffers (see Agenda Views) where queries have collected selected items, possibly from a number of files.

7.5.1列定义

Setting up a column view first requires defining the columns. This is done by defining a column format line.

7.5.1.1列定义的范围

To specify a format that only applies to a specific tree, add a ‘COLUMNS’ property to the top node of that tree, for example:

** Top node for columns view
   :PROPERTIES:
   :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
   :END:

A ‘COLUMNS’ property within a property drawer before first headline will apply to the entire file. As an addition to property drawers, keywords can also be defined for an entire file using a line like:

#+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO

If a ‘COLUMNS’ property is present in an entry, it defines columns for the entry itself, and for the entire subtree below it. Since the column definition is part of the hierarchical structure of the document, you can define columns on level 1 that are general enough for all sublevels, and more specific columns further down, when you edit a deeper part of the tree.

7.5.1.2列属性

A column definition sets the attributes of a column. The general definition looks like this:

%[WIDTH]PROPERTY[(TITLE)][{SUMMARY-TYPE}]

Except for the percent sign and the property name, all items are optional. The individual parts have the following meaning:

WIDTH

An integer specifying the width of the column in characters. If omitted, the width is determined automatically.

PROPERTY

The property that should be edited in this column. Special properties representing meta data are allowed here as well (see Special Properties).

TITLE

The header text for the column. If omitted, the property name is used.

SUMMARY-TYPE

The summary type. If specified, the column values for parent nodes are computed from the children⁵⁵.

Supported summary types are:

‘+’	Sum numbers in this column.
‘+;%.1f’	Like ‘+’, but format result with ‘%.1f’.
‘$’	Currency, short for ‘+;%.2f’.
‘min’	Smallest number in column.
‘max’	Largest number.
‘mean’	Arithmetic mean of numbers.
‘X’	Checkbox status, ‘[X]’ if all children are ‘[X]’.
‘X/’	Checkbox status, ‘[n/m]’.
‘X%’	Checkbox status, ‘[n%]’.
‘:’	Sum times, HH:MM, plain numbers are minutes.
‘:min’	Smallest time value in column.
‘:max’	Largest time value.
‘:mean’	Arithmetic mean of time values.
‘@min’	Minimum age56 (in days/hours/mins/seconds).
‘@max’	Maximum age (in days/hours/mins/seconds).
‘@mean’	Arithmetic mean of ages (in days/hours/mins/seconds).
‘est+’	Add low-high estimates.

You can also define custom summary types by setting org-columns-summary-types.