# emacs-rime

**Repository Path**: andrew_heung/emacs-rime

## Basic Information

- **Project Name**: emacs-rime
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-03-15
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

#+TITLE: Emacs Rime

[[https://melpa.org/#/rime][file:https://melpa.org/packages/rime-badge.svg]] [[https://stable.melpa.org/#/rime][file:https://stable.melpa.org/packages/rime-badge.svg]]

[[file:README_EN.org][Document in English]]

[[file:https://i.imgur.com/jHpk7BT.gif]]

* 安装与使用方法

** 依赖

- Emacs 26.1+ ，且需启用动态支持模块。

- emacs-rime 会自动构建所需的动态模块，这需要 ~make~ 和 ~gcc~ 可用。

** 安装 librime

*** Linux

**** ArchLinux/Manjaro

#+begin_src emacs-lisp
  sudo pacman -S librime
#+end_src

**** Debian/Ubuntu

请注意 ~librime-dev~ 的版本，如果在1.5.3以下，则需要自行编译。

#+begin_src emacs-lisp
  sudo apt install git build-essential cmake libboost-all-dev libgoogle-glog-dev libleveldb-dev libmarisa-dev libopencc-dev libyaml-cpp-dev libgtest-dev
  git clone https://github.com/rime/librime.git ~/.emacs.d/librime
  cd ~/.emacs.d/librime
  make
  sudo make install
#+end_src

*** MacOS
1. 先安装[[https://rime.im/download/][鼠须管]]，里面有输入法方案。
2. 然后直接下载编译好的librime的Release版本。

#+BEGIN_SRC bash
  curl -OJ  https://github.com/rime/librime/releases/download/1.5.3/rime-1.5.3-osx.zip
  unzip rime-1.5.3-osx.zip -d ~/.emacs.d/librime
  rm -rf rime-1.5.3-osx.zip
#+END_SRC

如果MacOS Gatekeeper阻止第三方软件运行，可以暂时关闭它：

#+begin_src bash
  sudo spctl --master-disable
  # later: sudo spctl --master-enable
#+end_src

*** Windows

在 Windows 下构建 librime-emacs 的最简单的方法是使用 [[https://www.msys2.org/][msys2]] 。

#+begin_src bash
  pacman -S pactoys base-devel
  pacboy -S librime:x librime-data:x emacs:x toolchain:x
  ln -s /mingw64/share/opencc/* /mingw64/share/rime-data/opencc # Fix the Simplified Chinese input
#+end_src

在 mingw64 环境中启动 emacs 来获取正确的 =SHELL= 环境变量，用来在 Emacs 内构建 librime-emacs 以及  =MSYSTEM_PREFIX= 环境变量来设置 ~rime-share-data-dir~ 变量。

** 最小配置

Emacs Rime 已发布到 Melpa 。

#+begin_src emacs-lisp
  (use-package rime
    :custom
    (default-input-method "rime"))
#+end_src

#+html: <details>
#+html: <summary>使用 Straight</summary>
#+BEGIN_SRC emacs-lisp
  (use-package rime
    :straight (rime :type git
                    :host github
                    :repo "DogLooksGood/emacs-rime"
                    :files ("*.el" "Makefile" "lib.c"))
    :custom
    (default-input-method "rime"))
#+END_SRC
#+html: </details>

#+html: <details>
#+html: <summary>使用 Quelpa</summary>
#+BEGIN_SRC emacs-lisp
  (use-package rime
    :quelpa (rime :fetcher github
                  :repo "DogLooksGood/emacs-rime"
                  :files ("*.el" "Makefile" "lib.c"))
    :custom
    (default-input-method "rime"))
#+END_SRC
#+html: </details>

*NOTE* 如果你在 MacOS 上或是选择自己编译 librime （没有放在系统路径中）， *必须* 指定 ~rime-librime-root~ 。

在 ~:custom~ 中加入如下内容.

(假设将 librime 解压到了 ~/.emacs.d/librime)

#+BEGIN_SRC emacs-lisp
(rime-librime-root "~/.emacs.d/librime/dist")
#+END_SRC

** 激活 Rime 输入法

使用 ~toggle-input-method~ 来激活，默认快捷键为 ~C-\~

* 设置输入中发送到 Rime 的组合键。

通过变量 ~rime-translate-keybindings~ 可以设置哪些组合键将发送至 Rime 。可以用来配合方案中的设置完成光标移动和选字等功能。
支持 Control (C-), Meta (M-), Shift (S-)的组合键。

#+BEGIN_SRC emacs-lisp
  ;; 默认值
  (setq rime-translate-keybindings
    '("C-f" "C-b" "C-n" "C-p" "C-g" "<left>" "<right>" "<up>" "<down>" "<prior>" "<next>" "<delete>"))
#+END_SRC

* 样式设置
** 候选框展示风格

设置 ~rime-show-candidate~ 。

| 可选值     | 说明                                                   |
|------------+--------------------------------------------------------|
| ~nil~        | 不展示                                                 |
| ~minibuffer~ | 在minibuffer中展示， 推荐使用的方式                    |
| ~message~    | 直接使用 ~message~ 输出，兼容控制 ~minibuffer~ 内容的插件  |
| ~popup~      | 使用 ~popup.el~ 展示跟随的候选                           |
| ~posframe~   | 使用 ~posframe~ 展示跟随的候选，在不可用的时候会用 ~popup~ |

** 候选样式

| Face                    | 说明                               |
|-------------------------+------------------------------------|
| ~rime-default-face~       | 默认的前景色和背景色（仅posframe） |
| ~rime-code-face~          | 编码的颜色                         |
| ~rime-candidate-num-face~ | 候选序号颜色                       |
| ~rime-comment-face~       | 编码提示颜色                       |

** posframe 候选版式
设置 ~rime-posframe-style~ ，可选值有
| 可选值     | 说明       |
|------------+------------|
| ~simple~     | 单行       |
| ~horizontal~ | 水平，默认 |
| ~vertical~   | 垂直       |

** posframe 的其它属性
设置 ~rime-posframe-properties~, 其中颜色的设置使用 ~rime-default-face~.
#+begin_src emacs-lisp
  (setq rime-posframe-properties
   (list :font "sarasa ui sc"
         :internal-border-width 10))
#+end_src
支持的内容参照 [[https://github.com/tumashu/posframe/blob/master/posframe.el#L212][posframe]] 。

** 设置软光标的样式

默认使用 ~|~ 字符做为软光标，可以通过如下方式修改。

#+BEGIN_SRC emacs-lisp
  (setq rime-cursor "˰")
#+END_SRC

颜色可通过 ~rime-cursor-face~ 设置。

** 设置嵌入文本的样式

可通过 ~rime-preedit-face~ 设置。

** 编码的展示形式

设置 ~rime-show-preedit~, 可选值有
| 可选值 | 说明         |
|--------+--------------|
| ~t~      | 展示在菜单中 |
| ~inline~ | 替换上屏预览 |
| ~nil~    | 不展示       |

注意：使用 ~inline~ 或 ~nil~ 将不再展示软光标。

* 临时英文模式
如果使用模式编辑，或是在一些特定的场景下需要自动使用英文，可以设
置~rime-disable-predicates~ ， ~rime-disable-predicates~ 的值是一个断言列表，
当其中有任何一个断言的值 **不是** nil 时，会自动使用英文。

一个在 ~evil-normal-state~ 中、在英文字母后面以及代码中自动使用英文的例子。

#+BEGIN_SRC emacs-lisp
  (setq rime-disable-predicates
        '(rime-predicate-evil-mode-p
          rime-predicate-after-alphabet-char-p
          rime-predicate-prog-in-code-p))
#+END_SRC

#+html: <details>
#+html: <summary>目前可用的断言函数</summary>

- ~rime-predicate-after-alphabet-char-p~

  在英文字符串之后（必须为以字母开头的英文字符串）

- ~rime-predicate-after-ascii-char-p~

  任意英文字符后

- ~rime-predicate-prog-in-code-p~

  在 ~prog-mode~ 和 ~conf-mode~ 中除了注释和引号内字符串之外的区域

- ~rime-predicate-evil-mode-p~

  在 ~evil-mode~ 的非编辑状态下

- ~rime-predicate-ace-window-p~

  激活 ~ace-window-mode~

- ~rime-predicate-hydra-p~

  如果激活了一个 ~hydra~ keymap

- ~rime-predicate-current-input-punctuation-p~

  当要输入的是符号时

- ~rime-predicate-punctuation-after-space-cc-p~

  当要在中文字符且有空格之后输入符号时

- ~rime-predicate-punctuation-after-ascii-p~

  当要在任意英文字符之后输入符号时

- ~rime-predicate-punctuation-line-begin-p~

  在行首要输入符号时

- ~rime-predicate-space-after-ascii-p~

  在任意英文字符且有空格之后

- ~rime-predicate-space-after-cc-p~

  在中文字符且有空格之后

- ~rime-predicate-current-uppercase-letter-p~

  将要输入的为大写字母时

- ~rime-predicate-tex-math-or-command-p~

  在 (La)TeX 数学环境中或者输入 (La)TeX 命令时

#+html: </details>

** 可提示临时英文状态的提示符

使用函数 ~(rime-lighter)~ 返回一个用于展示的 ~ㄓ~ 符号。
可以通过 ~rime-indicator-face~ 和 ~rime-indicator-dim-face~ 设置样式。

如下设置可替换输入法的符号，使其用颜色提示当前的临时英文状态。

#+begin_src emacs-lisp
  ;;; 具体参考 mode-line-mule-info 默认值，其中可能有其它有用信息
  (setq mode-line-mule-info '((:eval (rime-lighter))))
#+end_src

** 基于 Rime inline ascii 模式的临时英文

设置 ~rime-inline-predicates~ ，结构与 ~rime-disable-predicates~ 相同，具有较低优先级。

这个功能主要用来实现输入带空格的临时英文的场景。

由于当前实现限制，如果 Rime 配置中没有使用默认的 ~Shift_L~ 切换 inline ascii 模式，需要在 emacs-rime 中指定。
两边配置相同才能正常激活。

#+begin_src emacs-lisp
  ;;; support shift-l, shift-r, control-l, control-r
  (setq rime-inline-ascii-trigger 'shift-l)
#+end_src

在有编码的状态下使用 ~rime-inline-ascii~ 命令可以切换状态。

#+begin_src emacs-lisp
  (define-key rime-active-mode-map (kbd "M-j") 'rime-inline-ascii)
#+end_src

** 临时英文中阻止标点直接上屏
#+begin_src emacs-lisp
  (setq rime-inline-ascii-holder ?x)      ; Any single character that not trigger auto commit
#+end_src

** 断言成立时的强制中文模式
使用 ~rime-force-enable~ 来临时强制使用强制中文模式（即无视 ~rime-disable-predicates~ 中的规则），
在 *一次输入行为* 或 *取消输入* 之后会自动关闭强制中文模式。

你可能需要给这个命令绑定一个按键来使用。

#+begin_src emacs-lisp
  (define-key rime-mode-map (kbd "M-j") 'rime-force-enable)
#+end_src

* 在 minibuffer 使用后自动关闭输入法

默认行为为自动关闭，设置 ~rime-deactivate-when-exit-minibuffer~ 为 nil 取消该行为。

* 指定 Rime 共享目录和用户目录

~rime-share-data-dir~ 是 Rime 安装后放置配置的目录，例如 Linux 上默认为 /usr/share/rime-data. 通常使用默认值即可。
如果使用其它的位置，可以配置该值。

~rime-user-data-dir~ 为 emacs-rime 布署的位置，默认为 ~/.emacs.d/rime ，如果需要其它位置，可以配置该值。

* 打开 Rime 的配置文件

使用 ~rime-open-configuration~ 打开自定义配置文件。

使用 ~rime-open-schema~ 打开一个方案的自定义配置文件。

* FAQ

#+html: <details>
#+html: <summary>如何获得支持动态模块的 Emacs</summary>
**** Linux
Linux 各主要发行版自带 emacs 默认已启用动态模块支持。

**** MacOS
***** emacs-plus 默认启用 ~--with-modules~ 选项，使用 homebrew 安装命令如下：
#+BEGIN_SRC shell
brew tap d12frosted/emacs-plus
brew install emacs-plus
#+END_SRC

***** emacs-mac 安装时需要启用 ~--with-modules~ 选项，使用 homebrew 安装命令如下 :
#+BEGIN_SRC shell
brew tap railwaycat/emacsmacport
brew install emacs-mac --with-modules
#+END_SRC

**** 手工编译

使用 ~--with-modules~ 选项.
#+html: </details>

#+html: <details>
#+html: <summary>编译时无法找到 rime_api.h</summary>

必须设置 ~rime-librime-root~ 参照安装方法中的说明。

#+html: </details>

#+html: <details>
#+html: <summary>编译时无法找到 emacs-module.h</summary>

如果自己编译 Emacs 且没有安装到标准目录（/usr/, /usr/local/），
*必须* 指定 ~rime-emacs-module-header-root~ 。

在 ~:custom~ 中加入如下内容.

(假设将 Emacs 安装到了 ~/emacs)

#+BEGIN_SRC emacs-lisp
(rime-emacs-module-header-root "~/emacs/include")
#+END_SRC

#+html: </details>

#+html: <details>
#+html: <summary>如何重新部署？</summary>

~emacs-rime~ 的配置文件更新之后，与RIME一样，都需要重新部署才可生效。

以添加 ~地球拼音（terra_pinyin）~ 为例。

找到 ~emacs-rime~ 配置所在路径，或使用 ~M-x rime-open-configuration~ 打开文件 ~default.custome.yaml~ ，在 ~patch:schema_list~ 中添加 ~- schema: terra_pinyin~ ，需要 ~M-x rime-deploy~ 重新部署才可启用地球拼音方案，重新部署成功后按 ~C-`~ 选择输入方案。

示例如下：
#+BEGIN_SRC yaml
patch:
  schema_list:
    - schema: luna_pinyin
    - schema: pinyin_simp
    - schema: terra_pinyin
  menu/page_size: 7 # 每页显示7个候选字词。
  switcher:
    hotkeys:
      - Control+grave # 激活RIME选单的快捷键，某些版本的RIME支持<F4>为快捷键，容易与其他软件冲突。
#+END_SRC

#+html: </details>

#+html: <details>
#+html: <summary>如何同步词库？</summary>

~M-x rime-sync~ 可对RIME输入方案和词库进行同步与备份，每次同步双向进行，词库生成的备份文件为 ~sync/ins_id/schema.userdb.txt~ ，其本身是文件夹 ~schema.userdb/~ 中词库与词频使用记录的纯文本形式，方便用户跨平台、多设备使用。

所谓双向同步，即当前设备中的词频或用户自造词（ ~schema.userdb/~ 中）与备份文件（ ~sync/ins_id/schema.userdb.txt~ 中）所记录的词库会被RIME合并，其 *并集* 将会继续记录在 ~schema.userdb/~ 中，同时生成一份新的备份文件，仍名为 ~sync/ins_id/schema.userdb.txt~ ，并（在不询问用户的情况下）将旧的覆盖。

上述路径中 ~sync~ 文件夹与配置文件 ~default.custom.yaml~ 在同一目录， ~ins_id~ 对应的是 ~installation.yaml~ 文件中 ~installation_id~ 的值，默认值为随机生成，可自定义为其他字符串。

以添加 ~地球拼音（terra_pinyin）~ 后同步为例。启用该方案后，在RIME数据目录下会产生名为 ~terra_pinyin.userdb~ 的文件夹，其中为使用频率与自造词的记录，不可随意修改。同步前先修改 ~installation.yaml~ 中内容为自定义的 ~installation_id: "hesperus"~ ，之后 ~M-x rime-sync~ ，将会在 ~sync/hesperus/~ 生成文件 ~terra_pinyin.userdb.txt~ （词库）与 ~terra_pinyin.schema.yaml~ （输入方案）。

若在其他设备或系统中有个人积累的词库，想继续使用。则先在旧系统中进行同步，将生成的 ~terra_pinyin.userdb.txt~ 复制到当前系统的 ~sync/hesperus/~ 下，再进行同步或部署，此时旧系统中备份的词库将会被合并到当前系统的 ~terra_pinyin.userdb/~ ，新的并集也将会被同时导出，并覆盖 ~terra_pinyin.userdb.txt~ 。

#+html: </details>

#+html: <details>
#+html: <summary>重新部署后原有个人词库丢失</summary>

（以地球拼音方案在fcitx-rime与emacs-rime中使用为例。）

*不建议 ~emacs-rime~ 与 ~fcitx-rime~ 共用数据文件夹* 。若设置
#+BEGIN_SRC emacs-lisp
(setq rime-user-data-dir "~/.config/fcitx/rime/")
#+END_SRC
，则在 ~emacs-rime~ 初次部署后，将会生成新的 ~terra_pinyin.userdb/~ 文件夹，原有 ~fcitx-rime~ 使用记录将会被移动到 ~terra_pinyin.userdb.old/~ ，此时新的 ~terra_pinyin.userdb.txt~ 中词频为空。

***** 如何找回
设置 ~emacs-rime~ 用户数据目录到其他文件夹，删除 ~terra_pinyin.userdb/~ 并将 ~terra_pinyin.userdb.old/~ 重命名为前者，再次同步或部署， ~terra_pinyin.userdb.txt~ 亦将恢复。

#+html: </details>

#+html: <details>
#+html: <summary>词库同步失败</summary>

（以地球拼音方案使用为例。）

*建议将不同设备或系统中的 ~installation_id~ 设为同一值* 。若其不同，则可能同步失败，即从旧系统同步并复制的 ~terra_pinyin.userdb.txt~ 中的词频记录不会被纳入到当前的 ~terra_pinyin.userdb/~ 。
此时该文件中词频不为空，但其中 ~user_id~ 等不同，修改此值后再次同步仍可能不生效。

#+html: </details>

#+html: <details>
#+html: <summary>在 isearch 中的使用</summary>

目前在 isearch 中不能正常工作，但是可以使用 [[https://github.com/zk-phi/phi-search][phi-search]].

#+html: </details>

#+html: <details>
#+html: <summary>候选框最后一项不显示？</summary>

极少数用户下会偶尔出现最后一个候选词不显示的情况，可以确定跟 `posframe` 有关，但
目前尚未找到原因，有一个暂时的解决办法，就是给候选词列表最后附加一个全角空格，这
样即使出现“吃字”的情况也只是把末尾的全角空格“吃”掉，不会影响候选词的显示。代码如
下：
#+BEGIN_SRC emacs-lisp
  (defun +rime--posframe-display-content-a (args)
    "给 `rime--posframe-display-content' 传入的字符串加一个全角空
格，以解决 `posframe' 偶尔吃字的问题。"
    (cl-destructuring-bind (content) args
      (let ((newresult (if (string-blank-p content)
                           content
                         (concat content "　"))))
        (list newresult))))

  (if (fboundp 'rime--posframe-display-content)
      (advice-add 'rime--posframe-display-content
                  :filter-args
                  #'+rime--posframe-display-content-a)
    (error "Function `rime--posframe-display-content' is not available."))
#+END_SRC

#+html: </details>

#+html: <details>
#+html: <summary>无需 librime 纯 Emacs 实现的输入法？</summary>

你可能需要 [[https://github.com/tumashu/pyim][pyim]].

#+html: </details>

* 感谢所有的 Contributor

- [[https://github.com/Z572][Z572]]
- [[https://github.com/cnsunyour][cnsunyour]]
- [[https://github.com/shuxiao9058][shuxiao9058]]
- [[https://github.com/lkzz][lkzz]]
- [[https://github.com/wsw0108][wsw0108]]
- [[https://github.com/HesperusArcher][HesperusArcher]]
- [[https://github.com/longminwang][longminwang]]
- [[https://github.com/chuxubank][chuxubank]]
- [[https://github.com/jixiuf][jixiuf]]
- [[https://github.com/cireu][cireu]]