(package-install 'org-roam)
(package-install 'org-roam-server)

(setq org-roam-directory "~/Dropbox/org/roam")

(add-hook 'after-init-hook 'org-roam-mode)

(setq org-roam-server-host "127.0.0.1"
      org-roam-server-port 9090
      org-roam-server-export-inline-images t
      org-roam-server-authenticate nil
      org-roam-server-network-label-truncate t
      org-roam-server-network-label-truncate-length 60
      org-roam-server-network-label-wrap-length 20)
(org-roam-server-mode)

(require 'org-roam-protocol)

用 org-roam-find-file/org-roam-capture 新建笔记的时候，会要求我们输入笔记标题，假如我们输入的笔记标题是 "org-roam"，那么会在新建这个笔记后发现这个笔记只在第一行把我们输入的标题写上去了，别的什么都没有：

#+title: org-roam

在实际使用中，我们可能会有不同的笔记需求，比如说：当我为一个专业术语记录笔记时，我想写下这个术语所属的领域以及它的含义；当我记录一个观点时，我会想写上这个观点是谁提出来的、论据是什么、我自己是支持还是反对；当我读一篇深度学习的论文时，我要记录这篇论文的相关工作、要解决的问题、使用了什么方法、进行了怎么样的实验……

这些需求用 org-roam 是能够满足的，因为 org-roam 通过 org-roam-capture-templates 这个变量提供了定制笔记模板的能力。

具体来说，默认的笔记模板是这样的

'(("d" "default" plain (function org-roam-capture--get-point)
   "%?"
   :file-name "%<%Y%m%d%H%M%S>-${slug}"
   :head "#+title: ${title}\n"
   :unnarrowed t))

每个模板都由 8 个部分组成，我这里以上面的默认模板来进行说明

下面对这 8 个模板元素分别说明一下

• 用来选择模板的 key：

  对应默认模板里的 "d"，一个字符的情况下用来直接选择模板，两个字符的情况下用第一个字符表示模板分组、第二个字符用来选择这个分组下的实际模板。

  下面的配置设置了四个模板，其中第二个 ("g" "group") 用来指明一个模板分组，后面的 "ga" 和 "gb" 是这个模板下的子模板。

  (setq org-roam-capture-templates
        '(
          ("d" "default" plain (function org-roam-capture--get-point)
           "%?"
           :file-name "%<%Y%m%d%H%M%S>-${slug}"
           :head "#+title: ${title}\n#+roam_alias:\n\n")
          ("g" "group")
          ("ga" "Group A" plain (function org-roam-capture--get-point)
           "%?"
           :file-name "%<%Y%m%d%H%M%S>-${slug}"
           :head "#+title: ${title}\n#+roam_alias:\n\n")
          ("gb" "Group B" plain (function org-roam-capture--get-point)
           "%?"
           :file-name "%<%Y%m%d%H%M%S>-${slug}"
           :head "#+title: ${title}\n#+roam_alias:\n\n")))
  

  上面的模板生效后，首先在执行 org-roam-find-file 新建笔记时，就会看到一个选择界面，如下图所示：

  

  如果输入 d 会直接打开新建笔记的编辑窗口，如果输入 g 会展开分组模板要求我们再输入一次来选择具体的模板，如下图所示：

  

• 用来描述模板的 description：这个元素就是起到单纯的描述作用，没有功能上的意义
• 用来说明新增内容类型的 type：本来有 plain/entry/item/checkitem/table-line 五种取值，但在 org-roam 中作用都是一样的，建议一律使用 plain
• 用来说明新增内容位置的 target：这一项在 org-roam 中不可更改

• 设置新增内容模板的 template：

  这个元素是整个模板中的核心，其中的内容可以分为两类：

  • 普通的文本，将会原样出现在新增内容中
  • 以 % 开头的特殊标记，如默认模板中的 "%?"，将会在最后根据类型自动扩展成不同的内容

  对于第一类内容没啥可说的，唯一值得一提的是，如果需要模板是多行的文本，需要在模板中用 "\n" 来指明要换行，如模板内容 "第一行\n第二行" 最后就会在笔记中显示为：

  第一行
  第二行
  

  这里说一下以 % 开头的特殊标记，由于这块内容很多，这里只列举一些常用的供读者参考：

  标记	描述
  %<…>	自定义格式的时间戳，如: %<%Y-%m-%d>，会得到 <2018-03-04 日>
  %t	当前日期，展开后的格式固定为 <2018-03-04 日> 这样
  %T	当前日期和时间，展开后的格式固定为 <2018-03-04 日 19:26> 这样
  %u	当前日期，展开后的格式固定为 [2018-03-04 日] 这样
  %U	当前日期和时间，展开后的格式固定为 [2018-03-04 日 19:26] 这样
  %prompt	用 prompt 作为提示要求我们输入并填充在这个模板元素所在的位置
  %?	其他所有特殊标记填充完毕后，光标将停留在这个元素的位置等待我们编辑

• 指定新增笔记文件名的 file-name：

  org-roam 中新建笔记一般都是以一个新文件的形式来创建的，支持用 file-name 来设置这个新文件的文件名，默认模板中的这块设置为 "%<%Y%m%d%H%M%S>-${slug}"，分为两部分

  • %<%Y%m%d%H%M%S> ：参考上一节 template 部分的特殊标记
  • ${slug} ：将笔记标题文字做处理后得到的文本，这些处理包括大写字母转小写、去除一些特殊字符等

  这块建议使用默认模板就好。

• 设置新增笔记初始内容的 head：

  这个设置用来在新建笔记文件时设置初始内容，只会执行一次，也就是说之后如果使用 org-roam-capture 新增内容到已有笔记中时，这个设置的内容是不会再写入到文件中的。

  默认模板这块的内容是 "#+title: ${title}\n"，只设置了笔记文件的标题，建议改为如下内容：

  :head "#+title: ${title}\n#+roam_alias: \n#+roam_tags: \n"
  

  这样设置后新建笔记文件的初始内容将会是：

  #+title: 示例标题
  #+roam_alias:
  #+roam_tags:
  

  "#+roam_alias" 可以给这条笔记设置别名，这样在其他笔记中引用的时候会更方便；"#+roam_tags" 可以用来为这条笔记添加标签，使得在用 org-roam-find-file 查找已有笔记时能根据 tag 来进行过滤。

• 设置新增内容其他属性的 properties：

  这些属性用于对新建笔记内容的行为做一些额外的控制，列举几个常用的：

  • :unnarrowed t: org-roam 推荐的设置，表示现实整个笔记文件，如果不加这个设置，用 org-roam-capture 增加内容到已有笔记文件中时，仅会显示当前我们输入的内容，而不会显示这个笔记文件中已有的内容
  • :empty-lines 1: 在新增的笔记内容前后加一个空行，使用 org-roam-capture 增加内容到已有笔记文件中时比较有用

org-roam 的笔记模板是利用 org-capture 实现的，上述模板元素中 file-name 和 head 是 org-roam 在 org-capture 模板的基础上增加的新元素；其他六个部分，target 在 org-roam 中不可更改，key、description、type 和 template 的更详细说明可以参考我之前写的一篇介绍 org-capture 文章中的相关内容，capture 模板的五个部分。

为了能更直观地理解模板的工作机制，这里给几个模板的示例：

• 用于记录专业术语的模板

  (add-to-list 'org-roam-capture-templates
               '("t" "Term" plain (function org-roam-capture--get-point)
                 "- 领域: %^{术语所属领域}\n- 释义:"
                 :file-name "%<%Y%m%d%H%M%S>-${slug}"
                 :head "#+title: ${title}\n#+roam_alias:\n#+roam_tags: \n\n"
                 :unnarrowed t
                 ))
  

  将上面的配置拷贝到你的 Emacs 配置中，并置于所有 org-roam 相关配置的后面，就可以在你的 org-roam 中使用这个模板，后面的示例模板也是一样，但要注意不同模板的 key 不要有冲突。

  

• 用于记录论文笔记的模板

  (add-to-list 'org-roam-capture-templates
               '("p" "Paper Note" plain (function org-roam-capture--get-point)
                 "* 相关工作\n\n%?\n* 观点\n\n* 模型和方法\n\n* 实验\n\n* 结论\n"
                 :file-name "%<%Y%m%d%H%M%S>-${slug}"
                 :head "#+title: ${title}\n#+roam_alias:\n#+roam_tags: \n\n"
                 :unnarrowed t
                 ))
  

  

另外，org-roam-insert-immediate 不使用 org-roam-capture-templates，而是使用一个专门的 org-roam-capture-immediate-template 来设置新建内容的模板，且只能有一个模板，所以设置这个模板的配置是这样的（以默认配置为例）

