marginalia

#+title: marginalia.el - 小缓冲区中的旁注 #+author: Omar Antolín Camarena, Daniel Mendler #+language: zh #+export_file_name: marginalia.texi #+texinfo_dir_category: Emacs 杂项功能 #+texinfo_dir_title: Marginalia: (marginalia). #+texinfo_dir_desc: 小缓冲区中的旁注

#+html: <a href="https://www.gnu.org/software/emacs/"><img alt="GNU Emacs" src="https://yellow-cdn.veclightyear.com/ab5030c0/afb44aee-9f59-4732-b73f-d6e0b89f0d8c.svg?raw=true"/></a> #+html: <a href="https://elpa.gnu.org/packages/marginalia.html"><img alt="GNU ELPA" src="https://yellow-cdn.veclightyear.com/ab5030c0/60bd92ce-6328-44c4-8251-1d678279fa82.svg"/></a> #+html: <a href="https://elpa.gnu.org/devel/marginalia.html"><img alt="GNU-devel ELPA" src="https://yellow-cdn.veclightyear.com/ab5030c0/2362d0b0-78a1-4069-b4e0-a9065690a164.svg"/></a> #+html: <a href="https://melpa.org/#/marginalia"><img alt="MELPA" src="https://yellow-cdn.veclightyear.com/ab5030c0/6d06c030-6b25-48bb-845c-aa8c5bea5bcc.svg"/></a> #+html: <a href="https://stable.melpa.org/#/marginalia"><img alt="MELPA Stable" src="https://yellow-cdn.veclightyear.com/ab5030c0/190a5432-3c15-4c81-878a-44c1b6cd841d.svg"/></a>

#+html: <img src="https://upload.wikimedia.org/wikipedia/commons/4/4f/Marginalia_%285095211566%29.jpg" align="right" width="30%">

