个人 Emacs 核心配置

本文梳理个人使用 emacs 的核心配置，这些代码主要是为了在 org mode 里方便地记录想法、整理笔记和发布，在使用 emacs 之前：

• 我习惯在一个 markdown 或者 txt 文档里随时记录流水账式的日记，手机上则用自带备忘录，然后不定期地导出到电脑。
• 用过一年多的 vim (主要是远程服务器上编程), 用于本地写笔记的话，模态编辑的方式对中文输入法切换不太友好，不方便显示 markdown 里的图片，vimscript 定制起来也比较麻烦。
• 用 jupyter notebook 记录那些带有代码的笔记，尤其是代码需要一点公式说明的情形。 jupyter notebook 弱点在于元信息太多，不方便用 git 来对比差异(不过 vscode 的 git diff 解决了这个问题，只比较其中的内容)，此外每次打开也需要启动一个服务，更不容易整理笔记之间的关系。
• 用 notion 或者为知笔记这样的云服务记录一些不带个人信息的笔记（notion 也可以作为主页进行内容发布），了解到了 roam research ，对其有好感，但 roam 还是无法满足以上提到的需求。

可以看到，那时的记录分散成了三块：

• jupyter notebook: 以代码为主的笔记。
• 本地 markdown/txt: 随机的想法，日记，更具有隐私性。
• 云笔记：不带隐私的知识记录，更容易发布。

当时我就希望能有一个统一以上需求的工具，它要能够保证隐私性、在 vim 模式下方便地输入中文、打开 markdown 还能预览图片和 latex 、 可以比较好地支持 git 版本管理。我想到的方案之一是自己写一个脚本服务，利用 notedown 在 markdown 和 jupyter notebook 之间转换，这样我只需要对 markdown 进行版本管理和 blog 发布，但也可以用 jupyter notebook 编辑（有支持 vim 的 notebook 插件）、执行代码和编写公式。 然而这只能作为一种不得以的选择，在很快了解到 emacs 中有 evil, org, org-roam 以及 org-babel 后，转向 emacs 几乎已经是注定的事了。

正如前文所说，使用 emacs 的最初目的就是写阅读笔记、随记、执行代码（或曰文学编程）：

• org 阅读、记笔记、日记

  pdf-tools, nov-mode, org-roam 等

• org 中执行代码

  org-babel 和 emacs-jupyter

• 中文环境

  与 evil 和谐相处的输入法： emacs-rime 。额外发现还可以用拼音来搜索和跳转等，因此加入 pyim, avy,ace-pinyin, ivy/vertico/company 生态，这些都涉及字符串的解析、预测、选择 UI。

• 窗口管理

  打开的窗口多了，需要对其进行基本的分类，用自带的 tab-bar, 同时写了一些额外记录 context switch 信息的变量和函数，更方便地进行上下文切换后的回退（switch-back）。

• org 任务分解、文献管理

  这不在最初的需求里，但发现 org 中处理起来也比较方便，主要用来分解任务并且记录各任务大致花费的时间。用原生 org-agenda 生成临时报告，org-dynamic-block 生成可存档的报告，citar 生态进行文献管理。

• blog 发布

  已经在 orgchange: 文学编程式 org mode 静态网页生成器 中描述， 其配置独立于个人 emacs 配置，因此不在本文范围内。

• 配置 org 来管理配置本身

  参考： org roam 风格的系统配置文件管理

首先如前文所述， org 之外的其他功能都不在我使用 Emacs 的核心需求中，但由于 emacs 的扩展性，在攒配置过程中还是会去尝试一些其他的功能，有一些保留下来，比如 org-agenda/eaf-mindmap，有些则没有。

本节列出几个自己配置过但不再使用或很少使用的功能或场景：

• 编写项目代码

  我有对部分编程语言配置基础的开发环境，比如 python 、 web/js 、 bash 等，但它们主要是用来支撑 org src block 编辑或者偶尔修改代码用的。在我个人常用的场景里，VSCode 比 emacs 也会更方便一点，比如远程连接加调试。但如果从更广的角度来看待编程活动的话，由于写代码时我会新建一个 org 文件追踪这个项目，记录各阶段问题，又要在 gtd 文件里规划，在 babel 里测试部分函数和类，因此整个项目编写实际是 emacs/org/vscode 混合使用，但编码部分还是以 vscode 为主。

• 查看网页，rss, 邮件等

  这些对我来说只是搜集信息的活动，并且属于初筛，大部分页面都是快速浏览后就关掉，偶尔需要把内容选中复制到 org 里，涉及操作比较单一，配置它们更多是体验一下 emacs 的扩展性。

  与之相对的，做笔记和写作则涉及规划分解、搜索或跳转到相似笔记、插入公式图片、发布等更多环节，这些功能在 org 里都有很好的支持，核心是把它们流畅地串起来，这就需要一些个人的定制。

• 尽量少用 capture template: 比如 org-capture-templates, org-roam-capture-templates。

  一方面，这些模板的书写格式类似 C 语言中 printf 对字符串格式化风格，比如各种 %u %a 符号，不太直观，对于更精细一点的操作又要混合 elisp 代码，比如切换到某个 tab 里去记录，这样还不如自己写一段函数来实现，读起来更加清晰。

  另一方面，用 capture 模板去创建文件或插入内容意味着记录时就要做一些抉择，因为不同模板往往对应不同目录和命名方式等，这很容易打断思路。

  实际中，我更偏向一种 "lazy load" 的方式：要记录时，用一个快捷键打开日志文件、跳到最后一行并自动打上时间戳， 把内容写下来，然后就继续回到当时正在做的事情上，至于这些文字最终要放到哪里， 用什么词去作为它们的文件名和搜索关键字（title, tag 等），那是整理阶段才要考虑的，那时在不同文件之间复制元信息还有助于不同内容之间的对比。

本文给出的代码里有 <<basic-ui>> 这种带双尖括号的格式，这是 org-babel noweb 的引用形式， <<basic-ui>> 在最终配置中会被本文 #+name 为 basic-ui 里的代码块中的内容替换掉，可以用 Ctrl-f 在网页中搜索名称进行跳转查看。

本文不是完整的 emacs 配置，例如包管理、外观主题、编程语言 mode 的基础设置等由于比较零散且大部分是从官方拷贝的默认配置，没有太多个人的加工，因此不在此说明。

先说明两个常见到的编译选项：

• pgtk: 主要是为了支持 Wayland，和 X11 有些地方不兼容, 比如导致 xmodmap 修改的按键失效，我目前不用 Wayland，因此不需要。

