Emacs org-capture

org-capture 使用

之前使用了org-mode 和 agenda，后面为了能够更好得记录笔记，研究一下capture的使用和roam。

参考大神文章
参考 org capture 官方文档

首先在windows下折腾一下，根据大神的文章，试用一下该功能。

配置

capture 功能包含在 org 包里，所以只要安装了 org，那么直接就是能使用 capture 功能的。不过不做配置的话，那么

1. 没有快捷键可以触发功能
2. 默认只有一个用于创建任务的 Task 模板可选，并且存储在变量 org-default-notes-file 指定的文件里

如果我们连 org-default-notes-file 都没有设置，它会默认存储到 ~/.notes 中去，然后会由于这个文件不是 Org 文件而报错。。。

例如：
我直接使用后，会报以下的warning
根据大神设置，更新配置文件

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

再来capture一下：
文件中的内容，建立了两个task
## 模板

示例：

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

由五个部分组成

key “t” 用来选择模板的字符
description “Task” 展示用的模板描述
type entry 新增内容的类型
target (file+headline “” “Tasks”) 新增内容的存储位置
template “* TODO %?\n %u\n %a” 新增内容的模板

注意：

1. key不能相同

模板类型

entry 带有 headline 的一个 Org mode 节点
item 一个列表项
checkitem 一个 checkbox 列表项
table-line 一个表格行
plain 普通文本

注意：

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

target

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

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

type	des	example
file	文件	(file “path/to/file”)
id	特定id的某个headline	(id “id of existing Org entry”)
file+headline	文件的某个唯一的 headline	(file+headline “path/to/file” “node headline”)
file+olp	文件中的 headline 路径	(file+olp “path/to/file” “Level 1 heading” “Level 2” …)
file+regexp	文件中被正则匹配的 headline	(file+regexp “path/to/file” “regexp to find location”)
file+datetree	文件中当日所在的 datetree	(file+datetree “path/to/file”)
file+datetree+prompt	文件中的 datetree，弹出日期选择	(file+datetree+prompt “path/to/file”)
file+weektree	文件中当日所在的 weektree	(file+weektree “path/to/file”)
file+weektree+prompt	文件中的 weektree，弹出日期选择	(file+weektree+prompt “path/to/file”)
file+function	文件中被函数匹配的位置	(file+function “path/to/file” function-finding-location)
clock	当前正在计时中的任务所在的位置	(clock)
function	自定义函数匹配的位置	(function function-finding-location)

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

template

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

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

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

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

2. 以 % 开头的特殊标记，如 “%?” 和 “%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

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

模板示例

所有的 capture 模板都应当以 list 的形式记录在变量 org-capture-templates 中

(setq org-capture-templates nil)

配置参看一下大神配置，弄完结束时是这个样子：
使用时，细节需要在根据自己的想法做了， 我这边用的最多的应该就是note ，和tasks

agenda

加入agenda file
org-agenda-file-to-front或者快捷键C-c [ 将当前文件加入到全局列表。

参考：https://blog.csdn.net/u010994434/article/details/113647518

添加 scheduled 时间，这时就可以通过org-agenda 看到该任务。
如何在创建模板时加入计划时间，有待研究，目前先这么尝试了。

这个跟我之前的task模板不太一样，标记为完成后，是这个样子了

查看

查看记录：

C-u M-x org-capture

Visit the target location of a capture template. You get to select the template in the usual way.

C-u C-u M-x org-capture

Visit the last stored capture item in its buffer. 

refile

我理解refile就是跨文件移动，使其更方便在各种agenda 的org文件中移动任务等。

简单配置：

(setq org-refile-targets (quote ((nil :maxlevel . 3)
                                 (org-agenda-files :maxlevel . 3))))

结束吧

下午花了点时间，整理了一下capture功能，感觉跟org-agenda使用有些交集，之前一直使用org的文件记录笔记和日程，这个差不多，只是多了一些定义模板的功能和其他note记录，是不是方便，只有到真正用起来，还是需要慢慢琢磨的。个人感觉有点复杂，不如直接使用org方便

待办：org-refile， org-protocal， org-roam

真正的结束

尝试了一下org-roam，refile， 不是很好用，可能用不习惯，有点太折腾了，后面有心情再搞了。

cache

建立链接后，使用 M-x org-roam-db-build-cache 建立。
一开始建立链接后一直没效果，后来发现是没有更新db。

One can customize the waiting time by setting org-roam-db-update-idle-seconds; or change the cache update to be triggered immediately after buffer save by setting org-roam-db-update-method to 'immediate.