doc: update doc, format markdown

CHANGELOG.md

@@ -1,10 +1,35 @@
+# v0.4.0
+
+## Fix
+
+- 改进文件 didChange 的判断，减少 `unwrap()` 报错
+- 避免代码中硬编码用户目录
+- 移除部分不必要的类型转换
+- 修复第一次补全无法触发方案选单的问题
+
+## Feat
+
+- 放弃 `Rime*` 这种老 API，转用新版本 API
+- 可以通过 Github Actions 构建的 Docker 镜像来使用 rime-ls 了
+- 增加新的配置项 `show_order_in_label` 用于配置补全项不显示数字 (#28)
+
+## Doc
+
+- NixOS 下的安装使用指南 (Thanks to definfo #32 #33)
+- fix typo (Thanks to evpeople #34)
+
+## Chore
+
+- 加入 `Cargo.lock` 便于可重复构建 (Thanks to definfo #32)
+- 改进 `Dockerfile`，基于 Alpine 减小镜像大小 (23 MB)
+
 # v0.3.0
 
 ## Fix
 
 - 解决某些编辑器无法连续输入的问题：
-    - 为 Zed 和 Helix 增加配置项 `long_filter_text`
-    - 为 Zed 增加配置项 `show_filter_text_in_label`
+  - 为 Zed 和 Helix 增加配置项 `long_filter_text`
+  - 为 Zed 增加配置项 `show_filter_text_in_label`
 - 在查找补全串开头的时候应该从右到左搜索 (Thanks to TwIStOy in #21 )
 - 解决使用 dashmap 的一个死锁 (#16)
 
@@ -20,61 +45,72 @@
 
 - 增加 Release 的编译脚本, 通过 `cargo-zigbuild` 和 `cargo-xwin` 交叉编译其他平台
 
-
 # v0.2.4
 
 ## Fix
+
 - 修复了不定期发生的补全无法触发的问题 #14
 - 修复了 termux 环境下的构建失败 #8
 
 ## Feat
+
 - 允许通过新配置项 `paging_characters` 自定义触发补全的字符，主要用途是翻页 #13
 
 ## Chore
+
 - 有了基础的 GitHub CI #9 (Thanks to eagleoflqj)
 
 # v0.2.3
 
 ## Breaking Changes
+
 - 不再默认选中第一个候选项，若要选中，通过新配置项 `preselect_first` 进行配置
 
 ## Feat
+
 - 提升了在五笔和音形输入方案下的体验 #7 (Thanks to TwIStOy)
-    - 增加了新配置项 `max_tokens`，强制在删除到一定长度时重建一次候选词
-    - 增加了新配置项 `always_incomplete`，每次输入重建候选词，防止过滤代替候选词重建
+  - 增加了新配置项 `max_tokens`，强制在删除到一定长度时重建一次候选词
+  - 增加了新配置项 `always_incomplete`，每次输入重建候选词，防止过滤代替候选词重建
 
 ## Doc
+
 - 增加了 macOS 系统下的编译步骤 #6 (Thanks to rainzm)
 - 更新了 neovim 配置样例，在 nvim-cmp 下的体验更接近系统输入法
-    - 空格汉字上屏之外，新增回车原始串上屏 #7 (Thanks to TwIStOy)
-    - 使上述行为只对 rime-ls 提供的补全项生效，不影响其他补全
+  - 空格汉字上屏之外，新增回车原始串上屏 #7 (Thanks to TwIStOy)
+  - 使上述行为只对 rime-ls 提供的补全项生效，不影响其他补全
 
 # v0.2.2
 
 ## Fix
+
 - 修复了因内存提前释放导致的日志文件名出错
 - 修复了一些特殊场景下对已提交文字的判断错误
 
 ## Feat
+
 - 升级 `tower-lsp` 到 `0.19.0` 版本以支持 LSP 3.17.0
 - 支持 LSP 3.17.0 的 `label_details` 特性，用于显示每一个候选项的 comment
 - 默认选中第一个候选项
 
 # v0.2.1
 
 ## Breaking Changes
+
 - 启动时不再自动更新用户词频，改为完全手动操作
 
 ## Fix
+
 - 修复了因状态判断出错导致的删除输入后同一位置无法继续输入的问题
 - 修复了进入「方案选单」后必须选择才能退出的问题
 
 # v0.2.0
 
 ## Breaking Changes
+
 - 配置项 `max_candidates` 不再生效，改为遵从 Rime 配置的每页候选项个数
 
 ## Feat
+
 - 与 Rime 的 API 保持同步，不再是只获取候选项
 - 支持将通过数字选择的候选项提交给 Rime，从而影响用户词频
 - 支持长句子的分多次选择
@@ -84,35 +120,41 @@
 # v0.1.3
 
 ## Fix
+
 - 更好的错误处理
 - 修复了几处从 rust 传指针给 C 时的典型内存泄漏
 
 ## Feat
+
 - 配置项的路径现在支持展开波浪线 `~` 为家目录
 - 支持通过 TCP 远程使用 (明文传输，不安全，需要配合加密的 TCP 信道)
 - 可能有理论上的性能提升 (未验证)
 
 # v0.1.2
 
 ## Breaking Changes
+
 - `execute_command` 所支持的命令的名称都增加了 `rime-ls.` 的前缀
 
 ## Fix
+
 - 修复了因更新位置在边界处导致的 LSP server 不能同步更新文档内容的问题
 
 ## Feat
+
 - 现在可以通过命令手动触发用户目录同步
 - 执行 `rime-ls.toggle-rime` 命令后会返回执行后的当前状态
 
 # v0.1.1
 
 ## Fix
+
 - 全局模式下，补全时会删掉拼音前未提交的标点符号
 
 ## Feat
+
 - 触发模式下，光标前有非英文字符时可以自动触发补全继续输入
 
 # v0.1.0
 
 第一个基本可用版本
-

Dockerfile

@@ -2,8 +2,8 @@ FROM alpine:edge AS builder
 
 # 1. build rime plugins from source
 ## 1.1 install dependencies
-RUN apk add --no-cache boost-dev capnproto-dev chrpath cmake \ 
-glog-dev leveldb-dev libmarisa-dev opencc-dev \ 
+RUN apk add --no-cache boost-dev capnproto-dev chrpath cmake \
+glog-dev leveldb-dev libmarisa-dev opencc-dev \
 samurai yaml-cpp-dev git bash clang gtest-dev
 
 ## 1.1 clone git repo

README.md

@@ -14,8 +14,8 @@
 - 支持按数字选择补全项
 - 支持候选词翻页
 - 多种触发方式
-    - 默认开启, 随时补全, 用快捷键控制关闭 (写大量汉字)
-    - 平时关闭, 检测到配置的特殊字符或光标前有非英文字符时触发补全 (写少量汉字)
+  - 默认开启, 随时补全, 用快捷键控制关闭 (写大量汉字)
+  - 平时关闭, 检测到配置的特殊字符或光标前有非英文字符时触发补全 (写少量汉字)
 - 可以按配置其他 rime 输入法的方式去配置 (只有能影响候选项的配置是有用的)
 - 可以同步系统中已有 rime 输入法的词频
 - 可以通过 TCP 远程使用 (无任何加密，谨慎使用) (since v0.1.3)
@@ -32,11 +32,11 @@ https://user-images.githubusercontent.com/14821247/213079440-f0ab2ddd-5e44-4e41-
 1. 下载 Release 或自己从源码编译
 2. 将编译好的二进制文件放在喜欢的目录下
 3. 配置 LSP 客戶端, 例如:
-    - [Neovim + nvim-cmp](doc/nvim.md)
-    - [Vim + coc.nvim](doc/vim.md)
-    - [Vscode](doc/vscode.md)
-    - [Helix](doc/helix.md)
-    - [Zed](doc/zed.md)
+   - [Neovim + nvim-cmp](doc/nvim.md)
+   - [Vim + coc.nvim](doc/vim.md)
+   - [Vscode](doc/vscode.md)
+   - [Helix](doc/helix.md)
+   - [Zed](doc/zed.md)
 4. 像配置其他 Rime 输入法一样在 rime-ls 的用户目录进行配置
 5. 輸入拼音, 就可以看到补全提示
 6. 可以通过修改 rime-ls 的配置项控制补全行为
@@ -49,17 +49,43 @@ https://user-images.githubusercontent.com/14821247/213079440-f0ab2ddd-5e44-4e41-
 
 > [!TIP]
 > 容器中不包含 Rime 内置输入方案的数据。使用时可以根据需要映射到 `/usr/share/rime-data` 目录，
-> 或者使用 [rime-ice](https://github.com/iDvel/rime-ice/releases/tag/nightly) 
+> 或者使用 [rime-ice](https://github.com/iDvel/rime-ice/releases/tag/nightly)
 > 等不依赖 Rime 内置输入方案的方案。
 
+## Config
+
+所有可配置项及其默认值（以 json 为例）:
+
+```jsonc
+{
+  "initializationOptions": {
+    "enabled": true, // 是否启用
+    "shared_data_dir": "/usr/share/rime-data", // 指定 rime 共享文件夹
+    "user_data_dir": "~/.local/share/rime-ls", // 指定 rime 用户文件夹，最好别与其他 rime 前端共用
+    "log_dir": "~/.local/share/rime-ls", // 指定 rime 日志文件夹
+    "max_candidates": 9,  // [v0.2.0 后不再有用] 与 rime 的候选数量配置最好保持一致
+    "trigger_characters": [],  // 为空表示全局开启，否则列表内字符后面的内容才会触发补全
+    "schema_trigger_character": "&" // [since v0.2.0] 当输入此字符串时请求补全会触发 “方案选单”
+    "paging_characters": [",", ".", "-", "="], // [since v0.2.4] 输入这些符号会强制触发一次补全，可用于翻页 见 issue #13
+    "max_tokens": 0 // [since v0.2.0] 大于 0 表示会在删除到这个字符个数的时候，重建所有候选词，而不使用删除字符操作，见 pr #7
+    "always_incomplete": false // [since v0.2.0] true 强制补全永远刷新整个列表，而不是使用过滤，见 pr #7
+    "preselect_first": false // [since v0.2.3] 是否默认选择第一个候选项
+    "long_filter_text": false // [since v0.3.0] 使用更长的 filter_text，某些编辑器如 helix/zed 连续补全需要设置 true
+    "show_filter_text_in_label": false // [since v0.3.0] 在候选项的 label 中显示 filter_text，某些编辑器如 zed 需要设置 true
+    "show_order_in_label": true // [since v0.4.0] 在候选项的 label 中显示数字
+  }
+}
+
+```
+
 ## Build
 
 ### Ubuntu
 
 1. 配置 Rust 环境, 安装额外依赖 `clang` 和 `librime-dev`
 2. 编译
-    - `librime >= 1.6` => `cargo build --release`
-    - `librime < 1.6` => `cargo build --release --features=no_log_dir`
+   - `librime >= 1.6` => `cargo build --release`
+   - `librime < 1.6` => `cargo build --release --features=no_log_dir`
 
 ### ArchLinux
 
@@ -113,33 +139,34 @@ https://user-images.githubusercontent.com/14821247/213079440-f0ab2ddd-5e44-4e41-
    ```powershell
    $env:LIBRIME_LIB_DIR="C:\解压出来的目录\dist\lib" # 找库文件
    $env:LIBRIME_INCLUDE_DIR="C:\解压出来的目录\dist\include" # 找头文件
-   $env:LIB="C:\解压出来的目录\dist\lib" # 链接时找 lib 文件 
+   $env:LIB="C:\解压出来的目录\dist\lib" # 链接时找 lib 文件
    ```
 4. 编译 `cargo build --release`
 
 ### macOS
 
 1. 安装 [鼠须管输入法](https://github.com/rime/squirrel)
 2. 安装 [librime](https://github.com/rime/librime)
-从此项目中的 [Release](https://github.com/rime/librime/releases/)
-下载最新的 MacOS 相关的压缩包，解压缩后将 include 文件夹以及 lib 文件夹下的内容分别复制到 `/usr/local/include` 和 `/usr/local/lib`;
+   从此项目中的 [Release](https://github.com/rime/librime/releases/)
+   下载最新的 MacOS 相关的压缩包，解压缩后将 include 文件夹以及 lib 文件夹下的内容分别复制到 `/usr/local/include` 和 `/usr/local/lib`;
 3. 设置环境变量以便编译时找到 librime 的相关文件（参考[相关issue](https://github.com/wlh320/rime-ls/issues/24)）
 
-    ```bash
-    # 用于编译 
-    export LIBRIME_LIB_DIR=/usr/local/lib
-    export LIBRIME_INCLUDE_DIR=/usr/local/include
-    # 用于运行
-    export DYLD_LIBRARY_PATH=/usr/local/lib  # 最好放在~/.zshrc中，记得修改~/.zshrc 后，source ~/.zshrc 
-    ```
-    lib 库文件后面调用的时候应该还需要到 MacOS 的“安全性与隐私”中进行授权，所以建议调用解压后 bin 文件下的可执行文件来提前触发授权。
+   ```bash
+   # 用于编译
+   export LIBRIME_LIB_DIR=/usr/local/lib
+   export LIBRIME_INCLUDE_DIR=/usr/local/include
+   # 用于运行
+   export DYLD_LIBRARY_PATH=/usr/local/lib  # 最好放在~/.zshrc中，记得修改~/.zshrc 后，source ~/.zshrc
+   ```
+
+   lib 库文件后面调用的时候应该还需要到 MacOS 的“安全性与隐私”中进行授权，所以建议调用解压后 bin 文件下的可执行文件来提前触发授权。
+
 4. 编译，参考 [Ubuntu](#Ubuntu)
 5. 配置，`shared_data_dir` 应该设置为 `/Library/Input Methods/Squirrel.app/Contents/SharedSupport`
 
 ## 个人词库同步
 
-> **Warning**
-> **不推荐**与系统中的已有 rime 输入法共用一个用户目录, 免得出什么问题
+> **Warning** > **不推荐**与系统中的已有 rime 输入法共用一个用户目录, 免得出什么问题
 >
 > 使用前备份自己的数据, 避免因作者对 rime API 理解不到位可能造成的数据损失
 
@@ -153,17 +180,18 @@ https://user-images.githubusercontent.com/14821247/213079440-f0ab2ddd-5e44-4e41-
 ## FAQ
 
 1. 为什么默认补全繁体中文？怎么修改候选个数？
-   
+
    答：这部分由 Rime 负责，参考 [Rime 的帮助文档](https://rime.im/docs/)。推荐对 Rime 有初步了解后再使用本软件。
-   
-3. 某个编辑器不能用/不好用
-   
+
+2. 某个编辑器不能用/不好用
+
    答：由于 LSP 客户端在补全上的实现都很不一致（影响用户体验的差异主要有：怎样寻找单词边界、怎样过滤候选项），
    不能保证每个编辑器都有很好的使用体验。
 
 ## Contributions
 
 欢迎为本项目贡献代码，你可以：
+
 - 发现并修改代码里的 bug
 - 为某个编辑器实现相关插件
 - 提供某个编辑器的更好用的用户配置
@@ -172,13 +200,13 @@ https://user-images.githubusercontent.com/14821247/213079440-f0ab2ddd-5e44-4e41-
 ## TODO
 
 - [x] 實現更多 librime 的功能
-    - [x] 按数字键选择候选项
-    - [x] 与 rime API 同步翻页
-    - [x] 与 rime API 同步提交
-    - [x] 输入标点符号
-    - [x] 输入方案选择
+  - [x] 按数字键选择候选项
+  - [x] 与 rime API 同步翻页
+  - [x] 与 rime API 同步提交
+  - [x] 输入标点符号
+  - [x] 输入方案选择
 - [x] 实现更友好的触发条件
-    - [x] ~~计划实现光标前面有汉字就开启, 但发现不同编辑器行为不一致, 搁置~~ 多加了一次正则匹配解决了, 不知道性能如何
+  - [x] ~~计划实现光标前面有汉字就开启, 但发现不同编辑器行为不一致, 搁置~~ 多加了一次正则匹配解决了, 不知道性能如何
 - [ ] 读 LSP 文档, 继续提升补全的使用体验
 - [x] 參數可配置 (用户目录, 触发条件, 候选数量)
 - [x] ~~實現一個更好的 librime 的 rust wrapper 庫~~ 目前功能比较固定，没必要了
@@ -190,11 +218,9 @@ https://user-images.githubusercontent.com/14821247/213079440-f0ab2ddd-5e44-4e41-
 
 ## Known Issues
 
-- [x] ~~補全的觸發條件很奇怪，現在我是手動觸發補全寫的這些字~~ 解决, 要设置 is_incomplete 来连续补全
-- [x] ~~還沒完成開始這個項目的最初目的, 即直接復用 rime 配置~~ 维护一份独立的用户目录，与外部输入法互相同步词频
-- [x] ~~沒有完全實現 rime 功能, 只是读取了候选项, 沒有把选到的字真正提交~~ v0.2.0 基本解决
-- [ ] 第一次嘗試從 Rust 調用 C 接口，寫的非常不專業且 unsafe
-- [x] ~~同时开启多个共用同一个用户目录的程序时，会因为用户数据库的锁导致不工作~~ 是预期行为，避免这么干
+- [ ] #31 补全时吞符号，暂时可以通过在输入方案设置所有符号直接上屏进行规避
+- [ ] #20 用数字选词以后还需要一次确认，这是 LSP 协议本身带来的限制，需要编辑器插件配合提升体验
+- [ ] 调用 sync_user_data 后偶尔内存占用大，这是 rime 已知问题 https://github.com/rime/librime/issues/440
 
 ## Credits
 
@@ -204,4 +230,3 @@ https://user-images.githubusercontent.com/14821247/213079440-f0ab2ddd-5e44-4e41-
 - [cmp-rime](https://github.com/Ninlives/cmp-rime)
 - [librime-sys](https://github.com/lotem/librime-sys)
 - [tower-lsp-boilerplate](https://github.com/IWANABETHATGUY/tower-lsp-boilerplate)
-

doc/helix.md

@@ -56,6 +56,5 @@ rime-ls 的配置项参考其他编辑器，都是一样的，改成 toml 的格
 ## 存在问题
 
 - [x] 补全触发条件有问题(**已解决**)
-    - [x] 在汉字后面输入不会自动触发补全，需通过配置的触发字符手动触发(since v0.3.0 配置 `config.long_filter_text = true`)
-    - [x] 最小补全长度为 2，手动设置最小补全长度为 1 会导致当前输入长度为 2 时补全消失(helix 最新版已无问题)
-
+  - [x] 在汉字后面输入不会自动触发补全，需通过配置的触发字符手动触发(since v0.3.0 配置 `config.long_filter_text = true`)
+  - [x] 最小补全长度为 2，手动设置最小补全长度为 1 会导致当前输入长度为 2 时补全消失(helix 最新版已无问题)

doc/vim.md

@@ -1,4 +1,3 @@
-
 # vim 配置示例
 
 目前没有现成插件，建议根据实际使用情况自行配置。
@@ -21,16 +20,16 @@
         "shared_data_dir": "/usr/share/rime-data", // rime 公共目录
         "user_data_dir": "~/.local/share/rime-ls", // 指定用户目录，最好新建一个
         "log_dir": "~/.local/share/rime-ls", // 日志目录
-        "max_candidates": 9,  // [v0.2.0 后不再有用] 与 rime 的候选数量配置最好保持一致
+        "max_candidates": 9, // [v0.2.0 后不再有用] 与 rime 的候选数量配置最好保持一致
         "paging_characters": [",", "."], // [since v0.2.4] 这些符号会强制触发一次补全，可用于翻页 见 issue #13
-        "trigger_characters": [],  // 为空表示全局开启
-        "schema_trigger_character": "&" // [since v0.2.0] 当输入此字符串时请求补全会触发 “方案选单”
-      }
+        "trigger_characters": [], // 为空表示全局开启
+        "schema_trigger_character": "&", // [since v0.2.0] 当输入此字符串时请求补全会触发 “方案选单”
+      },
     },
 
     // 其他 LSP
     // ......
-  }
+  },
 }
 ```
 
@@ -42,4 +41,3 @@
 # TODO
 
 - [x] 发送 execute command 命令, 手动 toggle
-