这个包提供了 =marginalia-mode=，它为小缓冲区补全添加了旁注。[[https://en.wikipedia.org/wiki/Marginalia][旁注]]是放置在书页边缘的标记或注释，在这里则是为补全候选项添加的有用的彩色注释。Marginalia 只能为补全候选项添加注释，它不能修改候选项本身的外观，候选项会按原命令提供的样子完整显示。

注释是根据补全类别添加的。例如，=find-file= 报告 =file= 类别，而 =M-x= 报告 =command= 类别。你可以使用 =marginalia-cycle= 命令在更详细或更简洁的注释器之间切换，甚至可以禁用注释器。

#+html: <img src="https://yellow-cdn.veclightyear.com/ab5030c0/09a1a4a7-b8f1-4293-b618-9db7a0a950b2.png?raw=true">

#+toc: headlines 8

配置

建议将 Marginalia 与 [[https://github.com/minad/vertico][Vertico]]、[[https://github.com/protesilaos/mct][Mct]]、[[https://www.gnu.org/software/emacs/manual/html_node/emacs/Icomplete.html][Icomplete]] 或默认补全界面一起使用。此外，Marginalia 可以与 [[https://github.com/oantolin/embark][Embark]] 结合使用以支持操作，还可以与提供许多有用命令的 [[https://github.com/minad/consult][Consult]] 结合使用。

#+begin_src emacs-lisp ;; 使用 Marginalia 包启用丰富的注释 (use-package marginalia ;; 在小缓冲区中本地绑定 marginalia-cycle'。要使绑定在 *Completions* 缓冲区中可用， ;; 请将其添加到 completion-list-mode-map'。 :bind (:map minibuffer-local-map ("M-A" . marginalia-cycle))

;; :init 部分始终会执行。 :init

;; Marginalia 必须在 use-package 的 :init 部分中激活，以便立即启用该模式。 ;; 请注意，这会强制加载包。 (marginalia-mode)) #+end_src

注释器显示的信息

一般来说，要了解不同注释的含义，一个好的起点是查看 ~~marginalia-annotator-registry~~，然后跟进到你感兴趣的类别的注释函数。

例如，Elisp 符号的注释包括它们的符号类别 - =v= 表示变量，=f= 表示函数，=c= 表示命令等。有关不同分类含义的更多信息，请参阅 ~~marginalia--symbol-class~~ 的文档字符串。

添加自定义注释器或分类器

包作者请注意：Marginalia 包的目的是为用户提供覆盖补全类别和为现有命令添加自定义注释器的方法。Marginalia 是面向用户的包，不intended作为库使用。因此，Marginalia 不会将库函数作为其公共 API 的一部分暴露出来。如果你要为你的包添加自己的补全命令，我们建议指定一个 =annotation-function= 或 =affixation-function=，这样可以避免依赖 Marginalia。=annotation-function= 和 =affixation-function= 在 [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Completion.html][Elisp 手册]]中有所文档。如果你使用 =consult--read=，你可以指定一个 =:annotate= 关键字参数。

对我们的建议有一个例外：如果你想为一个现有的包 =hypothetic.el= 实现注释，而该包没有注释且无法添加注释，那么创建一个 =marginalia-hypothetic.el= 包是一个好主意，因为 Marginalia 提供了从外部增强现有命令的功能。

支持小缓冲区补全的命令使用包含所有可用候选项的补全表。候选项与一个类别相关联，如 =command=、=file=、=face= 或 =variable=，具体取决于候选项的内容。根据候选项的类别，Marginalia 选择一个注释器为每个候选项生成要显示的注释。遗憾的是,并非所有命令(包括Emacs内置命令)都指定了其候选项的类别。为了弥补这一不足,Marginalia钩入Emacs补全框架,运行变量=marginalia-classifiers=中列出的分类器,这些分类器使用命令的提示或候选项的其他属性来指定补全类别。

例如,=marginalia-classify-by-prompt=分类器会根据=marginalia-prompt-categories=关联列表中列出的正则表达式检查小缓冲区提示,以确定类别。以下内容已包含在内,但也可以作为一种方法,将类别=face=分配给所有包含"face"一词的命令提示中的候选项。

#+begin_src emacs-lisp (add-to-list 'marginalia-prompt-categories '("\<face\>" . face)) #+end_src

=marginalia-classify-by-command-name=分类器使用=marginalia-command-categories=关联列表根据命令名称指定补全类别。这在提示分类器产生误报时特别有用。

补全类别对[[https://github.com/oantolin/embark][Embark]]也很重要,它根据补全类别关联操作,并从Marginalia的分类器中受益。

一旦候选项的类别确定,Marginalia会在=marginalia-annotator-registry=中查找相关的注释器。注释器是一个函数,它接受一个补全候选项字符串作为参数,并返回一个注释字符串,在小缓冲区中显示在候选项之后。每个类别可以分配多个注释器,显示更多、更少或不同的信息。使用=marginalia-cycle=命令在当前类别定义的不同注释器的注释之间切换。

以下是一个基本的face注释器示例:

#+begin_src emacs-lisp (defun my-face-annotator (cand) (when-let (sym (intern-soft cand)) (concat (propertize " " 'display '(space :align-to center)) (propertize "The quick brown fox jumps over the lazy dog" 'face sym)))) #+end_src

定义新的注释器后,可以按如下方式将其与注释器注册表中的类别关联:

#+begin_src emacs-lisp (add-to-list 'marginalia-annotator-registry '(face my-face-annotator marginalia-annotate-face builtin none)) #+end_src

这使=my-face-annotator=成为face类别的四个注释器中的第一个。其他注释器是Marginalia提供的注释器(=marginalia-annotate-face=)、Emacs定义的=builtin=注释器和禁用注释的=none=注释器。使用此设置,在调用=M-x describe-face RET=后,您可以使用=marginalia-cycle=在所有这些注释器之间切换。

禁用注释器、内置或轻量级注释器

Marginalia默认激活丰富的注释器。根据您的偏好,您可能希望默认使用内置注释器或甚至不使用注释器,只在需要时通过调用~~marginalia-cycle~~来激活注释器。

要永久禁用注释器,可以修改~~marginalia-annotator-registry~~。例如,如果您更喜欢永远不看到文件注释,可以从注册表中删除所有文件注释器。

#+begin_src emacs-lisp (setq marginalia-annotator-registry (assq-delete-all 'file marginalia-annotator-registry)) #+end_src

要默认使用内置注释器,可以运行以下代码。将=builtin=替换为=none=以默认禁用注释器。

#+begin_src emacs-lisp (mapc (lambda (x) (setcdr x (cons 'builtin (remq 'builtin (cdr x))))) marginalia-annotator-registry) #+end_src

作为~~marginalia-cycle~~的替代方案,如果补全类别支持两个注释器,您可以使用以下命令在它们之间切换。

#+begin_src emacs-lisp (defun marginalia-toggle () (interactive) (mapc (lambda (x) (setcdr x (append (reverse (remq 'none (remq 'builtin (cdr x)))) '(builtin none)))) marginalia-annotator-registry)) #+end_src

循环切换注释器后,您可能希望自动保存配置。这可以通过调用~~customize-save-variable~~的建议来实现。

#+begin_src emacs-lisp (advice-add #'marginalia-cycle :after (lambda () (let ((inhibit-message t)) (customize-save-variable 'marginalia-annotator-registry marginalia-annotator-registry)))) #+end_src