(setq org-roam-capture-immediate-template
      '("d" "default" plain (function org-roam-capture--get-point)
        "%?"
        :file-name "%<%Y%m%d%H%M%S>-${slug}"
        :head "#+title: ${title}\n"
        :unnarrowed t))

这部分内容需要 org-protocol，后续内容是在 org-protocol 已经设置好的基础上展开的，如果 org-protocol 设置存在问题，请查阅文档，或这评论区留言来讨论。

利用 org-protocol 这样的外部程序和 Emacs 进行通信的机制，我们可以使用 javascript 来抓取网页上的信息发送到 Emacs 中，而 org-roam 也支持了这种机制。在 org-roam 中可以通过 org-roam-capture-ref-templates 来设置网页捕获相关的模板，默认的设置是这样的：

(setq org-roam-capture-ref-templates
      '(("r" "ref" plain (function org-roam-capture--get-point)
         ""
         :file-name "${slug}"
         :head "#+title: ${title}\n#+roam_key: ${ref}\n"
         :unnarrowed t)))

可以看到，模板本身和前面的笔记模板是一样的，没有什么特别。但我们可以创建一个小书签，来利用这个模板，抓取网页标题和链接然后新建一个笔记到 org-roam 中，如下图所示：

上图中小书签的内容来自 org-roam 的文档，具体内容为：

javascript:location.href = 'org-protocol://roam-ref?template=r&ref=' + encodeURIComponent(location.href) + '&title=' + encodeURIComponent(document.title)

添加的方法是在浏览器中新增一个书签，书签的名字随意（上图中我设置为了“网页抓取”），书签的 URL 填上上面的 javascript 代码。下图是 Firefox 中创建这样的小书签的示意图：

这个小书签的内容分成几部分：

• 第一部分说明小书签要访问的地址，这个就是 org-roam-protocol 的通信地址

  javascript:location.href='org-protocol://roam-ref'
  

• 第二部分指定要使用的笔记模板，从 org-roam-capture-ref-templates 中匹配

  '?template=r'
  

• 第三部分获取一些网页的信息，并设置到变量中，供模板填充使用

  '&ref=' + encodeURIComponent(location.href) + '&title=' + encodeURIComponent(document.title)
  

  前面的默认模板中，head 部分内容为

  :head "#+title: ${title}\n#+roam_key: ${ref}\n"
  

  需要填充 "title" 和 "ref" 两个变量，小书签中第三部分内容就是获取了当前网页的链接赋值给 "ref" 变量，并获取网页标题文本赋值给 "title" 变量了，这样这个模板就能自动填充好了。

不过这个模板和小书签过于简单，只能记录网页链接，我设计了一个模板和对应的小书签，可以做到进行网页标注、摘录，效果见下图：

要达到上图的效果，首先，在 org-roam-capture-ref-templates 中新增一个模板

(add-to-list 'org-roam-capture-ref-templates
             '("a" "Annotation" plain (function org-roam-capture--get-point)
               "%U ${body}\n"
               :file-name "${slug}"
               :head "#+title: ${title}\n#+roam_key: ${ref}\n#+roam_alias:\n"
               :immediate-finish t
               :unnarrowed t))

然后新建一个小书签，内容为

javascript:location.href = 'org-protocol://roam-ref?template=a&ref=' + encodeURIComponent(location.href) + '&title='+encodeURIComponent(document.title) + '&body='+encodeURIComponent(function(){var html = "";var sel = window.getSelection();if (sel.rangeCount) {var container = document.createElement("div");for (var i = 0, len = sel.rangeCount; i < len; ++i) {container.appendChild(sel.getRangeAt(i).cloneContents());}html = container.innerHTML;}var dataDom = document.createElement('div');dataDom.innerHTML = html;['p', 'h1', 'h2', 'h3', 'h4'].forEach(function(tag, idx){dataDom.querySelectorAll(tag).forEach(function(item, index) {var content = item.innerHTML.trim();if (content.length > 0) {item.innerHTML = content + '&#13;&#10;';}});});return dataDom.innerText.trim();}())

'("t" "Task" entry (file+headline "" "Tasks") "* TODO %?\n  %u\n  %a")