• native compile: 把 emacs 里 elisp 代码编译成底层指令，可以提高 emacs 运行速度。

  以下是用默认 ./autogen.sh ./configure 编译后 emacs29.2 的编译选项展示：

  system-configuration-features
  

  ACL CAIRO DBUS FREETYPE GIF GLIB GMP GNUTLS GPM GSETTINGS HARFBUZZ JPEG JSON LCMS2 LIBOTF LIBSELINUX LIBSYSTEMD LIBXML2 M17N_FLT MODULES NOTIFY INOTIFY PDUMPER PNG RSVG SECCOMP SOUND SQLITE3 THREADS TIFF TOOLKIT_SCROLL_BARS X11 XDBE XIM XINPUT2 XPM GTK3 ZLIB
  

  首先这里已经有许多默认的选项了，比如 GIF, X11, MODULES(支持动态链接库，比如 emacs-jupyter 需要 zmq.so ，emacs-rime 需要 librime.so), 但没有 NATIVE_COMP 字样，说明这个版本不是 native comp 的。

  为了支持 native compile, 编译前首先需要安装 libgccjit:

  sudo apt install libgccjit-11-dev
  

  以上版本号应根据自己 gcc 的版本来定，如下是 11.4.0 ，所以用 libgccjit-11-dev

  gcc --version
  

  gcc (Ubuntu 11.4.0-1ubuntu1~22.04) 11.4.0
  

  接着进入 emacs 源码目录，开启编译选项并编译：

  ./autogen.sh
  ./configure --with-native-compilation=aot
  make -j16 #根据 lscpu 显示的核数选择数字
  

  编译时间比没有 native-comp 时长很多，应该是花在把 emacs-lisp 编译成字节码上，编译过后启动 emacs 查看编译选项变量：

  system-configuration-features
  

  ACL CAIRO DBUS FREETYPE GIF GLIB GMP GNUTLS GPM GSETTINGS HARFBUZZ JPEG JSON LCMS2 LIBOTF LIBSELINUX LIBSYSTEMD LIBXML2 M17N_FLT MODULES NATIVE_COMP NOTIFY INOTIFY PDUMPER PNG RSVG SECCOMP SOUND SQLITE3 THREADS TIFF TOOLKIT_SCROLL_BARS X11 XDBE XIM XINPUT2 XPM GTK3 ZLIB
  

  其中已经有 NATIVE_COMP 字样了

  由于 .emacs.d 里第三方包是在 emacs 启动并第一次被加载时进行 native 编译，那时候会打印很多警告，在 early-init.el 里加入以下命令取消警告打印：

  (setq native-comp-async-report-warnings-errors nil)`
  

  编译 emacs 的核心命令：

  print_info "采用编译的方式来安装 emacs, 首先要准备安装条件，包括 build 需要的库，包括 build-essential, 剩下的可以用 `sudo apt build-dep --no-install-recommends emacs` 来查看"
  sudo apt install build-essential -y
  sudo apt build-dep emacs -y
  
  sudo apt-get install build-essential autoconf automake libtool texinfo libgtk-3-dev libxpm-dev libjpeg-dev libgif-dev libtiff5-dev libgnutls28-dev libncurses-dev libxml2-dev libgpm-dev libdbus-1-dev libgtk2.0-dev libpng-dev libotf-dev libm17n-dev librsvg2-dev libmagickcore-dev libmagickwand-dev libglib2.0-dev libgirepository1.0-dev -y
  
  # support native compile
  sudo apt install libgccjit-11-dev -y
  
  print_info "sqlite3 用于 org-roam"
  sudo apt install sqlite3 -y
  
  pushd $CODES
  wget http://mirrors.aliyun.com/gnu/emacs/emacs-29.2.tar.gz
  print_notice "下载 emacs-29.2.tar.gz"
  tar -xf emacs-29.2.tar.gz
  pushd $CODES/emacs-29.2
  ./autogen.sh
  ./configure --with-native-compilation=aot
  make -j16 
  popd 
  rm -rf emacs-29.2.tar.gz
  print_notice "删除 emacs-29.2.tar.gz"
  popd
  print_success "emacs29.2 编译完毕"
  

  完整脚本见： metaesc/install_libs/pack-emacs29.2.sh at main · metaescape/metaesc

对 emacs 本身或者 emacs 中重要的插件进行升级之前一般先备份，便于发现升级不满意或出问题后回退，这部分写在 ~/metaesc/Makefile 中：

backup-emacs-org:
	mkdir -p /data/resource/emacs_org_backup
	tar -czvf /data/resource/emacs_org_backup/$$(date +'%Y%m%d')-wemacs.tar.gz ~/.wemacs
	tar -czvf /data/resource/emacs_org_backup/$$(date +'%Y%m%d')-org.tar.gz ~/org
	@echo "Backup completed."

执行 make backup-emacs-org 会对 emacs 配置和 org 笔记目录进行压缩备份，并以日期作为前缀。

如果要调试其他配置，可以复制 .emacs.d 目录，然后用 -–init-directory 去测试（emacs29 及以上）

Emacs 中某个操作出现 error 时，可以执行 toggle-debug-on-error 启动 debug 后再执行之前的命令，或者在设置 (setq debug-on-error t) 后再操作以打印出调试信息。

由于可以从 emacs 启动其他进程，因此涉及到程序路径的查询，一般来说，有两类从 emacs 启动外部进程的方式：

• 通过 shell-command （同步） 或 start-process-shell-command （异步）：这两个命令大致都是先启动一个 shell ，然后在 shell 里执行命令，而 shell 寻找路径用的是 PATH 环境变量，通过以下命令查看 emacs 继承到的 PATH 变量值：

  (getenv "PATH")
  

  如果要修改这个值，比如像 bash 里

  export xxx:$PATH
  

  可以用类似以下方式：

  (setenv "PATH" (concat (concat conda_dir "/envs/usr/bin:") (getenv "PATH")))
  

  shell-command* 接口比较方便，只要知道这个程序怎么从命令行执行，照搬过来即可。

• 通过 start-process 函数，这时 emacs 从 exec-path 变量去找程序的具体路径，由于这是一个 elisp 变量，可以用 describe-variable 查看。start-process 不需要先启动 shell, 执行效率会更高一点，但执行命令的接口更复杂，需要仔细查看文档了解（包括执行二进制对象的文档）

一些案例（经验结果，可能有偏差）：

• quickrun 是根据 PATH 路径来寻找二进制，因为它实际是调用 shell-command 命令来运行程序
• dired, flycheck, org-babel 是 emacs 内置功能，使用 start-process 根据 exec-path 里的路径去寻找可执行程序。
• org 里打开 http 链接默认需要 PATH 变量，因为是在 shell-command* 里执行 xdg-open
• emacs-jupyter 需要找到 jupyter 二进制，通过异步执行 shell 命令启动 jupyter, 因此查找的是 PATH
• latex 预览同时需要 exec-path 和 PATH ，因为预览涉及多个进程，比如可能 start-process 执行 latex 主函数，shell-command 执行转 svg 的进程，这部分我没有深究，但曾经试过从 exec-path 或 PATH 中分别删除 latex 路径，发现预览 latex 均会出问题。

然而，个人使用场景下没有必要区分 PATH 和 exec-path，因为它们在打开 emacs 时继承的都是启动环境里的 PATH 环境变量。我是通过以下 open_emacs 脚本来启动 emacs 的，需要什么路径（比如 conda）通过 export 导入即可，之后不会再手动修改这两个值，因此它们始终保持一致。

#!/usr/bin/env bash
# 打开不同 配置 的 emacs 方式, 但基本只用默认的

export PATH=$HOME/miniconda3/envs/usr/bin:$PATH
version=${version:-29.2}
em=~/codes/emacs-${version}/src/emacs
emc=~/codes/emacs-${version}/lib-src/emacsclient
if [ "$1" == 'default' ]; then
    if [ ! -z $2 ]; then
        $em --name "$2"
    else
        $em
    fi
	#systemctl restart --user emacsanywhere.service
elif [ "$1" == 'client' ]; then
    $emc -c
elif [ "$1" == 'test' ]; then
	$em --init-directory ~/.wemacs_test/
else 
	$em
fi

这部分在 i3wm: 无关生产力，且远不止窗口管理 文章里也有提到。

使用 emacs-jupyter 和 eaf (目前主要用 eaf-mindmap 展示 org 文件层级结构) 都依赖 python 环境, 比如 emacs-jupyter 需要在环境中安装 jupyter 。因此最好为 emacs 创建了一个特定的 python 环境（比如名为 usr），先用以下命令安装 jupyter 以支持 emacs-jupyter：

conda install jupyter

对于 eaf ，如果执行 ./install-eaf.py 命令来初始化, 在 conda 环境中会采用 pip --user 的方式安装包，从而把 pip 包都安装到 ~/.local/lib 中，该目录是所有 conda 环境共享的，不属于特定 conda 环境，打破 conda 的隔离容易带来混乱，conda list 也不会显示该目录下的包，所以还是手动进入到 conda 环境用以下方式安装 eaf 依赖：

pip install epc tld lxml PyQt6 PyQt6-Qt6 PyQt6-sip PyQt6-WebEngine PyQt6-WebEngine-Qt6

此外用 ./install-eaf.py -i mind-map 安装时由于使用 https 连接，有时候网络很慢，因此手动用 git@ 方式安装具体的 eaf app:

git clone -b master --depth 1 git@github.com:emacs-eaf/eaf-mindmap.git app/mindmap

注意这里命名不需要 eaf- 前缀，否则会找不到。

eaf 核心配置如下

(use-package eaf
  :load-path "site-lisp/emacs-application-framework/"
  :commands eaf-open-mindmap
  :config
  (require 'eaf-mindmap)
  <<eaf-key-bindings>>
  )

以上通过 :commands eaf-open-mindmap 设置令 eaf 只在执行特定命令后启动，以免 emacs 一启动就在后台创建一个 eaf 进程。

<<eaf-key-bindings>> 部分是一些改键设置，不展示具体代码了。

除了前文提到的 open_emacs 脚本，个人还有其他几种 emacs 启动入口：

• 用 org-publish 发布 blog: orgchange: 文学编程式 org mode 静态网页生成器 。 它不依赖个人 emacs 配置和插件，并且可以对每篇文章设置单独的 emacs 程序。

• 将 emacs 作为一次性命令来执行

  比如用来 tangle 出配置，更新 org-ids 等，这些操作如果在当前运行的 emacs 中进行，往往会打开大量 buffer 或者比较耗时导致 emacs 卡顿，而它们又只使用到少量的和个人交互无关的配置，因此分离出单独的脚本进行执行，这在 org roam 风格的系统配置文件管理 里也提到过。

  .SILENT:
  .SUFFIXES:
  .PHONY: clean
  
  wemacs-tangle:
        emacs --batch -l ~/metaesc/make_tangle.el --eval "(tangle-config-file \"init\")"
        emacs
  
  update-org-ids:
      emacs --batch \
            --eval '(setq org-directory "~/org")' \
            --eval '(setq org-id-locations-file "~/.wemacs/.org-id-locations")' \
            --eval '(require (quote org-id))' \
            --eval '(org-id-update-id-locations (directory-files-recursively org-directory "\\.\\(org\\|gtd\\)"))'
  

  emacs --batch 是不会去加载 ~/.emacs.d 目录下的配置文件的，因此它也是独立于个人 emacs 配置的。

• emacsclient 快速启动脚本 emacsclinet 一般只是发信息给已经启动的 emacs server, 因此它的配置就是 emacs 本身的配置。

  • ~/metaesc/lib/i3-emacs-publish.sh

    先用 emacsclient 启动一个窗口，在其中打开 shell buffer, 然后执行 blog 的发布命令，虽然发布命令和个人 emacs 配置无关，但启动 emacsclient 是与本文配置相关的。

  • ~/metaesc/lib/i3-emacs-quicknote.sh

    emacsclient 直接打开日记 buffer, 前文提到的 "lazy load" 记录方式的实现, 依赖于 evil.

  • ~/metaesc/lib/i3-emacs-xwish.sh

    emacsclient 打开 ivy-minibuffer 并且导入当前的窗口信息进行选择交互，依赖 evil 和 ivy ，因此 ivy 配置有比较大变化饿化，最好应该测试一下该脚本。

  这些脚本都放在 metaesc/lib at main · metaescape/metaesc 之中

以下是 evil 配置的总览，一些解释：

• ctrl-u 在 emacs 中是一个前缀按键，个人很少使用（改成 C-M-u）, 通过 evil-want-C-u-scroll 来更改为 page up(half)
• 如果没有 (setq evil-want-C-i-jump nil) ，会影响 tab 按键的功能， org src block 中换行时都不会自动缩进，比较奇怪。

(use-package evil
  :init
  (setq evil-want-Y-yank-to-eol t)
  (setq evil-want-integration t)
  (setq evil-want-keybinding nil)
  (setq evil-want-C-u-scroll t)
  (setq evil-want-C-i-jump nil)
  :config 
  (evil-mode 1)
  <<evil-esc>>
  <<evil-undo-fu>>
  <<evil-collections>>
  <<expand-region>>
  <<evil-surround>>
  <<evil-commentary>>
  <<evil-multiedit>>
  <<evil-select-paste>>
  <<snipe-pinyin>>
  <<avy-ace-pinyin>>
  <<evil-9line>>
  <<ex-quit-buffer>>
  (general-define-key
   :keymaps '(visual)
   "DEL" (lambda ()
           (interactive)
           (evil-delete (region-beginning) (region-end) nil ?_))))

<<evil-basic>>

esc 绑定的 keyboard-escape-quit 在有些场合下会失效，从 dotfiles/Emacs.org at master · SqrtMinusOne/dotfiles 拷贝了 minibuffer-keyboard-quit 函数作为增强。

(global-set-key (kbd "<escape>") 'keyboard-escape-quit)
(defun minibuffer-keyboard-quit ()
  "Abort recursive edit.
In Delete Selection mode, if the mark is active, just deactivate it;
then it takes a second \\[keyboard-quit] to abort the minibuffer."
  (interactive)
  (if (and delete-selection-mode transient-mark-mode mark-active)
      (setq deactivate-mark  t)
    (when (get-buffer "*Completions*") (delete-windows-on "*Completions*"))
    (abort-recursive-edit)))

  (general-define-key
   :keymaps '(normal visual global)
   [escape] 'keyboard-quit
   )

(general-define-key
 :keymaps '(minibuffer-local-map
            minibuffer-local-ns-map
            minibuffer-local-completion-map
            minibuffer-local-must-match-map
            minibuffer-local-isearch-map)
 [escape] 'minibuffer-keyboard-quit)

不使用 undo-tree.el (作者不太维护了), undo-fu 为线形 undo 管理

(use-package undo-fu
  :config
  (define-key evil-normal-state-map "u" 'undo-fu-only-undo)
  (define-key evil-normal-state-map "\C-r" 'undo-fu-only-redo))

evil 包主要在 emacs 中一般的 buffer 里引入 vim 按键，而 minibuffer 等其他窗口的按键可能并没有被覆盖，因此加入以下额外增强：

• evil collection 中包含大量的 el 配置文件，针对不同的场景，将 vim 风格推广到其他 mode/window 中，例如使用按键 q 来退出只读 buffer
• evil 对 orgmode 的融合比较粗糙，用 evil-org 弥补, 这包括：
  • 对 agenda 添加一个 evil 层
  • 删除字符时保持 org-tag 或表格对齐
  • 更多 textobj 例如 vie/vae 选择当前最小的 org element, 比如 org-emphasis-alist 里的对象，时间戳等
  • >> 和 << 进行 org-tree 的 promote 和 demote

  • o/O 会尊重 org 结构，比如在表格里插入一行，则默认下一行是一个空的表格行，而不是纯空行

    不过这里用 go 和 gO 来标示纯结构化插入， o 和 O 还是保持原始的空行，需要用 evil-define-key 来覆盖（参考 evil-org.el 代码）

  • 我只需要其对 agenda 的增强以及 textobj, 因此以下只开启了 (textobjects)
  • 最后修改 enter 键，在 normal 下是打开 org 链接
• 最后的 hook 是为了在 c-c c-q 或者 clock-done 时进入 log buffer 自动切换到 insert 状态便于马上记录

(use-package evil-collection
  :after evil
  :config
  (evil-collection-init))

(use-package evil-org
  :after org
  :hook (org-mode . (lambda () (evil-org-mode +1)))
  :config
  (require 'evil-org-agenda)
  (evil-org-agenda-set-keys)
  ;; (evil-org-set-key-theme '(navigation insert textobjects additional calendar))
  (evil-org-set-key-theme '(textobjects))
  
  (general-define-key
   :keymaps '(org-mode-map)
   :states '(normal visual)
   "<return>" 'org-open-at-point)
  
  (evil-define-key 'normal 'evil-org-mode
    (kbd "go") 'evil-org-open-below
    (kbd "gO") 'evil-org-open-above
    (kbd "o") 'evil-open-below
    (kbd "O") 'evil-open-above
    (kbd "<") 'org-promote-subtree
    (kbd ">") 'org-demote-subtree
  ))

(add-hook 'org-log-buffer-setup-hook 'evil-insert-state)

expand-region 作为 evil text object 的补充，连续按 v 会不断扩大选择，不过一般就按 2 到 3 下

(use-package expand-region
  :general
  (:keymaps 'visual
            "v" 'er/expand-region)
  :config
  (setq expand-region-contract-fast-key "z"))

通过 csi- 替换括号， visual mode 下 S- 添加括号

(use-package evil-surround
  :config
  (global-evil-surround-mode 1))

主要就是按 gcc 后根据不同语言的语法进行注释

(use-package evil-commentary
  ;; :diminish evil-commentary
  :config
  (evil-commentary-mode)
)

这个包的作用是，当选中某个词后，绑定 n/N 为继续选中 下/上一个相同的词，之后可以同步修改这些选中的词汇。

(use-package evil-multiedit
  :load-path "site-lisp/evil-multiedit"
  ;; git@github.com:metaescape/evil-multiedit.git
  :general
   (:keymaps '(evil-visual-state-map)
   ;; Highlights all matches of the selection in the buffer.
   "R" 'evil-multiedit-match-all
   ;; incrementally add the next unmatched match.
   "n" 'evil-multiedit-match-and-next
   "N" 'evil-multiedit-match-and-prev ;; p for evil past
   )
   (:keymaps '(evil-multiedit-state-map) 
   "SPC" 'evil-multiedit-toggle-or-restrict-region
   "ESC" 'evil-multiedit-abort
   "C-j" 'evil-multiedit-next
   "C-k" 'evil-multiedit-prev
   "n" 'evil-multiedit-match-and-next
   "N" 'evil-multiedit-match-and-prev
   )
   (:keymaps '(evil-multiedit-insert-state-map) 
   "C-j" 'evil-multiedit-next
   "C-k" 'evil-multiedit-prev
   )
  :config
  (define-key evil-motion-state-map (kbd "RET") 'evil-multiedit-toggle-or-restrict-region)
  ;; Ex command that allows you to invoke evil-multiedit with a regular expression, e.g.
  (evil-ex-define-cmd "ie[dit]" 'evil-multiedit-ex-match))

其最新版把 evil-multiedit-state-map 和 evil-multiedit-insert-state-map 合并成了 evil-multiedit-mode-map(只有 insert 情况下), 使得不能用 ESC 结束，而且无法用 n 和 N 来扩大范围。 因此不使用 melpa 包来安装了，直接用个人 fork 下来的旧版本： metaescape/evil-multiedit: forked evil-multiedit。

选中文本后按 p 粘贴，evil 默认会先先插入粘贴文本，然后将选中文本 kill 掉，因此选中的文本就会覆盖当前的粘贴板（register），也就无法连续替换，以下设置取消这种行为：

(setq-default evil-kill-on-visual-paste nil)

参考 In Evil mode, how can I prevent adding to the kill ring when I yank text, visual mode over other text, then paste over? - Emacs Stack Exchange

• snipe 可以用于单字符跳转（对 fFtT 的增强）和双字符跳转，个人只使用行内的单字符跳转。

  这个功能相当与 vim 里的 clever-f 插件功能。

• evil-find-char-pinyin 包可以给 snipe 提供中文拼音首字母和标点符号跳转，对选择中文很是方便。

(use-package evil-snipe
  :defer
  :config
  (evil-snipe-mode -1) ;; disabled 2 char jump
  (evil-snipe-override-mode +1) ;; enable 1 char jump
  (setq evil-snipe-scope 'line) ;; jump in line
)

(use-package evil-find-char-pinyin
  :config
  (evil-find-char-pinyin-toggle-snipe-integration t)
  (setq evil-find-char-pinyin-only-simplified t) ;; nil for traditional chinese
  (setq evil-find-char-pinyin-enable-punctuation-translation t) ;;punctuation
  )

• snipe 只在行内跳转， avy 则是用于在 window 或 frame 内跳转，当进入 avy 状态时，通过按目标对象（比如英文单词的前两个字母，中文词拼音首字母）就可以进行跳转了。
• ace-pinyin 之于 avy 正如 evil-find-char-pinyin 之于 evil-snipe, 提供额外中文拼音支持。另外 ace-pinyin 默认不支持 avy-goto-char-timer, 但个人觉得这才是 avy 最好用的接口, 有其他开发者提供这个功能，但 ace-pinyin 作者似乎不太维护没有合并，因此根据 Add function corresponding to avy-goto-char-timer by yangsheng6810 · Pull Request #17 · cute-jumper/ace-pinyin 自己加上这段代码。

(use-package avy
  :bind
  (:map evil-normal-state-map
        ("C-\\" . ace-pinyin-goto-char-timer))
  :config
  (setq avy-all-windows t) ;; jump to any buffer in window
  (setq avy-timeout-seconds 0.5)

  (use-package ace-pinyin
    :config
    (ace-pinyin-global-mode +1))

  (defun ace-pinyin--build-string-regexp (string)
    (pinyinlib-build-regexp-string
     string
     (not ace-pinyin-enable-punctuation-translation)
     (not ace-pinyin-simplified-chinese-only-p)))

  (defun ace-pinyin-goto-char-timer (&optional arg)
    "Read one or many consecutive chars and jump to the first one.
The window scope is determined by `avy-all-windows' (ARG negates it)."
    (interactive "P")
    (let ((avy-all-windows (if arg
                               (not avy-all-windows)
                             avy-all-windows)))
      (avy-with avy-goto-char-timer
        (setq avy--old-cands
              (avy--read-candidates #'ace-pinyin--build-string-regexp))
        (avy-process avy--old-cands))))

  (general-define-key
   :keymaps 'org-agenda-mode-map
   :states 'motion ;; agenda 下用 motion 代替 normal state
   "C-\\" 'ace-pinyin-goto-char-timer
   ))