(global-set-key (kbd "C-c c") 'org-capture)
(setq org-default-notes-file "~/org/inbox.org")

'("t" "Task" entry (file+headline "" "Tasks") "* TODO %?\n  %u\n  %a")

对应前面默认模板里的 "t"，这个 key 可以是一个或两个字符，用来在执行 org-capture 的时候选择模板 —— 两个字符的情况是用来给模板分组的，第一个字符表示分组名，第二个字符用来选择这个分组下的实际模板。在我们有很多模板的时候，分组是非常有用的，一来可以让执行 org-capture 时显示的可选项更少，而来可以用来组织相近性质的模板以便管理。模板分组稍后一点会做详细说明，此处就先不展开了。

另外，经验证，这里的 key 是支持中文的 XD

对应前面默认模板里的 "Task"，这个就是用来对模板进行描述的，方便我们正确地选择模板。

key 和 description 这两部分会在执行 org-capture 进入模板选择 buffer 后，会显示的内容，其他模板内容在模板选择 buffer 中都是不显示的，如下所示：

这两部分，务必要注意

• 不同模板的 key 不能是一样的
• description 应当尽量清晰以减轻自己的记忆负担

对应前面默认模板里的 "entry"，这个用来设置新增内容的类型，可选的类型如下表所示

根据不同的 type，org-capture 会尝试将新增内容添加到文件中不同类型的数据的后面，比如

• 如果 type 是 item/checkitem，那么会找到目标位置后最近的一个列表，并将新增列表项添加到这个列表的后面
• 如果 type 是 table-line，那么会找到目标位置后最近的一个表格，并将新增行添加到表格的后面

因此对于不同的 type，要求后面的内容模板是按照一定的格式来编写的，下面是不同的 type 对应内容模板的简单示例

• type 为 entry 时，内容模板示例

  "* headline"
  

  也就是说，template 的形式上必须是一个 headline

• type 为 item 时

  如果内容模板为空，会插入一个普通列表项，并且等待输入；如果有需要自定义的内容，那么才需要去写内容模板。

  而此时的内容模板不需要在形式上是一个列表项，也就是说

  "- item"
  

  和

  "item"
  

  的效果是一样的，都会在 target 对应的位置里插入下面这样一个列表项

  - item
  

• type 为 checkitem 时

  与 type 为 item 时行为大部分一样，仅有一点区别，就是在内容模板为空的时候，它会插入一个 checkbox 列表项。

  也就是说，如果内容模板不为空，那么它其实是不保证插入的是 checkbox 列表项的，需要我们自己来保证。

  相应的内容模板应该是类似下面的格式

  "[ ] item"
  

• type 为 table-line，内容模板示例

  "| colum 1 | colum 2 | colum3 |"
  

  就是说，内容模板必须是一个表格的行

对应前面默认模板里的 "(file+headline "" "Tasks")"，target 用来指定

• 新增内容要写入到哪个文件
• 新增内容要写入到文件的什么地方

如前面的默认模板所示，target 部分用一个 list 来表示，其中第一个元素用来表示 target 的类型，可用的类型如下表所示

(翻译有点生硬，如有疑惑，请执行 「M-x describe-variable」并输入「org-capture-templates」查看对应的文档)

其中 file+headline 是比较常用的，用来记录笔记、创建任务一般用这个就好了。不过这个要求 headline 在文件中是唯一的，如果不是唯一的话，最好使用 file+olp，指定对应 headline 在文件中的完整路径。

而 file+datetree、file+weektree 这两种用来创建日志是非常合适的，记录的内容能按年-月-日的层级结构组织好，方便回顾和管理。

如果有自己的特殊需求，那么 file+function、function 这两个也提供了极大的自由扩展的空间。

需要注意的是，上述与文件相关的 target 类型，如果指定了文件名，那么将会优先使用这个文件名而不是变量 org-default-notes-file 指定的文件 —— 反之，如果文件部分留空，那么就会默认使用 org-default-notes-file 指定的文件了。

对应前面默认模板里的 "* TODO %?\n %u\n %a"，这部分的内容是实际上新增内容的模板，通过设置它，我们可以在新增内容时

• 自动插入时间、链接、剪贴板内容、文件内容
• 交互式地要求输入特定内容，如 tag、headline 属性或其他自定义的字段
• 自动插入外部应用传入的特定信息，如浏览器上当前网页的链接、选中的文本等

这部分的配置，其中的内容可以分为两类

• 普通的文本，将会原样出现在新增内容中，如默认模板里的 "* TODO"、"\n"、" "

• 以 % 开头的特殊标记，如 "%?" 和 "%a"，将会在最后根据类型自动扩展成不同的内容

  这些特殊标记包括这些

  • 时间、日期相关

    标记	描述
    %<…>	自定义格式的 timestamp，如: %<%Y-%m-%d>，会得到 <2018-03-04 日>
    %t	当前仅包含日期的 timestamp，如: <2018-03-04 日>
    %T	当前包含日期和时间的 timestamp，如: <2018-03-04 日 19:26>
    %u	当前包含日期的未激活的 timestamp，如: [2018-03-04 日]
    %U	当前包含日期和时间的未激活的 timestamp，如: [2018-03-04 日 19:26]
    %^t	类似 %t，但是弹出日历让用户选择日期
    %^T	类似 %T，但是弹出日历让用户选择日期和时间
    %^u	类似 %u，但是弹出日历让用户选择日期
    %^U	类似 %U，但是弹出日历让用户选择日期和时间

    注: 激活(active)和未激活(inactive)的 timestamp 的区别在于，后者不会出现在 agenda 中 —— 所以如果是新建一个 headline 到 org-agenda-files 中并且不希望它出现在 agenda 列表中时，应当使用未激活的 timestamp。

  • 剪贴板相关

    标记	描述
    %c	当前 kill ring 中的第一条内容
    %x	当前系统剪贴板中的内容
    %^C	交互式地选择 kill ring 或剪贴板中的内容
    %^L	类似 %^C，但是将选中的内容作为链接插入

  • 标签相关

    标记	描述
    %^g	交互式地输入标签，并用 target 所在文件中的标签进行补全
    %^G	类似 %^g，但用所有 org-agenda-files 涉及文件中的标签进行补全

  • 文件相关

    标记	描述
    %[file]	插入文件 file 中的内容
    %f	执行 org-capture 时当前 buffer 对应的文件名
    %F	类似 %f，但输入该文件的绝对路径

  • 任务相关

    标记	描述
    %k	当前在计时的任务的标题
    %K	当前在计时的任务的链接

  • 外部链接的信息

    这里的链接不仅仅指如 http://www.google.com 这样的网页链接，还包括文件、邮箱、新闻组、IRC 会话等，详情见 Org mode 手册的 External links 一节。

    当然在 capture 里我们用不到所有类型的外部链接，从文档和 docstring 来看，在 capture 里能用的外部链接只有下面几种

    link type	description
    bbdb	BBDB 联系人数据库记录链接
    irc	IRC 会话链接
    vm	View Mail 邮件阅读器中的消息、目录链接
    wl	Wunder Lust 邮件/新闻阅读器中的消息、目录链接
    mh	MH-E 邮件用户代理中的消息、目录链接
    mew	MEW 邮件阅读器中的消息链接
    rmail	Emacs 的默认邮件阅读器 Rmail 中的消息链接
    gnus	GNUS 邮件/新闻阅读器中的群组、消息等资源链接
    eww/w3/w3m	在eww/w3/w3m 中存储的网页链接
    calendar	日历链接
    org-protocol	遵循 org-protocol 协议的外部应用链接

    注: 文档的内容来自 org-mode 仓库 中的 doc/org.texi，从 commit 历史来看，可能是过时的；但奇怪的是 org-protocol 明明是支持的，docstring 里却完全没有提及……

    这些外部链接，大部分都会在 Emacs 中通过 org-store-link-pros 记录起来，其中会包含这些链接的各个属性，而在 capture 的模板里面，就支持以 %:keyword 的形式来访问这些属性，比如 vm/wl/mh/mew/rmail/gnus 消息中的发件人名称、发件人地址之类的。因为邮件阅读器这块我个人不怎么用，需要详细了解的请查阅文档，而 calendar 完全可以用前面的「时间、日期相关」中的 %t、%T 等标记来替代，因此这里只详细说一下 eww 和 org-protocol。

    eww 可用的特殊标记有如下三个

    标记	描述
    %:type	固定值，eww
    %:link	页面的链接
    %:description	页面的标题，如无则为页面的链接

    org-protocol 可用的特殊标记有如下六个

    标记	描述
    %:type	链接的类型，如 http/https/ftp 等
    %:link	链接地址，在 org-protocol 里的 url 字段
    %:description	链接的标题，在 org-protocol 里的 title 字段
    %:annotation	靠 url 和 title 完成的 org 格式的链接
    %:initial	链接上选中的文本，在 org-protocol 里的 body 字段
    %:query	org-protocol 上除掉开头和子协议部分的剩下部分

    此外，在内容模板中还支持自定义函数来插入内容，以 %(sexp) 的形式，比如说我们可以自己写一个 get-current-time 函数来插入当前的时间，那么内容模板可以是这个样子的

    "%(get-current-time)"
    

    而在内容模板中使用自定义函数时，可以将上面 eww 和 org-protocol 的这些特殊标记作为函数的参数，比如一个场景是，用 org-protocol 捕获的网页 title 中包含中括号，会导致下面这样的内容模板出错

    "[[%:link][%:description]]"
    

    这个时候可以定一个一个函数来将 %:description 中的中括号替换成下划线

    (defun replace-bracket-in-title (title)
      ;; blablabla
      )
    

    那么上面那个内容模板可以改成这样

    "[[%:link][%(replace-bracket-in-title \"%:description\")]]"
    

  • 其他

    还有一些特殊标记，不太好归类，就在这里罗列一下。

    "%i" 可以插入一段初始化内容，通常是 org-store-link-plist 中 "initial" 属性的值；如果没有的话，会使用当前 buffer 中被选中的内容；都没有的话就什么也不插入。

    "%^{prop}p" 会提示输入内容，这将会在新增内容中插入一个 property 到 target 中，并且这个 property 的名字是 prop，值则是我们输入的文本。

    "%^{prompt}" 则会用 prompt 作为提示符要求我们输入，并且用我们输入的文本替换模板中相应的内容。比如说 "%{姓名}" 会用 "姓名" 作为提示符要求输入。当有多个标记时，可以用 "%\N" 来插入第 N 个提示输入标记产生的内容，举个例子，下面的内容模板

    "- name: %^{姓名}\n- age: %^{年龄}\n\n%\\1的年龄是%\\2"
    

    (注: 此处的反斜线「\」需要转义，否则「\1」会被视作值为 1 的 ASCII 码特殊字符，感谢 Emacs China 网友 slack-py 指出该问题)

    会要求我们输入姓名和年龄，假如我们输入姓名是 "张三"，年龄是 "25"，那么最后得到的内容是

    - name: 张三
    - age: 25
    
    张三的年龄是25
    

    "%?" 是一个更特殊的标记，它不会产生任何内容，当所有其他的特殊标记都展开完毕或者输入完毕后，光标将会停留在这个标记所在的位置。

(setq org-capture-templates nil)

GTD 一般会有一整套系统的设计，这里只讲一下最一般的新建任务的做法，下面是一个新建书籍阅读任务的示例

(add-to-list 'org-capture-templates
             '("r" "Book Reading Task" entry
               (file+olp "~/Dropbox/org/task.org" "Reading" "Book")
               "* TODO %^{书名}\n%u\n%a\n" :clock-in t :clock-resume t))

上面的两个属性 ":clock-in" 和 ":clock-resume" 在之前没有讲过，是用来对新建内容的行为做一些设置的，不影响内容本身。可用的这些属性一共有 14 个，这里及后面只对涉及到的做说明，其他的请查阅文档。

":clock-in" 设置为 t 的时候，会在新建内容时开始计时，这在 GTD 这种场景下是挺有用的。但有可能我们在新建内容时，本来就有一个任务在计时，这种情况下原来的计时会中断掉，这个时候将 ":clock-resume" 设置为 t，可以在新任务完成后，自动恢复原来任务的计时状态。

有些时候我们会对我们需要做的任务做分类，比如上面有一个阅读任务，可能还有工作任务、写作任务，这个时候我们可以利用前面说到的模板分组来更好地进行管理。

在做模板分组前，我们的 org-capture 的任务模板可能是这样的

(add-to-list 'org-capture-templates
             '("r" "Book Reading Task" entry
               (file+olp "~/Dropbox/org/task.org" "Reading" "Book")
               "* TODO %^{书名}\n%u\n%a\n" :clock-in t :clock-resume t))
(add-to-list 'org-capture-templates
             '("w" "Work Task" entry
               (file+headline "~/Dropbox/org/task.org" "Work")
               "* TODO %^{任务名}\n%u\n%a\n" :clock-in t :clock-resume t))

在这个基础上，假设我们要添加一个模板，用来记录从网页上收集的资源、文章的时候，遵循使用描述中关键词的首字母作为选择键的原则，我会希望新建这样一个 capture 模板

(add-to-list 'org-capture-templates
             '("w" "Web Collections" entry
               (file+headline "~/Dropbox/org/inbox.org" "Web")
               "* %U %:annotation\n\n%:initial\n\n%?"))

但这个时候的模板选择键 "w" 和之前任务里的 "Work Task" 就冲突了，为了解决冲突，我只好在其中一个使用小写的 "w" 字母而在另外一个中使用大写的字母 "W"。当我们的模板数量更多时，这种 capture 模板选择键冲突的情况可能会更多。

虽然并不是非常大的问题，但使用模板分组，能尽量地减少这种情况，让我们的模板更加清爽一些

上述情况，我们可以将任务相关的 capture 模板分到一组里，如下所示：

(add-to-list 'org-capture-templates '("t" "Tasks"))
(add-to-list 'org-capture-templates
             '("tr" "Book Reading Task" entry
               (file+olp "~/Dropbox/org/task.org" "Reading" "Book")
               "* TODO %^{书名}\n%u\n%a\n" :clock-in t :clock-resume t))
(add-to-list 'org-capture-templates
             '("tw" "Work Task" entry
               (file+headline "~/Dropbox/org/task.org" "Work")
               "* TODO %^{任务名}\n%u\n%a\n" :clock-in t :clock-resume t))

和前面未分组的模板，有两个不同

• 多了一个只有 key 和 description 而没有 entry/target/template 的 capture 模板，也就是

  (add-to-list 'org-capture-templates '("t" "Tasks"))
  

  这个模板至关重要，它设定了一组模板的名称和选择键前缀。如果缺失了这个模板，那么后面两个模板是不会起作用的。

• 原来的两个任务模板，其选择键多了一个前缀 "t"

一图胜千言，在建立分组前，执行 M-x org-capture 时，弹出的模板选择 buffer 是这个样子的

建立分组后，在模板选择 buffer 里看到的是这个样子

这里只会显示模板的 group 的 key 和 description，等我们按下 t 后才会出来组内所有模板的列表

这个之前也提到过，就是用来做日志记录、日记写作一类的事情，新增的内容和过去的内容都按时间顺序排列，方便我们进行回顾。

做日志记录时，比较推荐用 file+datetree 或者 file+weektree 这两个 target type，当然也不是绝对的，比如说下面这个 capture 模板也是满足基本要求的

(add-to-list 'org-capture-templates
             '("j" "Journal" entry (file "~/Dropbox/org/journal.org")
               "* %U - %^{heading}\n  %?"))

上述模板在每次执行后，在 journal.org 的尾部插入下面这样的内容

* [2018-03-24 六 21:42] - 某件事情的记录

  具体的记录 blablabla

就是如果想要快速地找到某一天或者某一个月的记录，会稍微费力一点，使用 file+datetree 的话，新增的记录会按照「年-月-日」的层次组织起来；而使用 file+weektree 的话，新增的记录会按「年-周-日」的层次组织，下图是两者的对比

我个人目前是使用 file+datetree 的。

这类模板也比较简单，基本上用 file+headline 的 target，然后视情况而定预先设置 tag 什么的。

我个人有一个 capture 模板，用来快速记录未归类的东西，然后会在后面使用 refile 来将这些东西迁移到任务或者笔记中

(add-to-list 'org-capture-templates
             '("i" "Inbox" entry (file "~/Dropbox/org/inbox.org")
               "* %U - %^{heading} %^g\n %?\n"))

笔记则用另外一个 capture 模板

(add-to-list 'org-capture-templates
             '("n" "Notes" entry (file "~/Dropbox/org/notes/inbox.org")
               "* %^{heading} %t %^g\n  %?\n"))

可以看到两个模板其实差不多，无非就是写入的文件不一样。实际上的不同之处在于，在我的笔记本 ~/Dropbox/org/notes/inbox.org 中，我设置了一些文件级别的 tag，如下所示

#+TITLE: 笔记本
#+STARTUP: hideall
#+TAGS: [coding: shell python]
#+TAGS: [shell: grep tail sed ssh]
#+TAGS: [python: ipython pandas numpy]

这样在特殊标记 %^g 展开的时候，就可以用上面设置的 tag 进行补全。

在 Org mode 中利用表格来记录账单是非常合适的一个方式，记录好后利用表格公式(见我的上一篇文章)可以很方便地进行计算、绘图什么的。

下面是我用来记录账单的 capture 模板，利用自定义的函数，来将同一个月的支出记录在同一张表里

(add-to-list 'org-capture-templates
             '("b" "Billing" plain
               (file+function "~/Dropbox/org/billing.org" find-month-tree)
               " | %U | %^{类别} | %^{描述} | %^{金额} |" :kill-buffer t))))

其中的函数 find-month-tree，用来做类似 file+datetree 的事情，不过层级结构只到月为止，其实现如下

(defun get-year-and-month ()
  (list (format-time-string "%Y年") (format-time-string "%m月")))


(defun find-month-tree ()
  (let* ((path (get-year-and-month))
         (level 1)
         end)
    (unless (derived-mode-p 'org-mode)
      (error "Target buffer \"%s\" should be in Org mode" (current-buffer)))
    (goto-char (point-min))             ;移动到 buffer 的开始位置
    ;; 先定位表示年份的 headline，再定位表示月份的 headline
    (dolist (heading path)
      (let ((re (format org-complex-heading-regexp-format
                        (regexp-quote heading)))
            (cnt 0))
        (if (re-search-forward re end t)
            (goto-char (point-at-bol))  ;如果找到了 headline 就移动到对应的位置
          (progn                        ;否则就新建一个 headline
            (or (bolp) (insert "\n"))
            (if (/= (point) (point-min)) (org-end-of-subtree t t))
            (insert (make-string level ?*) " " heading "\n"))))
      (setq level (1+ level))
      (setq end (save-excursion (org-end-of-subtree t t))))
    (org-end-of-subtree)))

效果如下图所示

联系人会有一些常见的属性比如姓名、手机号、邮箱、住址之类的，简单起见可以用表格来做，比如

(add-to-list 'org-capture-templates
             '("c" "Contacts" table-line (file "~/Dropbox/org/contacts.org")
               "| %U | %^{姓名} | %^{手机号}| %^{邮箱} |"))

不过在一些场景下用表格来做可能会不太方便，比如说我们想对联系人进行一些细致的描述之类的，这种情况下一个表格行太长就不太方便了。

因此因外一个方案是，将每个联系人的信息记录为一个 headline 中，联系人的具体属性作为 headline 的 property 进行记录，如果要进行什么描述说明的话就作为 headline 下属的内容就好，如下所示：

(add-to-list 'org-capture-templates
             '("c" "Contacts" entry (file "~/Dropbox/org/contacts.org")
               "* %^{姓名} %^{手机号}p %^{邮箱}p %^{住址}p\n\n  %?" :empty-lines 1))

和记录联系人类似，如果只是单纯地记录密码，那么可以直接用表格。不过作为一个密码管理方案，我们可能要考虑以下事情

• org 文件本质上是文本文件，怎么保证密码的安全性？
• 当我需要新建密码时，是否能在 org-capture 中直接来生成密码？

以上两点都是可以解决的。安全方面，Org mode 支持对文件、headline、headline 中正文等不同层级的加密，详情见 Encrypting org Files.，这里只讲最简单的文件级加密。

首先我们在 Emacs 中先新建好一个后缀为 cpt 的 org 文件，比如 passwords.org.cpt —— 在一个正常的 org 文件后再附加上 cpt 这个后缀，就会被当作一个加密文件，在创建这个文件的时候会要求我们输入加密用的密码，我们只需要把这个主密码记住就好了。

然后我们要写一个函数来要求输入密码，当输入密码为空时，我们就自动生成一个密码 —— 简单起见这里限定生成的密码长度是 16 位，只用字母和数字组成，如下所示。

(defun random-alphanum ()
  (let* ((charset "abcdefghijklmnopqrstuvwxyz0123456789")
         (x (random 36)))
    (char-to-string (elt charset x))))

(defun create-password ()
  (let ((value ""))
    (dotimes (number 16 value)
      (setq value (concat value (random-alphanum))))))


(defun get-or-create-password ()
  (setq password (read-string "Password: "))
  (if (string= password "")
      (create-password)
    password))

然后新建一个模板如下就可以了。

(add-to-list 'org-capture-templates
             '("p" "Passwords" entry (file "~/Dropbox/org/passwords.org.cpt")
               "* %U - %^{title} %^G\n\n  - 用户名: %^{用户名}\n  - 密码: %(get-or-create-password)"
               :empty-lines 1 :kill-buffer t))

我是直接使用 Org mode 的原生支持的 project 来写博客的，写好后将整个 project 导出成 html，放置到配置好的 jekyll 目录下。Org mode 的 project 要求设置一个目录，这个目录下的 org 文件都会被当作 project 中的文章，比如说我的博客对应的 project 设置是这样的