默认 jk 会把折成多行的长句也看作是一行，不太自然，以下使得 jk 按照视觉上的行上下移动（折行以后算做多行），另外用 JK 作为多行移动。

用 evil-define-motion 这个宏来定义新的移动方式，然后用 define-key 在对应模式下绑定按键 这是最基础的绑定按键的方式， 这里 j k 全局设置会影响一些特殊 mode, 例如 image-mode

;; Use visual line motions even outside of visual-line-mode buffers
;; deal with wrap
(evil-global-set-key 'motion "j" 'evil-next-visual-line)
(evil-global-set-key 'motion "k" 'evil-previous-visual-line)

(evil-define-motion move-9-lines-down () (evil-next-visual-line 9))
(evil-define-motion move-9-lines-up () (evil-previous-visual-line 9))

(general-define-key
 :keymaps 'general-override-mode-map
 :states '(normal visual motion)
 "J" 'move-9-lines-down
 "K" 'move-9-lines-up
 )

默认 :q 是直接退出整个 emacs, 改为 kill buffer, 使用 :quit 完整退出（虽然基本不会用）

;; :q should kill the current buffer rather than quitting emacs entirely
(evil-ex-define-cmd "q" 'kill-this-buffer)
(evil-ex-define-cmd "wq" 'kill-this-buffer)
 ;; Need to type out :quit to close emacs
(evil-ex-define-cmd "quit" 'evil-quit)

参考： Making :q Not Kill Emacs : spacemacs

对输入英文内容补全时交互的核心是：

• Enter 或者 Tab 选择当前行（company 默认用 Enter 选词，tab 获取候选词里的最长公共前缀）
• C-j/k 或 M-n/p 上下移动 (company 默认有这两组方式，通过变量 company-active-map 查看按键)

除此之外会关注的就是补全效率和准确度了，但这一般不是用户能控制的，这与补全后端的能力有关，对于 company-backends 的顺序，参考的 Better Company | tychoish 。

对我来说 org 里最有帮助的 company 后端是 company-files,它在输入时补全文件路径， 对其他后端则没有太强的感知。

(use-package company
 :config
 (setq company-idle-delay 0) ;;default 0.2
 (setq company-echo-delay 0) ;;default 0.01
 (setq company-show-numbers t) 
 (setq company-minimum-prefix-length 2) ;;default 3
 (setq company-dabbrev-minimum-length 2) ;;default 4
 (setq company-selection-wrap-around t) ;;default nil, next of end is begin
 (setq company-dabbrev-downcase nil)
 (setq company-backends '(company-capf
                        company-keywords
                        company-semantic
                        company-files
                        company-dabbrev
                        company-etags
                        company-elisp
                        company-clang
                        company-cmake
                        company-yasnippet))
 (setq company-require-match nil)
 (global-company-mode)

 (use-package company-posframe
  :after company
  :hook (company-mode . company-posframe-mode)
  :config
  (use-package posframe) 
  )
 )

用 company-posframe 会使得候选框显示更整齐一点，默认的 popup 窗口有时候会影响周围文字的布局，这个包还自带了 company-quickhelp 显示文档的功能， 似乎也会在候选框最下方额外显示当前候选项的来源，比如是由 dabbrevs 从当前文档匹配还是 files 文件名。

smex 能够使得 counsel 显示的菜单按照使用频率排序

(use-package counsel
  :bind (("M-x" . counsel-M-x)
         ("C-x f" . counsel-find-file) ;;origin is set-fill-column
         :map org-mode-map
         ("C-c o" . counsel-org-goto)  ;; outline, similar to pdf/epub outline
         :map minibuffer-local-map
         ("C-r" . 'counsel-minibuffer-history))
  :config
  (setq ivy-initial-inputs-alist nil)
  (use-package smex)
  ;;将 c-c c-q(默认 org-set-tags-command) 定向为 counsel-org-tag
  ;;进入 tag 选择菜单后，通过 alt+enter 可以进行多选（选中当前而不退出）
  (global-set-key [remap org-set-tags-command] #'counsel-org-tag)
  )

默认情况下 counsel-M-x 会在初始时显示 "^" 这使得输入时正则搜索的是行首的字母，初始字符串由 ivy-initial-inputs-alist 变量决定，将其直接置为 nil, 参考： search - Counsel M-x always shows "^" - Emacs Stack Exchange

helpful 是构造了一个新的 buffer 类型，对 emacs 里函数的变量的帮助信息显示得更加丰富，查找 symbol 的时候也有一个搜索框， counsel 对该搜索交互有一定增强。

(use-package helpful
  :custom
  (counsel-describe-function-function #'helpful-callable)
  (counsel-describe-variable-function #'helpful-variable)
  :bind
  ([remap describe-function] . counsel-describe-function)
  ([remap describe-command] . helpful-command)
  ([remap describe-variable] . counsel-describe-variable)
  ([remap describe-key] . helpful-key))

vertico 系列比 ivy 控制度更好一点，但由于它在如下几个常用的功能上无法达到 ivy 的效果，所以目前没有使用。

• 没有 swiper-isearch 等价的功能，也就是搜索完成之后按 n/p 可以在刚才搜索完成的关键词上进行前后跳转
• rg 全项目搜索文档时支持拼音（首字母或者全拼），consult-grep 似乎无法做到
• consult-buffer 切换速度没有 ivy-switch-buffer 那么快（可能是其中 UI 更丰富了，对 buffer 和文件做了不同 section 的划分），同样 consult-line 似乎也没有 swiper-isearch 那么流畅。

以下是之前尝试 vertico 的代码，如果以后能够满足以上功能了，会重新考虑。

(use-package vertico
  :init
  (vertico-mode)
  :bind 
  (:map minibuffer-local-map
        ("C-j" . next-line)
        ("C-k" . previous-line)))

(use-package orderless
  :init
  (setq completion-styles '(orderless basic)
        completion-category-defaults nil
        completion-category-overrides '((file (styles partial-completion))))
  :config
  ;;from https://github.com/tumashu/pyim
  (defun my-orderless-regexp (orig-func component)
    (let ((result (funcall orig-func component)))
      (pyim-cregexp-build result)))

  (advice-add 'orderless-regexp :around #'my-orderless-regexp))

(use-package marginalia
  :bind
  (:map minibuffer-local-map
        ("C-l" . marginalia-cycle))
  :init
  ;; Marginalia must be activated in the :init section 
  (marginalia-mode))

(use-package nerd-icons-completion
  :after marginalia
  :config
  (nerd-icons-completion-mode)
  (add-hook 'marginalia-mode-hook #'nerd-icons-completion-marginalia-setup))

(use-package consult
  :config
  (general-define-key
   :keymaps '(general-override-mode-map org-agenda-mode-map)
   :states '(motion normal visual) ;; agenda 下用motion 代替 normal state
   "SPC" 'consult-buffer
   "/" 'consult-line
   )

  (advice-add 'consult--buffer-action :after #'my/buffer-switch-advice)
  (advice-add 'find-file-at-point :after #'my/buffer-switch-advice)

  ;; https://emacs-china.org/t/xxx-thing-at-point/18047/18
  (defun consult-delete-default-contents()
    (remove-hook 'pre-command-hook 'consult-delete-default-contents)
    (cond ((member this-command '(self-insert-command))
           (delete-minibuffer-contents))
          (t (put-text-property (minibuffer-prompt-end) (point-max) 'face 'default))))
  (consult-customize
   consult-line
   :initial (when-let ((string (thing-at-point 'word)))
              (add-hook 'pre-command-hook 'consult-delete-default-contents)
              (propertize string 'face 'shadow)))
  )

(use-package wgrep)

(use-package helpful
:bind
   ([remap describe-key]      . helpful-key)
   ([remap describe-command]  . helpful-command)
   ([remap describe-variable] . helpful-variable)
   ([remap describe-function] . helpful-callable))

pyim 是一个 emacs 中的中文处理库，提供了许多与中文处理相关的函数，例如检测光标当前字符是否是中文， 中文分词，或者将中文转换成拼音等，输入法是基于这些库实现一个高层的更复杂的应用。

• 由于 pyim 使用 elisp 实现，其好处是非常灵活，所有源码都在 emacs 包中，可以任意定制有关中文输入的按键交互功能。
• 同样由于使用 elisp 实现，pyim 把输入法的运行负担从系统转移到了 emacs， emacs 本身已经比较庞大，由于其他大量第三方插件代码，因此 pyim 有时会很卡，cpu 100% 以及 memory 占用超过 1 g 的情况常有发生，关闭 pyim 后性能会变好很多。因此我不把 pyim 作为输入法，而是使用其中提供的几个中文相关的功能，比如分词和按拼音搜索。

如 折腾emacs-rime 里所说："emacs-rime 是 RIME 输入法的 Emacs UI 前端，所有行为都通过 RIME 配置文件来配置", 因此实际上我们只需要安装 librime 库（作为后端）就可以了，对于 ubuntu 使用 sudo apt install librime-dev

更多安装和配置细节参考： rime 输入法

<<dashboard>>
(use-package tab-bar
  :ensure nil
  :config
  <<tab-utils>>
  <<switch-tab-by-name-num>>
  <<quick-switch-back>>
  <<confirm-scratch-delete>>
  <<windmove-ibuffer>>
  (use-package popwin
    :config
    (popwin-mode 1))

  (use-package winner 
    :ensure nil
    :hook (after-init . winner-mode))
  )

以上还开启了 popwin, 这会把一些特殊窗口变成临时窗口，用 C-g 可以退出。 winner-mode 开启之后可以通过 winner-undo 和 winner-redo 来进行切换窗口布局，对应 c-c left 和 c-c right, 重新绑定为 ,h 和 ,l 。

<<tab-bar>>

(tab-bar-mode 1)
(setq tab-bar-new-button-show nil)
(setq tab-bar-close-button-show nil)
(setq tab-bar-show 1)
(setq tab-bar-tab-hints t) ;; show number
(setq tab-bar-auto-width nil) ;; 取消自动 padding 大小(29.2 引入)
(setq tab-bar-format '(tab-bar-format-tabs tab-bar-separator tab-bar-format-align-right tab-bar-format-global))
(defun my/update-tab-bar-after-theme-change (&rest _args)
  "Update tab bar face attributes after a theme change."
  (set-face-attribute 'tab-bar-tab nil
                      :inherit 'doom-modeline-panel
                      :foreground 'unspecified
                      :background 'unspecified)

  (set-face-attribute 'tab-bar nil
                      :foreground (face-attribute 'default :foreground)))

(advice-add 'load-theme :after #'my/update-tab-bar-after-theme-change)
(my/update-tab-bar-after-theme-change)

说明：

• tab-bar-format 内容默认是：

  (tab-bar-format-history tab-bar-format-tabs tab-bar-separator tab-bar-format-add-tab)
  

  • tab-bar-format-history 会在 tabbar 最左边显示左右箭头，按历史记录返回之前或之后的 tab, 但一般不用，默认 tab-bar-history-mode 是 nil, 因此即便添加了这个 history format, 也不会显示
  • tab-bar-format-add-tab 是在 tab 名称右侧添加一个 + 号按钮，点击后新建一个 tab, 这个也不用，因此设置了 (setq tab-bar-new-button-show nil), 所以即便 format 里添加了该区域也不会显示，如果真要用鼠标创建 tab ，用右键也能弹出新建 tab 选项。
  • 因此删除了以上两个 section 后添加了 tab-bar-format-align-right tab-bar-format-global, 这可以把 org-clock 信息实时显示在 tab-bar 最右侧，这比显示在每个 buffer 的 modeline 上更合理，因为 org-clock 信息本身就是 emacs 全局的，而不是 buffer local 的（tab-bar-format-global 是 Emacs28 后引入的）
• 由于每次切换主题之后，tabbar 选中颜色变得很淡，因此要在主题切换后添加一个颜色恢复的函数，这里用 advice 恢复 face

绑定 M-digital 切换 tab, 如果当前已经再第 n 个 tab, 按 M-n 会返回上一个 tab.

(defun switch-to-tab-by-number (num)
  (let ((current-prefix-arg num)  ;; emulate C-u num
        (current-tab-index (tab-bar--current-tab-index)))
    ;; (update-ivy-tabs)
    (if (equal (1+ current-tab-index) num) ;; num start from 1
        (tab-bar-switch-to-recent-tab)
      (call-interactively 'tab-select))))

(general-define-key
 :keymaps 'general-override-mode-map
 "M-1" '(lambda () (interactive) (switch-to-tab-by-number 1))
 "M-2" '(lambda () (interactive) (switch-to-tab-by-number 2))
 "M-3" '(lambda () (interactive) (switch-to-tab-by-number 3))
 "M-4" '(lambda () (interactive) (switch-to-tab-by-number 4))
 "M-5" '(lambda () (interactive) (switch-to-tab-by-number 5))
 "M-6" '(lambda () (interactive) (switch-to-tab-by-number 6))
 "M-7" '(lambda () (interactive) (switch-to-tab-by-number 7))
 "M-8" '(lambda () (interactive) (switch-to-tab-by-number 8))
 "M-9" '(lambda () (interactive) (switch-to-tab-by-number 9))
 )

这里视图的定义是：buffer, tab 和 window, 它们有各自的 "跳转到上一个" 的接口：

• other-buffer
• tab-bar-switch-to-recent-tab
• evil-window-mru

本节则根据 context switch 的情况把这几个切换统一起来：

• 如果上一次是 *-buffer-switch/find-file, 那么应该在当前窗口跳转到切换前的 buffer
• 如果上一次是 avy-goto, 那么应该执行 avy-popmark, 返回到跳转前位置
• 如果上一次是 tab switch, 那么应该是 tab-bar-switch-to-recent-tab
• 如果当前是一些临时窗口，那么直接关闭这个窗口，这时光标会回到打开临时窗口前的 buffer
• （可选）如果上一次是 windmove* 操作, 那么应该执行 evil-window-mru, 它定位到当前 frame 中上一次光标所在的另外一个窗口中（类似 avy-popmark, 但只会回到另一个窗口）

上节 switch-to-tab-by-number 中已经用 last-switch-action 变量记录操作类型了，本节对更多操作加上记录切换类型的 hook/advice

因为大部分时间是用 ivy-switch-buffer 来切换 buffer 的，于是对 ivy–switch-buffer-action 加 advice 。注意 advice 不应该加在 switch-to-buffer 上, 因为该函数太过"底层", 覆盖面太细，比如打开 hydra buffer 或者 minibuffer 都会记录成 buffer-switch, 但这些 buffer 往往也是临时的，不希望它们被记录为值得回顾的 buffer。

(defvar last-switch-action nil)
(defun my/tab-switch-advice (&rest _) (setq last-switch-action "tab-switch"))
(defun my/buffer-switch-advice (&rest _) (setq last-switch-action "buffer-switch"))
(defun my/avy-goto-advice (&rest _) (setq last-switch-action "avy-goto"))

(advice-add 'switch-to-tab-by-number :after #'my/tab-switch-advice)
(advice-add 'ivy--switch-buffer-action :after #'my/buffer-switch-advice)
(add-hook 'find-file-hook 'my/buffer-switch-advice)
(advice-add 'ace-pinyin-goto-char-timer :after #'my/avy-goto-advice)

(defun my/switch-back ()
  "Switch to the recent buffer, or destoried window configuration."  
  (interactive)
  (cond 
   ((member major-mode '(special-mode
                             messages-buffer-mode
                             helpful-mode
                             magit-status-mode
                             help-mode
                             Custom-mode
                             ibuffer-mode
                             debugger-mode
                             org-roam-mode
                             compilation-mode))
    (quit-window))
   ((member major-mode '(package-menu-mode))
    (switch-to-buffer (other-buffer (current-buffer) nil)))
   ((equal last-switch-action "window-switch")
    (evil-window-mru))
   ((equal last-switch-action "avy-goto")
    (avy-pop-mark))
   ((equal last-switch-action "tab-switch")
    (tab-bar-switch-to-recent-tab))
   ((equal last-switch-action "buffer-switch")
    (switch-to-buffer (other-buffer (current-buffer) nil)))))

(general-define-key
 :keymaps '(general-override-mode-map org-agenda-mode-map eaf-mode-map*)
 :states '(motion normal visual) ;; agenda 下用motion 代替 normal state
 "gq" 'my/switch-back)

一般来说，不要删除这个 buffer, 因为里面会放许多尝试性代码，因此加一个确认提醒

(defun my/confirm-kill-scratch-buffer (orig-fun &rest args)
  "Confirm before killing the *scratch* buffer."
  (let ((buffer-to-kill (car args)))
    (if (and (get-buffer "*scratch*") 
             (equal buffer-to-kill (get-buffer "*scratch*"))
             (not (yes-or-no-p "*scratch* Don't want to be Killed, Confirm? ")))
        (message "Aborted")
      (apply orig-fun args))))

(advice-add 'kill-buffer :around #'my/confirm-kill-scratch-buffer)

• 用于显示启动页面，可以添加图片、展示启动时间等，此外绑定 R 为 desktop-read
• initial-buffer-choice 是保证已经启动 emacs server 情况下再启动一个 emacs 还是会显示 dashboard, 方便修改配置后新启动一个 emacs 进程看启动时间。

(use-package dashboard
  :config
  (dashboard-setup-startup-hook)
  (setq dashboard-center-content t)
  (setq dashboard-items '((recents  . 5)
                          (bookmarks . 5)
                          (projects . 5)
                          ))
  (setq initial-buffer-choice (lambda () (get-buffer-create "*dashboard*")))
  (setq dashboard-startup-banner "/data/resource/pictures/dashboard/moutain.png")
  (setq dashboard-image-banner-max-width 300)
  (setq dashboard-banner-logo-title "don't panic") ;;nil to delete

  (setq dashboard-set-navigator t)
  ;; Format: "(icon title help action face prefix suffix)"
  (setq dashboard-navigator-buttons
        `(;; line1
          ((,(nerd-icons-mdicon
              "nf-md-dock_window"
              :height 1.1 :v-adjust 0.0)
            "desktop-read (R)"
            ""
            (lambda (&rest _) (desktop-read))))))

  (setq dashboard-set-file-icons t)
  (setq dashboard-footer-messages '("-------------------"))
  (setq dashboard-display-icons-p t) ;; display icons on both GUI and terminal
  (setq dashboard-icon-type 'nerd-icons) ;; use `nerd-icons' package

  (general-define-key
   :keymaps '(dashboard-mode-map)
   :states 'normal
   ;; "gd" 'evil-goto-definition
   "R" 'desktop-read)
  )

• 窗口和 buffer 操作都是全局的，emacs 中由于有非常多 mode,每个 mode 有各自的 keybinding 无法对每个 mode 都进行改建，如果要覆盖所有 mode, 用以下 general-override-mode-map
• 对 Ibuffer mode 修改， 默认 , 是 sort, 取消掉

(general-define-key
 :keymaps 'general-override-mode-map
 :states '(normal insert visual motion)
 "M-h" 'windmove-left
 "M-l" 'windmove-right
 "M-j" 'windmove-down
 "M-k" 'windmove-up)

(use-package ibuffer
  :defer
  :config
  (general-define-key
   :keymaps 'ibuffer-mode-map
   :states 'normal
   "," nil 
   "s," 'ibuffer-toggle-sorting-mode
   "SPC" 'switch-to-buffer))

(use-package org
  :ensure nil
  :init 
  (setq org-ellipsis " ▾")
  (global-set-key (kbd "C-c l") 'org-store-link)
  (bind-key "C-c n" 'narrow-or-widen-dwim)
  :hook (org-mode . efs/org-mode-setup)
  :config
  (require 'ol-man) ;; support follow link in woman buffer
  (setq org-id-method 'ts)
  (setq org-image-actual-width nil)
  <<basic-ui>>
  <<org-appear>>
  <<visual-fill-column>>
  <<narrow-or-widen-dwim>>
  <<org-file-apps>>
  <<read-org-block-by-name>>
  )

说明：

• (setq org-image-actual-width nil) 使得可以通过 #+ATTR_ORG: :width 100 来定制 org inline image 大小
• org-id-method 有三个选项：
  • org: 生成内容是一个对时间的 hash 值 :ID: he4fkbc0lhj0
  • ts: 时间戳方式 :ID: 20220615T100541.162502, 这种方式至少有意义的
  • uuid: 全局的 hash 值
• c-c l快捷绑定是 org mode 文档里所推荐的 Activation (The Org Manual)

<<org>>

以下拷贝自 https://gist.github.com/mwfogleman/95cc60c87a9323876c6c, 用于在 narrow subtree 或 winden 之间切换

(defun narrow-or-widen-dwim ()
  "If the buffer is narrowed, it widens. Otherwise, it narrows to region, or Org subtree."
  (interactive)
  (cond ((buffer-narrowed-p) (widen))
        ((region-active-p) (narrow-to-region (region-beginning) (region-end)))
        ((equal major-mode 'org-mode) (org-narrow-to-subtree))
        (t (error "Please select a region to narrow to"))))

通过该变量控制 org 连接里文件的打开方式，比如 mp4 会通过 vlc 打开

(setq org-file-apps
      '((auto-mode . emacs)
        (directory . emacs)
        ("\\.mp4\\'" . "vlc \"%s\"")
        ("\\.mp3\\'" . "vlc \"%s\"")
        ("\\.mm\\'" . default)
        ("\\.x?html?\\'" . default)
        ("\\.pdf\\'" . default)))

这属于操作 org 中 src block 的常用库函数，之后会用到，比如 clock out 的时候

(defun my/read-org-block-by-name (file block-name)
  "Read the content of a named org-mode block from
a file."
  (with-temp-buffer
    (insert-file-contents file)
    (goto-char (point-min))
    (if (re-search-forward (concat "^#\\+name: " (regexp-quote block-name)) nil t)
        (when (re-search-forward "^#\\+begin_src" nil t)
          (forward-line)
          (beginning-of-line)
          (let ((start (point)))
            (if (re-search-forward "^#\\+end_src" nil t)
                (string-trim (buffer-substring-no-properties
                              start
                              (match-beginning 0)))
              (error "End of source block not found"))))
      (error "Named block not found"))))

(defun my/jump-to-org-block-by-name (file block-name)
  "Jump inside the src block with name: block-name in the specified file."
  (find-file file)  ; 打开文件
  (goto-char (point-min))  ; 移动到 buffer 的开始位置
  (if (re-search-forward (concat "^#\\+name: " (regexp-quote block-name)) nil t)
      (when (re-search-forward "^#\\+begin_src" nil t)
        (forward-line 1)  ; 移动到 #+begin_src 的下一行
        (beginning-of-line))
    (error "Named block not found")))

(my/jump-to-org-block-by-name "~/org/historical/projects.gtd" "timeout")

有以上函数之后，还可以精确地 tangle 出 org 文件里不同的 src block, 但实际不是很有必要，因为对于零散的脚本，直接用 include 方式引用即可，跳转也是方便的。

• 首先取消默认的 C-' 和 C-, 两个按键，他们默认都帮定为 org-cycle-agenda-files, 但由于我只有两个 agenda 文件，并且几乎不会用它取循环查看文件，因此解除绑定。
• 接着就是设置两个核心文件为 org-agenda-files, 并且设置一些根据年月份动态获取 archive 文件的函数
• get-current-archive-file-location 是返回当前时间对应的单个 archive 文件，同时包括 "::" 后缀，这是 org-archive-location 变量的要求。
• get-gtd-files-by-year 是包括了 org-agenda-files 以及当年的 archive 文件，用于设置 clocktable 的搜索范围
• get-current-journal-file 和 get-current-archive-file-location 类似，只不过这里纯粹是获得文件路径

(global-unset-key (kbd "C-'"))
(global-unset-key (kbd "C-,"))

(setq gtd-project-file "~/org/historical/projects.gtd"
      gtd-inbox-file "~/org/historical/inbox.gtd")

(setq org-agenda-files (list gtd-project-file gtd-inbox-file))

(defun get-archive-files-by-year (&optional year)
  (let ((year (or year "")))
    (file-expand-wildcards (format "~/org/historical/archive/%s*.org" year))))

(defun get-current-archive-file-location ()
  (format
   "~/org/historical/archive/%s%s.org::"
   (format-time-string "%Y")
   (if (<= (string-to-number (format-time-string "%m")) 6) "a" "b")))

(defun get-current-journal-file ()
  (format
   "~/org/self/journal/j%s%s.org"
   (format-time-string "%Y")
   (if (<= (string-to-number (format-time-string "%m")) 6) "a" "b")))

(defun get-gtd-files-by-year (&optional year)
  (append org-agenda-files
          (get-archive-files-by-year year)))

(defun my/set-archive-location (&rest _)
  "设置 org-archive-location 为当前存档文件的位置。"
  (setq org-archive-location (get-current-archive-file-location)))

;; defalult (time file olpath category todo itags)
(setq org-archive-save-context-info '(time))
(advice-add 'org-archive-subtree :before #'my/set-archive-location)

org-archive-save-context-info 只设置为 time，这样 archive 后，subtree 中只保留 archive 的时间，因为：

• 所有 archive 的任务来自于 projects.gtd，所以不需要 file 关键字来记录它是从哪个文件转移成存档的
• 我都是在某个大任务下的所有子任务都标记为 DONE 后才对整个任务树进行存档，因此 olpath 也不需要（它会记录父节点等信息）
• 同样由于只存档已经完成的大任务，因此 todo 信息也不需要
• 基本也不用 category 修饰 org tree, 故 category 字段也不需要。

最后，在 org-archive-subtree 函数加入一个 advice, 在执行该函数前，先设置动态的 archive 文件路径

以下命令可以查看 agenda files 以及 agenda files 关联的 archive 文件：

(org-agenda-files t org-id-search-archives)

只需要以下四个任务状态：

• TODO 还没开始的任务
• NEXT 已经开始正在进行的任务
• DONE 已经完成的事情
• CANCELED 取消的任务

定义类型时，如果有 ! 修饰表示进入该状态后会自动生成 timestamp, @表示会要求添加状态转移记录

(setq org-todo-keywords
      '((sequence "TODO(t)" "NEXT(n)" "|" "DONE(d@/!)" "CANCEL(c@/!)")))

;; TODO color
(setq org-todo-keyword-faces
   '(
    ("TODO" .      (:foreground "orange" :weight bold))
    ("NEXT" .      (:foreground "yellow" :weight bold))
    ("DONE" .      (:foreground "green" :weight bold))
    ("CANCEL" .     (:foreground "gray40"))
))

(setq org-log-into-drawer t) ;; add logbook
(setq org-log-done 'time) ;; add CLOSED: timestamp when task done

(setq org-tag-alist '( ("noexport" . ?n)))

可以通过 counsel-org-tag (c-c c-q) 选择添加 org-tag-alist 列表里定义的 tag, 但实际上自己很少使用 tag, 基本只需要 noexport 用来控制 blog 导出。

agenda 可以显示不同时间段的任务完成和计划情况，但我主要用它来查看当天的概览，将其成为 main-agenda

主 agenda 视图分为三栏：

• 当天已经处理的任务概览（Day Agenda）： 需要设置 org-agenda-start-with-log-mode 为 t
• 各个大任务中下一个不是 DONE 状态的任务（标题为 GO）
• inbox 中的项目（可选，目前不太用，一般直接打开 inbox.gtd 即可）

(setq org-agenda-block-separator nil)
(setq org-agenda-start-with-log-mode t) ;; show log

(setq org-agenda-todo-view
      `(" " "Agenda"
        ((agenda ""
                 ((org-agenda-span 'day)
                  (org-agenda-start-with-log-mode t)
                  (org-agenda-log-mode-items '(closed clock state))
                  (org-deadline-warning-days 14)))
         (todo "TODO|NEXT"
               ((org-agenda-overriding-header "GO")
                (org-agenda-sorting-strategy '(priority-down effort-up))
                (org-agenda-files '(,gtd-project-file))
                (org-agenda-skip-function #'org-agenda-skip-all-siblings-but-first)
                ))
         (search "^* \\.*"
               ((org-agenda-overriding-header "Inbox Processing")
                (org-agenda-files '(,gtd-inbox-file))))
         nil)))

(defun org-agenda-skip-all-siblings-but-first ()
  "Skip all but the first non-done entry."
  (let (should-skip-entry)
    (unless (org-current-is-todo-or-next)
      (setq should-skip-entry t))
    (save-excursion
      (while (and (not should-skip-entry) (org-goto-sibling t))
        (when (org-current-is-todo-or-next)
          (setq should-skip-entry t))))
    (when should-skip-entry
      (or (outline-next-heading)
          (goto-char (point-max))))))

(defun org-current-is-todo-or-next ()
  (or (string= "TODO" (org-get-todo-state))
      (string= "NEXT" (org-get-todo-state))))

(setq org-agenda-prefix-format
      '((agenda . "%?-8t%-3e% s")
        (todo . "%-6:c %-6e")
        (tags . "%-12:c")
        (search . "%-12:c")))

(add-to-list 'org-agenda-custom-commands `,org-agenda-todo-view)

org-agenda-skip-all-siblings-but-first 是查看文件中项目第一个未完成子任务的函数，它参考了 https://emacs.cafe/emacs/orgmode/gtd/2017/06/30/orgmode-gtd.html

以上 org-agenda-prefix-format 默认如下，为了适合小窗口显示，删除了 %c（文件名前缀，因为都来自 projects.gtd），并且调整间距。

((agenda . " %i %-12:c%?-12t% s")
 (todo . " %i %-12:c")
 (tags . " %i %-12:c")
 (search . " %i %-12:c"))

参考：.emacs.d/init.el at master · jethrokuan/.emacs.d

每次调用 org-agenda 时，它都要扫描 org-agenda-files 来临时构造一个视图 buffer, 而 clocktable 则是 org 里的一个可执行的代码块，可以指定需要扫描的文件从中抽取出某个时间段的任务情况总结。

clocktable 格式如下（通过 yasnippet 插入）：

#+BEGIN: clocktable :maxlevel 1 :emphasize nil :scope (lambda () (get-gtd-files-by-year 2023)) :block 2023-W3

#+END: clocktable

其中年份 2023 和周 2023-W3 是根据插入时的年份动态生成的（yasnippet 里设置）， :scope 里是一个函数，执行该函数后会返回 projects.gtd, inbox.gtd 以及当年的 archive 文件。

以下函数使得按 ctrl-c-ctrl-c 的时候，如果识别到当前光标在 clocktable block 内, 则执行 org-dblock-update 更新其中的内容，

(defun my/update-clocktable-if-appropriate ()
  "Update clocktable if the point is in a paragraph within a clocktable block."
  (let ((element-type (org-element-type (org-element-context))))
    ;;(prin1 element-type)
    (when (and
           (or (eq element-type 'paragraph)
               (eq element-type 'table-row))
           (save-excursion
             (let ((current-point (point))
                   (begin-found (search-backward "#+BEGIN: clocktable" nil t)))
               (if begin-found
                   (progn
                     ;; Reset position for the next search
                     (goto-char current-point)
                     (let ((end-found (search-forward "#+END: clocktable" nil t)))
                       (and end-found
                            (<= begin-found current-point)
                            (>= end-found current-point))))
                 nil))))
      (org-dblock-update)
      t)))  ; Return non-nil to indicate the hook has done something.

(add-hook 'org-ctrl-c-ctrl-c-hook 'my/update-clocktable-if-appropriate)

这部分想达到的一个效果是：

• 每次 clock in 后自动设置默认 org-effort 为 25 分钟，类似番茄时钟。目的是让自己对每个任务都尽可能分解到 25 分钟以内完成，如果超过则拆分成多个， 这样可以促使自己去思考如何更细地分解任务，另一方面自己投入太长时间其实无法专注，反而容易陷入细节。

  通过在 org-clock-in-hook 中添加 set-org-clock-effort-when-nil 函数实现

• 设置一个 my/clock-in-long-focus 函数，用该函数进行 clock in 之后，则当前周期为 52 分钟，这个适合少量需要较长时间专注的任务。
• clock in 之后创建一个计时器，从 0 开始，每 9 分钟更新计时器，如果超过 org-effort 时间则每 9 分钟做一次提醒。
• 在 clock out 的时候初始一个新的 clock-out-idle-timer, 该 timer 是全局变量，clock in 的时候通过 cancel-timer 来取消，提醒自己有多久没有 clock 了。
• 当把任务状态设置为 Done 的时候，也需要 clock out, 通过对 org-after-todo-state-change-hook 添加 org-clock-out-if-done 函数实现。

(use-package org-clock
  :ensure nil
  ;; :hook (org-clock-in-prepare . my/org-mode-ask-effort )
  :custom
  (org-clock-continuously nil)
  (org-clock-in-switch-to-state "NEXT")
  (org-clock-out-remove-zero-time-clocks t)
  (org-clock-display-default-range 'untilnow) ;; show statistic in all range
  (org-clock-persist t)
  (org-log-note-clock-out nil) ;; add log when clockout
  ;; (org-clock-persist-file (expand-file-name (format "%s/emacs/org-clock-save.el" xdg-cache)))
  (org-clock-persist-query-resume nil)
  ;; (org-clock-report-include-clocking-task t)
  (org-show-notification-timeout 10)
  :config
  (defun org-clock-out-if-done ()
    "Clock out when the task is marked DONE"
    (when (and (string= org-state "DONE")
               (equal (marker-buffer org-clock-marker) (current-buffer))
               (< (point) org-clock-marker)
               (> (save-excursion (outline-next-heading) (point))
                  org-clock-marker)
               (not (string= org-last-state org-state)))
      (org-clock-out)))

    (setq my/org-clock-effort 25)
    
    (defun set-org-clock-effort-when-nil ()
      (setq org-clock-effort (format "00:%s" my/org-clock-effort))
      (org-clock-update-mode-line))

  (defun my/clock-in-long-focus ()
    (interactive)
    ;; (setq my/org-clock-effort 
    ;;       (completing-read "Select efforts: " '("0:52")))
    (let ((my/org-clock-effort 52))
      (org-clock-in)))
  
  (add-hook 'org-clock-in-hook #'set-org-clock-effort-when-nil)
  (add-hook 'org-after-todo-state-change-hook 'org-clock-out-if-done)

  (defun clock-in-focus-notify ()
    (let ((current-focus-time
           (/ (float-time
               (time-subtract (current-time) org-clock-start-time))
              60)))
      (when (>= current-focus-time my/org-clock-effort)
        (start-process-shell-command
         ""
         nil
         (my/read-org-block-by-name "~/org/historical/projects.gtd" "timeout")))
      (org-notify (if (org-clock-is-active)
                      (string-trim
                       (substring-no-properties
                        (org-clock-get-clock-string)))
                    ""))))

  (setq my/clock-in-focus-notify-gap (* 60 9))

  (defun clock-in-focus-timer-start ()
    "设置一个计时器，每 my/clock-in-focus-notify-gap 触发一次 clock-in-focus-notify"
    (setq clock-in-focus-timer
          (run-at-time
           my/clock-in-focus-notify-gap
           my/clock-in-focus-notify-gap
           #'clock-in-focus-notify)))

  (defun clock-in-focus-timer-stop ()
    (when (boundp 'clock-in-focus-timer)
      (cancel-timer clock-in-focus-timer)))

  (add-hook 'org-clock-in-hook #'clock-in-focus-timer-start)
  (add-hook 'org-clock-out-hook #'clock-in-focus-timer-stop)

  (defun clock-out-idle-notify ()
    (setq clock-out-idle-time-duration (+ 10 clock-out-idle-time-duration))
    (org-notify (format "%d minutes idle" clock-out-idle-time-duration)))

  (defun clock-out-idle-timer-start ()
    "设置一个计时器，每 600 秒（10分钟）触发一次 clock-out-idle-notify,
     用 clock-out-idle-time-duration 全局变量大致记录 timer 已经运行的时间"

    (setq clock-out-idle-time-duration 0)
    (setq clock-out-idle-timer (run-at-time 600 600 #'clock-out-idle-notify)))

  (defun clock-out-idle-timer-stop ()
    (when (boundp 'clock-out-idle-timer)
      (cancel-timer clock-out-idle-timer)))

  (add-hook 'org-clock-out-hook #'clock-out-idle-timer-start)
  (add-hook 'org-clock-in-hook #'clock-out-idle-timer-stop)
  )

• 对 timer 的手动处理方式：有时候 timer 可能没有正常结束，这时可以通过执行 list-timers 命令打开一个 timers buffer, 然后将光标移动到需要取消的 timer 那一行，执行 timer-list-cancel 命令来取消这个 timer.

本节对常用 agenda 中命令进行封装，比如默认 org-agenda-clock-in/out/done 的时候不会更新状态，那么就在 这些操作之后加入 agenda 刷新

(defun my/org-agenda-clock-in-and-refresh ()
  (interactive)
  (org-agenda-clock-in) (org-agenda-redo) (org-agenda-goto))

(defun my/org-agenda-clock-out-and-refresh ()
  (interactive)
  (org-agenda-clock-out) (org-agenda-redo) (org-agenda-goto))

(defun my/org-agenda-done ()
  (interactive)
  (org-agenda-todo "DONE") (org-agenda-redo) (org-agenda-goto))

(defun org-agenda--jump-to-now ()
  "Search for the keyword 'now' in the current buffer and jump to it."
  (goto-char (point-min))  ; 从 buffer 的开头开始搜索
  (re-search-forward "now" nil t))  ; 搜索 'now' 关键词

(defun org-agenda-clockreport-mode-enhenced ()
  (interactive)
  (if org-agenda-clockreport-mode
      (progn
        (org-agenda-clockreport-mode)
        (org-agenda--jump-to-now)
        (beginning-of-line))
    (progn
      (org-agenda-clockreport-mode)
      (re-search-forward "Time" nil t)
      (next-line 2))))

(general-define-key
 :keymaps 'org-agenda-mode-map
 :states 'motion ;; agenda 下用 motion 代替 normal state
 "i" 'my/org-agenda-clock-in-and-refresh
 "o" 'my/org-agenda-clock-out-and-refresh
 "d" 'my/org-agenda-done
 "a" 'org-agenda-columns
 "R" 'org-agenda-clockreport-mode-enhenced
 )

绑定 S-F10 按键，进入到 gtds tab, 该 tab 会打开 4 个 buffer:

• agenda: 从时间上看到当天做了什么
• projects.gtd: 当前任务总体进展（agenda file）
• entry.org: 常用信息备忘，包括临时创建的待整理的笔记(类似 index.html)
• 日记文件，比如 j2024a.org: 快速记录

这样可以快速记录和查看任务信息。

(defun create-or-switch-to-tab (tab-name)
  "Create or switch to a tab with the given TAB-NAME."
  (let ((tab-exists (tab-bar--tab-index-by-name tab-name)))
    (if tab-exists
        (tab-bar-switch-to-tab tab-name)
      (tab-new)
      (tab-rename tab-name))))
  (setq org-agenda-window-setup 'only-window)

(defun gtd-setup-window-layout ()
  "Sets up a window layout with one window on the left and two windows stacked vertically on the right."
  (interactive)
  (progn
    (delete-other-windows)
    ;; 打开 agenda 跳到 clock 上
    (org-agenda "" " ")
    (split-window-horizontally) ;; 切分左右窗口
    (split-window-vertically)  ;; 在左侧 agenda 切分上下窗口
    (select-window (next-window)) ;; 在左侧下方窗口打开 entry 文件
    (find-file "~/org/historical/entry.org")
    ;; 跳转到右侧窗口打开项目文件, 跳转到最近 clock 的任务
    (select-window (next-window))
    (ignore-errors
      (org-clock-goto))
    (let ((target-file gtd-project-file))
      (unless (equal (buffer-file-name) (expand-file-name target-file))
        (switch-to-buffer (find-file target-file))))
    (split-window-vertically) ;; 右侧窗口继续切分出上下
    (select-window (next-window))
    (switch-to-buffer
     (find-file (get-current-journal-file)))))

(defun gtd-oriented-tab-switch (gtd-tab-name)
  "if current tab is gtd-tab-name, execute other-window, else goto gtd-tab"
  (let ((current-tab (cdr (assq 'name (tab-bar--current-tab)))))
    (if (equal current-tab "gtds")
        (tab-bar-switch-to-recent-tab)
      (progn (create-or-switch-to-tab "gtds")
               (gtd-setup-window-layout)))
    (setq last-switch-action "tab-switch")))
(bind-key (kbd "s-<f10>") (lambda () (interactive) (gtd-oriented-tab-switch "gtds")))

emacs 默认使用 DocView 打开 pdf, pdf-tool 对此有一些增强，比如搜索，outline 跳转等都。

第一次安装 pdftools 时需要调用 pdf-tools-install 自动安装系统依赖，如 libpoppler automake 等

有了以下设置后，常用的操作是：

• 按 f 后弹出 isearch 窗口，输入链接关键词，pdftool 高亮出对应链接，按 enter follow link, 比如可以看一眼注脚或者参考文献，然后按 o 或 C-o 回到刚才的位置。
• 按 O 进入 outline 后，可以通过 M-ret 让 pdf 同步到光标所在的 heading 章节位置, RET 则是光标跳转到 pdf 对应的 heading 位置。
• 按 / 搜索后会进入 pdf-occur buffer, 这和 outline 很类似，只不过每一行不是 heading 而是匹配到关键字的行，因此以上将 M-ret 绑定为 pdf-occur-view-occurrence 后，也可以让 pdf 同步到光标所在搜索结构的位置，和 pff-outline mode 下行为一样。
• org-pdftools 提供了对 pdf 的链接格式，可以直接用一个 hyperlink 跳转到精准的pdf页面

(use-package pdf-tools
  :mode ("\\.pdf\\'" . pdf-tools-install)
  :custom
  (pdf-annot-activate-created-annotations t "automatically annotate highlights")
  :config
  (setq mouse-wheel-follow-mouse t)
  (setq pdf-view-resize-factor 1.10)
  (setq-default pdf-view-display-size 'fit-width)
  (setq image-cache-eviction-delay 30) ; clear image cache after 30 sec, origin 300
  ;; (pdf-tools-install)

  (general-define-key
   :keymaps 'pdf-view-mode-map
   :states '(normal)
   "C-c C-g"  'pdf-sync-forward-search
   "o" 'pdf-history-backward
   "C-o" 'pdf-history-backward
   "C-t" 'pdf-history-backward
   "i" 'pdf-history-forward
   "C-i" 'pdf-history-forward
   "H" '(lambda () (interactive) (image-backward-hscroll 10))
   "L" '(lambda () (interactive) (image-forward-hscroll 10))
   "O" 'pdf-outline
   "C-c o" 'pdf-outline ;; same as outline in org/epub
   "d" 'pdf-view-scroll-up-or-next-page
   "b" 'pdf-view-scroll-down-or-previous-page
   "u" 'pdf-view-scroll-down-or-previous-page
   "gp" 'pdf-view-goto-page
   "C-f" 'pdf-view-next-page
   "C-b" 'pdf-view-previous-page
   "/" 'pdf-occur
   "C-s" 'isearch-forward
   )

  (general-define-key
   :keymaps 'pdf-occur-buffer-mode-map
   "M-RET" 'pdf-occur-view-occurrence
   )
  )

(use-package org-pdftools
  :hook (org-mode . org-pdftools-setup-link))