(setq org-publish-project-alist
      '(("blog-org"
         :base-directory "~/Dropbox/org/blog/"
         :base-extension "org"
         :publishing-directory "~/Projects/github-pages/"
         :recursive t
         :htmlized-source t
         :section-numbers nil
         :publishing-function org-html-publish-to-html
         :headline-levels 4
         :html-extension "html"
         :body-only t     ; Only export section between <body> </body>
         :table-of-contents nil
         )
        ("blog-static"
         :base-directory "~/Dropbox/org/blog/"
         :base-extension "css\\|js\\|png\\|jpg\\|gif\\|pdf\\|mp3\\|ogg\\|swf\\|php"
         :publishing-directory "~/Projects/github-pages/"
         :recursive t
         :publishing-function org-publish-attachment
         )
        ("blog" :components ("blog-org" "blog-static"))))

那么我每次新写文章的时候，就需要用 C-x C-f(find-file) 去在这个目录下新建一个文件，这个过程，是可以用 org-capture 来优化的。

为了方便示例我们把问题简化一下，我需要的是执行 org-capture 后，自动在一个固定的目录下，产生一个命名类似 2018-03-25.org 的文件，并在文件中写入一些固定的内容。

用 org-capture 我们可以这么做

(add-to-list 'org-capture-templates
             `("b" "Blog" plain (file ,(concat "~/Dropbox/org/blog/"
                                               (format-time-string "%Y-%m-%d.org")))
               ,(concat "#+startup: showall\n"
                        "#+options: toc:nil\n"
                        "#+begin_export html\n"
                        "---\n"
                        "layout     : post\n"
                        "title      : %^{标题}\n"
                        "categories : %^{类别}\n"
                        "tags       : %^{标签}\n"
                        "---\n"
                        "#+end_export\n"
                        "#+TOC: headlines 2\n")))

注意，这里和前面的模板有一些不同

• `("b" "Blog" 这里开头的符号不是单引号
• target 和 template 两部分中有一个 concat 函数的调用，在其前面有一个逗号

这里涉及到 emacs-lisp 的一些语法细节，想要详细了解的可以查看相关文档： Backquote - GNU Emacs Lisp Reference Manual。

结合 org-protocol，我们可以在外部程序中发送数据到 Emacs 中并触发 org-capture，是非常方便的一个功能。

由于 org-protocol 本身还有很多细节，展开来讲的话内容会很多，这里就只重点讲一下和 org-capture 相关的部分。

首先我们要知道 org-protocol 其实是定义了一个类似通信协议一样的东西，因此我们需要启动 Emacs server 来让外部程序可以访问，在配置文件中加入下面这行配置即可

(server-start)

要启用 org-protocol 的话，还需要在 Emacs 之外做一些设置，本文不准备在这里做过多说明，详情可以参考 org-capture-extension 这个项目，里面对 Linux/OSX/Windows 三个操作系统上的设置都做了详细说明。

在 Emacs 中我们需要加载一下 org-protocol

(require 'org-protocol)

当用 org-protocol 触发 org-capture 时，它会设置 org-store-link-plist 这个变量，根据外部传入的数据设置其中的一些属性。从 org-protocol-do-capture 这个函数的源代码中，我们可以发现这么一段

(org-store-link-props :type type
                      :link url
                      :description title
                      :annotation orglink
                      :initial region
                      :query parts)

也就是说，在 org-store-link-plist 中的属性有六个，分别如下

这和我们前面「capture 模板的五个部分」中提到的 org-protocol 在内容模板中可用的六个特殊标记，是一一对应的。

利用这六个属性及对应的六个特殊标记，我们就可以方便地做网页内容的收集了。

我们先为 org-protocol 相关的 capture 模板设立一个分组

(add-to-list 'org-capture-templates '("p" "Protocol"))

最简单的情况是用 org-capture 来做网页书签管理，相应的 capture 模板会比较简单，只需要记录下网页的标题和链接即可，如下所示：

(add-to-list 'org-capture-templates
             '("pb" "Protocol Bookmarks" entry
               (file+headline "~/Dropbox/org/web.org" "Bookmarks")
               "* %U - %:annotation" :immediate-finish t :kill-buffer t))

再进一步的，我们可以选中网页上的内容，通过 org-protocol 和 org-capture 快速记录到笔记中

(add-to-list 'org-capture-templates
             '("pn" "Protocol Bookmarks" entry
               (file+headline "~/Dropbox/org/web.org" "Notes")
               "* %U - %:annotation %^g\n\n  %?" :empty-lines 1 :kill-buffer t))

当然，上面的 capture 模板会有一个问题，假如说一个网页上，有多处我觉得有价值的内容，我都选中了然后通过 org-protocol 调用了 org-capture，那么实际上是会产生多条记录的。这种情况如果能将同一个网页的内容都按顺序放置到同一个 headline 里面，显然是更加合理的。对上面的 capture 模板稍作调整，得到的下面的模板就能满足这个需求：

(add-to-list 'org-capture-templates
             '("pa" "Protocol Annotation" plain
               (file+function "~/Dropbox/org/web.org" org-capture-template-goto-link)
               "  %U - %?\n\n  %:initial" :empty-lines 1))

这里用了 file+function，函数 org-capture-template-goto-link 的定义参考了 reddit 上的这篇帖子。

(defun org-capture-template-goto-link ()
  (org-capture-put :target (list 'file+headline
                                 (nth 1 (org-capture-get :target))
                                 (org-capture-get :annotation)))
  (org-capture-put-target-region-and-position)
  (widen)
  (let ((hd (nth 2 (org-capture-get :target))))
    (goto-char (point-min))
    (if (re-search-forward
         (format org-complex-heading-regexp-format (regexp-quote hd)) nil t)
        (org-end-of-subtree)
      (goto-char (point-max))
      (or (bolp) (insert "\n"))
      (insert "* " hd "\n"))))

此外，结合 abo-abo 的 orca 工具，我们还可以针对不同的网站域名，来自动地将网页收集内容进行归类，可以应用的场景有

• 在 arxiv、google scholar 上用 org-protocol 触发 org-capture 时，自动新增内容到记录待读论文列表的 papers.org 中
• 在淘宝、京东、亚马逊网站上用 org-protocol 触发 org-capture 时，自动新增内容到记录心愿单列表的 wishlist.org 中
• …

而结合 org-protocol-capture-html 这个工具，我们可以在用 org-protocol 触发 org-capture 时，将网页内容全文转换成 org 文件存储到特定目录中，打造一个类似稍后阅读的工具。

利用 anki-editor，我们可以在 org 文件中创建卡片并同步到 Anki 软件中。这里就以 anki-editor 中的卡片结构，来展示如何用 org-capture 创建 Anki 卡片。

最简单的例子，是新建单词卡，用来辅助记忆我们学习到的一些新的单词。那么对应的 capture 模板是这个样子的：

(add-to-list 'org-capture-templates
             `("v" "Vocabulary" entry
               (file+headline "~/Dropbox/org/anki.org" "Vocabulary")
               ,(concat "* %^{heading} :note:\n"
                        "%(generate-anki-note-body)\n")))

其中的 generate-anki-note-body 函数如下

(defun generate-anki-note-body ()
  (interactive)
  (message "Fetching note types...")
  (let ((note-types (sort (anki-editor-note-types) #'string-lessp))
        (decks (sort (anki-editor-deck-names) #'string-lessp))
        deck note-type fields)
    (setq deck (completing-read "Choose a deck: " decks))
    (setq note-type (completing-read "Choose a note type: " note-types))
    (message "Fetching note fields...")
    (setq fields (anki-editor--anki-connect-invoke-result "modelFieldNames" `((modelName . ,note-type))))
    (concat "  :PROPERTIES:\n"
            "  :ANKI_DECK: " deck "\n"
            "  :ANKI_NOTE_TYPE: " note-type "\n"
            "  :END:\n\n"
            (mapconcat (lambda (str) (concat "** " str))
                       fields
                       "\n\n"))))

这个函数的定义是抄了 anki-editor(version:20180729) 中的代码，做了一些修改得到的。

(defun my-python-mode-config ()
  (setq python-indent-offset 4
        python-indent 4
        indent-tabs-mode nil
        default-tab-width 4

        ;; 设置 run-python 的参数
        python-shell-interpreter "ipython"
        python-shell-interpreter-args "-i"
        python-shell-prompt-regexp "In \\[[0-9]+\\]: "
        python-shell-prompt-output-regexp "Out\\[[0-9]+\\]: "
        python-shell-completion-setup-code "from IPython.core.completerlib import module_completion"
        python-shell-completion-module-string-code "';'.join(module_completion('''%s'''))\n"
        python-shell-completion-string-code "';'.join(get_ipython().Completer.all_completions('''%s'''))\n")

  (add-to-list 'auto-mode-alist '("\\.py\\'" . python-mode))
  (hs-minor-mode t)                     ;开启 hs-minor-mode 以支持代码折叠
  (auto-fill-mode 0)                    ;关闭 auto-fill-mode，拒绝自动折行
  (whitespace-mode t)                   ;开启 whitespace-mode 对制表符和行为空格高亮
  (hl-line-mode t)                      ;开启 hl-line-mode 对当前行进行高亮
  (pretty-symbols-mode t)               ;开启 pretty-symbols-mode 将 lambda 显示成希腊字符 λ
  (set (make-local-variable 'electric-indent-mode) nil)) ;关闭自动缩进

(add-hook 'python-mode-hook 'my-python-mode-config)

(setenv "IPY_TEST_SIMPLE_PROMPT" "1")

(when (not (require 'company nil :noerror))
  (message "install company now...")
  (setq url-http-attempt-keepalives nil)
  (package-refresh-contents)
  (package-install 'company))

(add-hook 'after-init-hook 'global-company-mode)

(company-bbdb
 company-nxml
 company-css
 company-eclim
 company-semantic
 company-clang
 company-xcode
 company-cmake
 company-capf
 company-files
 (company-dabbrev-code company-gtags company-etags company-keywords)
 company-oddmuse company-dabbrev)

(when (not (require 'company-jedi nil :noerror))
  (message "install company-jedi now...")
  (setq url-http-attempt-keepalives nil)
  (package-refresh-contents)
  (package-install 'company-jedi))

mkdir -p ~/.emacs.d/.python-environments/

cd ~/.emacs.d/.python-environments/
virtualenv -p /usr/bin/python3  --prompt="<venv:jedi>" jedi

setup(
    name='jediepcserver',
    version='0.2.7',
    py_modules=['jediepcserver'],
    install_requires=[
        "jedi>=0.8.1",
        "epc>=0.0.4",
        "argparse",
    ],
    entry_points={
        'console_scripts': ['jediepcserver = jediepcserver:main'],
    },
    **args
)

~/.emacs.d/.python-environments/jedi/bin/pip install jedi>=0.8.1 epc>=0.0.4 argparse

~/.emacs.d/.python-environments/jedi/bin/pip install --upgrade ~/.emacs.d/elpa/jedi-core-20170319.2107/

~/.emacs.d/.python-environments/jedi/bin/pip install tensorflow==1.3.0 scipy==0.19.1 numy==1.13.1 scikit-learn==0.19.0

(setq jedi:environment-root "jedi")
(setq jedi:server-command (jedi:-env-server-command))

(defun config/enable-jedi ()
  (add-to-list 'company-backends 'company-jedi))
(add-hook 'python-mode-hook 'jedi:setup)
(add-hook 'python-mode-hook 'config/enable-jedi)

(when (not (require 'flycheck nil :noerror))
  (message "install flycheck now...")
  (setq url-http-attempt-keepalives nil)
  (package-refresh-contents)
  (package-install 'flycheck))

(defun config/enable-flycheck ()
  (flycheck-mode t))
(add-hook 'python-mode-hook 'config/enable-flycheck)

(defcustom flycheck-executable-find #'executable-find
  "Function to search for executables.

The value of this option is a function which is given the name or
path of an executable and shall return the full path to the
executable, or nil if the executable does not exit.

The default is the standard `executable-find' function which
searches `exec-path'.  You can customize this option to search
for checkers in other environments such as bundle or NixOS
sandboxes."
  :group 'flycheck
  :type '(choice (const :tag "Search executables in `exec-path'" executable-find)
                 (function :tag "Search executables with a custom function"))
  :package-version '(flycheck . "0.25")
  :risky t)

(defun executable-find (command)
  "Search for COMMAND in `exec-path' and return the absolute file name.
Return nil if COMMAND is not found anywhere in `exec-path'."
  ;; Use 1 rather than file-executable-p to better match the behavior of
  ;; call-process.
  (locate-file command exec-path exec-suffixes 1))

(push "<YOUR PYTHON3 VENV>/bin/" exec-path)

(when (not (require 'auto-virtualenvwrapper nil :noerror))
  (message "install auto-virtualenvwrapper now...")
  (setq url-http-attempt-keepalives nil)
  (package-refresh-contents)
  (package-install 'auto-virtualenvwrapper))

(add-hook 'python-mode-hook #'auto-virtualenvwrapper-activate)

(add-hook 'window-configuration-change-hook #'auto-virtualenvwrapper-activate)

(declare-function python-shell-calculate-exec-path "python")

(defun flycheck-virtualenv-executable-find (executable)
  "Find an EXECUTABLE in the current virtualenv if any."
  (if (bound-and-true-p python-shell-virtualenv-root)
      (let ((exec-path (python-shell-calculate-exec-path)))
        (executable-find executable))
    (executable-find executable)))

(defun flycheck-virtualenv-setup ()
  "Setup Flycheck for the current virtualenv."
  (setq-local flycheck-executable-find #'flycheck-virtualenv-executable-find))

(when (not (require 'py-autopep8 nil :noerror))
  (message "install autopep8 now...")
  (setq url-http-attempt-keepalives nil)
  (package-refresh-contents)
  (package-install 'py-autopep8))

pip install autopep8

(add-hook 'python-mode-hook 'py-autopep8-enable-on-save)

(setq py-autopep8-options '("--max-line-length=100"))

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

| 单元格 | 单元格 | 单元格 |
|-

| 单元格 | 单元格 | 单元格 |
|-------+-------+-------|

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

第一种方法依赖 gnuplot 这个外部绘图工具，以及 gnuplot-mode 这个 Emacs 插件。

在依赖满足的情况下，只需要在表格上方添加 "#+PLOT:"， 然后在后面填写要传递给 gnuplot 的参数即可:

#+PLOT: title:"Citas" ind:1 deps:(3) type:2d with:histograms set:"yrange [0:]" file:"./plot.png"
| 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 |

得到的结果如下图所示：

使用这种 Org mode 自带的绘图方式，除了简便以外，还有一个好处就是表格的 header 能被正确地识别做列名，并在图中用来作为各列数据的 label。

以下是可在 "#+PLOT:" 后面设置的绘图参数

• title: 设置图像的标题
• ind: 用于绘制 x 轴的表中的列
• deps: 除 x 轴以外的其他数据在表中的列，若有多列，用括号括起，如 "deps:(2, 3)"
• type: 2d, 3d, or grid
• with: 设置绘制类型，如 lines, points, boxes, impulses, histograms
• file: 如果需要将绘制的图像保存为文件，则使用该属性
• labels: 给定 deps 的标签，默认为表格 header

详见: Plotting tables in Org-Mode using org-plot

Org mode 有一个非常强大的功能就是可以插入各种语言的 source block，并且能去执行 source block 里的代码，接着将结果插入到当前的 Org mode 文档中来。

下图展示了在 Org mode 中插入 C++ 的 source block 并执行得到结果的过程:

同时，Org mode 中的表格数据是可以作为变量传递到 source block 中的，如下图所示:

如上图所示，要将表格数据传递给 source block ，需要两个步骤

1. 用 "#+NAME" 将表格命名为 "citas-data"
2. 在 source block 的选项中，用 ":var tbl_data=citas-data" 将表格数据赋值给变量 "tbl_data"

对于下面这个表格，我可以可以用这个方法将数据传递给 source block ，然后用 matplotlib 来绘制图像。

#+NAME: citas-data
| 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 |

相应的 source block 为

#+BEGIN_SRC python :results file :var tbl_data=citas-data filename="./org-plot-example2.png"
import numpy as np
import matplotlib
import matplotlib.pyplot as plt

plt.style.use('ggplot')


bar_names = [row[0] for row in tbl_data]
h_index = [row[2] for row in tbl_data]
ind = np.arange(len(tbl_data))
width = 0.5

plt.bar(ind, h_index, width)
plt.title('Citas')
plt.xlabel('Sede')
plt.ylabel('H-index')
plt.xticks(ind + width/2., bar_names)

plt.savefig(filename)
return(filename)
#+END_SRC

执行后得到的结果为:

上一节提到，默认情况下，Org mode 接受的任务状态关键词只有 "TODO" 和 "DONE" 两个，分别表示 "待办" 与 "完成"。这样的分类对于一些不可再分的小任务，当然是足够用的，但有时候需要设置更为丰富的任务状态，如添加一个表示 "正在进行" 状态的关键词 "DOING"，在不进行设置的情况下，这个关键词是无法高亮的:

这个词将会被视作任务名称的一部分，而不是表示任务状态的标识。用本文之前提到的快捷键更改任务的状态，会看到下面这样的变化。

要达到预期的目的，有两种方法，一种方法是全局的，另一种则只在当前文件生效。

Org mode 中有一个变量 org-todo-keywords 存储着作用于全局的状态序列，它的默认值是:

'((sequence "TODO" "DONE"))

这就是默认状态只有两个的原因，修改这个变量的值也就能达到全局修改状态序列的目的了。

需要注意的是，状态序列在定义时的顺序是从左至右有序的，最后一个关键词会被认为是 表示任务终结 的关键词。所以如果要添加 "DOING" 这个状态，应该像下面这样进行设置:

(setq org-todo-keywords '((sequence "TODO" "DOING" "DONE")))

默认情况下表示非终结状态的关键词与表示终结的关键词的高亮颜色是不一样的，而且在更改为终结状态时，会在任务下添加一条下面这样的标记。

CLOSED: [2015-07-15 三 23:20]

如果将 "DOING" 放置到序列的末端，那么状态变化时的现象就会和预期的不一致:

如果只想在某个文件中为其设置独有的关键词序列，那么可以在org文件的头部用"#+SEQ_TODO"来进行设置:

#+SEQ_TODO: TODO DOING DONE

之前提到，Org mode 在高亮时只区分非终结状态与终结状态，但如果各个状态都能以不同的颜色显示，那肯定能让任务的状态更加一目了然。通过修改 org-todo-keyword-faces 这个变量可以达到这个目的。例如我们希望 "TODO" 以红色显示，"DOING" 以黄色显示，"DONE" 用绿色显示，就可以这样设置:

(setq org-todo-keyword-faces '(("TODO" . "red")
                               ("DOING" . "yellow")
                               ("DONE" . "green")))

以下是这样设置后的效果图:

前面所以说 "终结状态" 而不说 "完成状态"，是因为 "终结状态" 可能有不止一种，比如在表示正常完成的状态外，还可以有表示异常中止的状态。当有多个表示终结的状态时，相应的关键词要处于关键词序列的尾部，并且用"|"和非终结状态分隔开来，也就是这样:

(setq org-todo-keywords '((sequence "TODO" "DOING" "|" "DONE" "ABORT")))

若在文件中进行设置，则是:

#+SEQ_TODO: TODO DOING | DONE ABORT

这样的话有一个问题，那就是，一般来说，对于一个任务来说，一般只会用到多个终结状态中的一个，但假如我要将一个原先为"TODO"状态的任务标记为"ABORT"，我就要使用快捷键"C-c C-t"或"S-left"/"S-right"，依次经过"DOING"、"DONE"，最后才标记为"ABORT"。这样的行为和理想的体验是不符合的。

好在 Org mode 也提供了解决这一场景的方法，那就是，可以为每一个状态设立一个快速选择键，在使用快捷键"C-c C-t"时，会等待输入这个快速选择键来迅速指定为特定状态。使用这个功能所需要的设置也很简单。

第一个是将变量"org-use-fast-todo-selection"的值设置为真(t)——一般来说，这个变量的值默认就是真(t):

(setq org-use-fast-todo-selection t)

然后在定义关键词序列时，在每个关键词后跟随括号并在其中指定快速选择键，如:

(setq org-todo-keywords '((sequence "TODO(t)" "DOING(i)" "|" "DONE(d)" "ABORT(a)")))

或在文件头部设置:

#+SEQ_TODO: TODO(t) DOING(i) | DONE(d) ABORT(a)

这样使用快捷键"C-c C-t"时，就能够方便地切换任务的状态了，如下图所示:

除了上述内容以外，Org mode 还允许定义进入状态和离开状态时的额外动作，可用的动作包含两个:

• 添加笔记和状态变更信息(包括时间信息)，用"@"表示
• 只添加状态变更信息，用"!"表示

这个通过定义带快速选择键的关键词时，在快速选择键后用"X/Y"来表示，X表示进入该状态时的动作，Y表示离开该状态时的动作。对于一个状态(以"DONE"为例)，以下形式都是合法的:

DONE(d@)       ; 进入时添加笔记
DONE(d/!)      ; 离开时添加变更信息
DONE(d@/!)     ; 进入时添加笔记，离开时添加变更信息

而这个是不合法的:

DONE(d@/)

需要注意的是，当由状态 A 到达状态 B 时，为状态 A 设置的离开动作 Y_A 只在状态 B 未设置进入动作 X_B 时生效；如果目标状态设置了进入动作，那么出发状态的离开动作不被执行，而是执行目标状态的进入动作。下图为演示。

(setq org-enforce-todo-dependencies t)

(add-to-list 'auto-mode-alist  '("\\.org\\'" . org-mode))

(setq truncate-lines nil)

在 Org mode 中，文档内容是通过 headline 来组织成一个树状结构的 —— 由于在 Org mode 中还存在 "title" 这种文章级的标题，为避免混淆，就不对 "headline" 进行翻译了，我们只要知道这几点就行:

1. headline 是一节内容的标题(概要)
2. headline 可以分级
3. headline 可以有子 headline

我想凡是有 Markdown 、RST 乃至 Microsoft Office 使用经验的人，都能理解什么是 "headline"。

headline 在 Org mode 中会被高亮显示，且不同级别的 headline 会以不同的颜色显示。要创建 headline 也很简单，只要一行文字以若干个连续星号(*)顶格，并在星号结束后跟随至少一个空格，则该行会被视为一个 headline ，连续星号的数量被视为 headline 的层级，如图所示。

实际上 Org mode 提供了丰富的快捷键来操作 headline，不需要手动输入星号(*)来创建 headline。以下是这些快捷键的一个总结:

通过 headline 来组织文档内容便于组织思想，这在很多其他编辑环境或者软件上都有体现，但与它们不同的是，Org能够方便地隐藏各级 headline 下的内容只显示 headline 的树状结构或者只显示第一级headline——这就是所谓 outline 了，如下图所示。只要通过 headline 组织好 Org 文档，概览文档、快速定位和编辑都能很方便地做到。

通过快捷键 TAB 可以对某个 headline 及其内容的显示在三种状态(Folded, Children, Subtree)中切换；快捷键 S-TAB 则对整个 org 文件的内容显示在三种状态(Overview, Contents, Show all)中切换。Org 的文档称这种行为为"cycling"，前者称为"subtree cycling"，后者则是"global cycling"。

subtree cycling的状态

• Folded: 对当前 headline，只显示 headline，其下的子节点及内容隐藏
• Children: 对当前 headline，显示当前 headline 及其下更低一级的 headline
• Subtree: 对当前 headline，只显示当前 headline 及其下更低级的 headline

下面的动态图像展示了subtree cycling 的状态变化(Folded -> Children -> Subtre)。

global cycling 的状态变化与 subtree cycling 类似，不过针对的是整个文档，下面图像展示了 global cycling 的状态变化(Overview -> Contents -> Show all)

Org mode 的几大特性中，任务管理、任务计时、项目管理都是建立在 outline 结构上的，捕获虽然可以不基于这个结构，但一般来说都会使用。

除了 headline 外，Org mode 还支持列表、文字修饰(粗体、斜体、下划线等)、代码块、引用等常见的功能。

• 列表

  + 无序列表
    * 用"+","-", "*"开头，后跟随用空格分隔开的列表项名称、内容
    * "*"在行首顶格的话则是headline，这个要注意
    * 如果想结束一个列表，那么在其后跟随两个空行
  
  + 有序列表
    1. 用"1.","1)"开头，后跟随用空格分隔开的列表项名称、内容
    2. 其余同无序列表
  

  列表和 headline 一样，也是可以分级、嵌套的，列表相关的快捷键也与 headline 相关的快捷键部分重叠(Org mode 会根据实际情况来进行合理的操作，所以不用担心混淆问题):

  快捷键	功能	备注
  C-<return>	在当前列表项的内容后建立一个同级列表项	光标在列表项同一行时有效
  M-<return>	在当前列表项后建立一个同级列表项	同上
  M-<right>	降低当前列表项的层级	同上
  M-<left>	提高当前列表项的层级	同上
  M-<up>	将当前列表项及其内容作为整体向上移动	同上
  M-<down>	将当前列表项及其内容作为整体向下移动	同上

• 粗体

  粗体 用两个星号包裹，星号与粗体前后的其他字应该各有至少一个空格或英文标点分隔开来
  bold,word,用英文逗号分隔开，bold显示出粗体效果
  *bold*word则不显示粗体效果
  

• 斜体

  hello 用""包裹，规则同粗体
  斜体 好像对中文不管用?导出成HTML时看到还是生效了，可能是字体关系吧
  

• 下划线

  下划线 用"_"在前后包裹，规则同粗体
  _下划线_紧跟其他字，则不生效
  

• 删除线

  删除线 用"+"在前后包裹，规则同粗体
  

• 引用块

  #+BEGIN_QUOTE
  引用内容
  #+END_QUOTE
  

  在org文件中输入"<q"然后按 TAB 键会自动插入一个引用块，插入后在其中进行编辑即可。

• 示例块

  #+Begin_EXAMPLE
  示例
  #+END_EXAMPLE
  

  在org文件中输入 "<e" 然后按 TAB 键来插入一个示例块，可以移动到其中并使用快捷键"C-'(单引号)"来在新窗格中编辑它，编辑好后用同样的快捷键来保存。

• 代码块

  #+BEGIN_SRC C++
  #include <iostream>
  
  using namespace std;
  
  int main(int argc, char *argv)
  {
      cout << "代码块" << endl;
  
      return 0;
  }
  #+END_SRC
  

  代码块稍微复杂一点，插入的话是通过输入"<s"然后按 TAB 键来达到，但插入后还要在"#+BEGIN_SRC"后指定代码的语言类型(如上例所示)。

  Org mode可以根据代码所属的语言来对其进行高亮，不过自Emacs 24.1后，默认设置下不对代码块进行高亮，需要进行设置

  (setq org-src-fontify-natively t)
  

  在编辑代码块的时候也会开启对应语言的 major mode，若对应的语言配置得当，在编辑 Org mode 中的代码块时，自动缩进、自动补全等功能都可以享用。编辑与保存的快捷键同示例块(exmple block)。

  

  此外在 Org mode 中还可以对代码进行求值，产生了很多丰富的应用方式，这个留待后续。

• 图片

  在 Org mode 中，可以插入本地图片，并在 Org mode 中进行显示。要做到这个，直接在 org 文件中写入本地文件的路径，然后开启 iimage-mode 即可(M-x iimage-mode)。

  为进行区分，通常会在图片地址前加上"file"前缀，如

  file:/assets/img/source-edit.gif
  

• 链接

  链接的语法规则是这样的:

  [[<link url>][<text>]]
  

  比如

  [[http://linusp.github.io/][Linusp's Blog]]
  

  会显示为 Linusp's Blog。

;; 将当前窗口分割为上下两个，并切换到另外一个 buffer
(defun split-window-new-buffer ()
  (interactive)
  (split-window-below)
  (call-interactively 'switch-to-buffer))

Emacs 中提供了 C-x o(字母) 这个快捷键来在窗口间循环移动，方向大致是顺时针方向。分割的窗口数稍微一多的话，这么一个快捷键肯定是不够的。

事实上 C-x o 是调用了 other-window 这个内建方法，通过 C-h f 可以知道这个方法的原型是:

(other-window COUNT &optional ALL-FRAMES)

它的参数里我们要关心的是 COUNT 这个参数，这个参数可以取三种值:

• 为正整数: 顺时针前进指定数目的窗口
• 等于0: 原地不动
• 为负整数: 逆时针前进指定数目(COUNT的绝对值)的窗口

所以我们可以很自然地写出一个 "切换到上一个窗口" 的方法来:

(defun prev-window ()
  (interactive)
  (other-window -1))

然后可以按自己的需要绑定到指定的快捷键上，以 C-x p 为例:

(global-set-key (kbd "C-x p") 'prev-window)

Emacs 中其实还内置了更为简易的切换方法，可以向当前窗口指定方向的邻近窗口切换，不过并未给这些方法提供默认的快捷键绑定。

共有四个方法，它们在 windmove 这个包中被定义和实现:

• windmove-up
• windmove-down
• windmove-right
• windmove-left

功能的话看它们的名称就看得出来，我想就不用多解释了。

我们可以自己来进行绑定，或者也可以使用默认的设置:

(windmove-default-keybindings)

在配置文件中添加上面这句后，我们将可以使用 Shift+方向键 的方式来进行窗口切换。为求方便一般还会在其后跟上以下这句:

(setq windmove-wrap-around t)

这一条语句的作用是让 windmove 在边缘的窗口也能正常运作。举个例子，当前窗口已经是最左端的窗口了，如果使用 Shift+left ，将仍会停留在当前窗口——因为已经到边缘了，左边没有窗口可供选择。但在添加了上面这句后，Shift+left 将会跳到最右边的窗口中。垂直方向上的窗口切换同理。

(desktop-save-mode 1)

(setq desktop-dir "~/Dropbox/doc/")
(desktop-read desktop-dir)

$$e^{i\pi} + 1 = 0$$

<script type="text/javascript" src="http://orgmode.org/mathjax/MathJax.js"></script>
<script type="text/javascript">
  <!--/*--><![CDATA[/*><!--*/
    MathJax.Hub.Config({
        // Only one of the two following lines, depending on user settings
        // First allows browser-native MathML display, second forces HTML/CSS
        //  config: ["MMLorHTML.js"], jax: ["input/TeX"],
            jax: ["input/TeX", "output/HTML-CSS"],
        extensions: ["tex2jax.js","TeX/AMSmath.js","TeX/AMSsymbols.js",
                     "TeX/noUndefined.js"],
        tex2jax: {
            inlineMath: [ ["\\(","\\)"] ],
            displayMath: [ ['$$','$$'], ["\\[","\\]"], ["\\begin{displaymath}","\\end{displaymath}"] ],
            skipTags: ["script","noscript","style","textarea","pre","code"],
            ignoreClass: "tex2jax_ignore",
            processEscapes: false,
            processEnvironments: true,
            preview: "TeX"
        },
        showProcessingMessages: true,
        displayAlign: "center",
        displayIndent: "2em",

        "HTML-CSS": {
             scale: 100,
             availableFonts: ["STIX","TeX"],
             preferredFont: "TeX",
             webFont: "TeX",
             imageFont: "TeX",
             showMathMenu: true,
        },
        MMLorHTML: {
             prefer: {
                 MSIE:    "MML",
                 Firefox: "MML",
                 Opera:   "HTML",
                 other:   "HTML"
             }
        }
    });
/*]]>*///-->
</script>

(setq org-publish-project-alist
      '(
        ("blog-org"
         ...
         :html-head-include-scripts nil
         ...)
        ...))

$$J(\theta) = \frac{1}{2m}\sum_{i=1}^{m}(\theta^{T}X_{i} - Y_{i})^2$$

(require 'ox-freemind)

#+TITLE: Org-mode
** 写文档
** 发布成html
** org-bable
** 表格

1: (defun org-freemind-export-to-freemind
2:   (&optional async subtreep visible-only body-only ext-plist)
3:     (interactive)
4:   (let* ((extension (concat ".mm" ))
5:          (file (org-export-output-file-name extension subtreep))
6:          (org-export-coding-system 'utf-8))
7:     (org-export-to-file 'freemind ,file
8:     async subtreep visible-only body-only ext-plist)))

这种办法的核心思想是通过一些措施把 ctrl 键映射到物理键盘上比较好按的键位上。常见的方法是将 ctrl 键和 caps lock 键交换，在Planet Emacsen 上还提到了另外一种办法：将 ctrl 键和回车键交换。

在笔记本的键盘按左 ctrl 键尤其难受，不过在笔记本键盘上，可以通过用手掌根部按压左 ctrl 键来避免使左手小指受损。

不过我并不习惯这种姿势。

使用设计更加合理的、符合人体工程学的键盘是解决这个问题的好办法。这个方法不仅能避免Emacs导致的问题，还能减轻其他因为长期使用电脑/键盘而出现的健康问题。

当然，为了健康而投入资金是必须的。

smex是Emacs的一个插件，这里 是相关说明。

smex是一个"M-x"快捷键的增强工具，它能够使得在Emacs中调用各种命令更为方便，能更智能地对命令进行补全，还能根据使用者调用命令的频率来猜测用户可能会执行的命令。如下图所示：

不少Emacs中的命令名字都很长，所以如果不使用smex的话，一来很多命令根本记不住，二来就算记住了输入时也要花费许多的时间——这也是为什么Emacs有如此多的快捷键的原因之一吧。

smex的使用也很简单，下载smex并放置到Emacs的加载目录中后，在配置文件中添加这么几条语句：

(load "~/.emacs.d/site-lisp/smex.el")
(require 'smex)
(smex-initialize)
(global-set-key (kbd "M-x") 'smex)
(global-set-key (kbd "M-X") 'smex-major-mode-commands)
(global-set-key (kbd "C-c C-c M-x") 'execute-extended-command)

我的办法呢，就是综合键位修改和使用smex两个方案。将 ctrl 和 caps lock 交换，然后绑定一些(少量)常用的命令到快捷键上，其他大部分的命令调用则使用smex。

(defun publish-project (project no-cache)
   (interactive "sName of project: \nsNo-cache?[y/n] ")
      (if (or (string= no-cache "y")
          (string= no-cache "Y"))
          (setq org-publish-use-timestamps-flag nil))
   (org-publish-project project)
   (setq org-publish-use-timestamps-flag t))

(require 'htmlize) ;htmlize.el
(setq org-src-fontify-natively t)

(setq org-publish-project-alist
    '(
      ("project-name"
       ......
   :htmlized-source t
       ......
       )
       ......))