MarginaliaのREADME


- marginalia.elのバージョン1.8のREADME.org日本語訳です

- 元の文書: https://github.com/minad/marginalia/blob/main/README.org

- ライセンス: パッケージのライセンスと同じ、すなわちGPLv3.0ライセンスです

- - -

# TOC
=================

* [構成](#構成)
* [注釈付けによって表示される情報](#注釈付けによって表示される情報)
* [カスタマイズされた注釈付けやクラス分けの追加](#カスタマイズされた注釈付けやクラス分けの追加)
* [annotator、ビルトインのannotator、軽量annotatorの無効化](#annotatorビルトインのannotator軽量annotatorの無効化)
* [ミニバッファーでのアイコン表示](#ミニバッファーでのアイコン表示)
* [貢献](#貢献)

<!-- Created by https://github.com/ekalinin/github-markdown-toc -->

-  - -

<a href="https://www.gnu.org/software/emacs/"><img alt="GNU Emacs" src="https://github.com/minad/corfu/blob/screenshots/emacs.svg?raw=true"/></a>

<a href="https://elpa.gnu.org/packages/marginalia.html"><img alt="GNU ELPA" src="https://elpa.gnu.org/packages/marginalia.svg"/></a>

<a href="https://elpa.gnu.org/devel/marginalia.html"><img alt="GNU-devel ELPA" src="https://elpa.gnu.org/devel/marginalia.svg"/></a>

<a href="https://melpa.org/#/marginalia"><img alt="MELPA" src="https://melpa.org/packages/marginalia-badge.svg"/></a>

<a href="https://stable.melpa.org/#/marginalia"><img alt="MELPA Stable" src="https://stable.melpa.org/packages/marginalia-badge.svg"/></a>

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

<!-- This package provides `marginalia-mode` which adds marginalia to the minibuffer -->
<!-- completions. [Marginalia](https://en.wikipedia.org/wiki/Marginalia) are marks or annotations placed at the margin of the -->
<!-- page of a book or in this case helpful colorful annotations placed at the margin -->
<!-- of the minibuffer for your completion candidates. Marginalia can only add -->
<!-- annotations to the completion candidates. It cannot modify the appearance of the -->
<!-- candidates themselves, which are shown unaltered as supplied by the original -->
<!-- command. -->

このパッケージはミニバッファーの補完にたいして、Marginaliaを追加する`marginalia-mode`を提供する。[Marginalia](https://en.wikipedia.org/wiki/Marginalia)とは本のページの余白・欄外(margin: マージン)にある印し(mark: マーク)や書き込み(annotation: 注釈)、あるいはこのパッケージだと補完候補にたいしてミニバッファーのマージンに配置されるカラフルで役に立つ注釈のことだ。Marginaliaが注釈を追加できるのは補完候補にたいしてだけである。補完候補自体の見栄えは変更できないので、元のコマンドによって提供されたままの見栄えをそのまま表示する。

<!-- The annotations are added based on the completion category. For example -->
<!-- `find-file` reports the `file` category and `M-x` reports the `command` category. You -->
<!-- can cycle between more or less detailed annotators or even disable the annotator -->
<!-- with command `marginalia-cycle`. -->

注釈はその補完のカテゴリーに基づいて追加される。たとえば`find-file`では`file`カテゴリー、`M-x`では`command`カテゴリーが報告される。詳細な注釈付けから注釈付けの無効化まで、注釈付けの強弱はコマンド`marginalia-cycle`で巡回できる。

<img src="https://github.com/minad/marginalia/blob/screenshots/marginalia-mode.png?raw=true">

# 構成

<!-- It is recommended to use Marginalia together with either the [Vertico](https://github.com/minad/vertico), [Mct](https://github.com/protesilaos/mct), [Icomplete](https://www.gnu.org/software/emacs/manual/html_node/emacs/Icomplete.html) or the default completion UI. Furthermore Marginalia can be combined with [Embark](https://github.com/oantolin/embark) for action support and [Consult](https://github.com/minad/consult), which provides many useful commands. -->

Marginaliaは[Vertico](https://github.com/minad/vertico)、[Mct](https://github.com/protesilaos/mct)、[Icomplete](https://www.gnu.org/software/emacs/manual/html_node/emacs/Icomplete.html)、あるいはデフォルトの補完ユーザーインタフェースと一緒に使用することをお勧めする。更にアクションをサポートするために[Embark](https://github.com/oantolin/embark)、有用なコマンドを多数提供する[Consult](https://github.com/minad/consult)と組み合わせることもできるだろう。

```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))
```

# 注釈付けによって表示される情報

<!-- In general, to learn more about what different annotations mean, a good starting point is to look at `marginalia-annotator-registry`, and follow up to the annotation function of the category you are interested in. -->

それぞれ異なる注釈の意味について理解を深めるためには、まず`marginalia-annotator-registry`の調査を出発点として、興味があるカテゴリーの注釈関数の知識を補う方法が一般的だろう。たとえばElispシンボルの注釈には変数は`v`、関数は`f`、コマンドなら`c`といったシンボルクラスが含まれている。この異なるクラス分けが何を意味しているかについての詳細については、`marginalia--symbol-class`のドキュメント文字列を参照して欲しい。

# カスタマイズされた注釈付けやクラス分けの追加

<!-- **IMPORTANT NOTICE FOR PACKAGE AUTHORS**: The intention of the Marginalia package is to give the user means to overwrite completion categories and to add custom annotators for existing commands in their user configuration. **Marginalia is a user facing package and is not intended to be used as a library**. Therefore Marginalia does not expose library functions as part of its public API. If you add your own completion commands to your package we recommend to specify an `annotation-function` or an `affixation-function`, avoiding the Marginalia dependency this way. The `annotation-function` and `affixation-function` are documented in the [Elisp manual](https://www.gnu.org/software/emacs/manual/html_node/elisp/Completion.html). If you use `consult--read`, you can specify an `:annotate` keyword argument. -->

**パッケージ作者向けの重要な注意事項**: Marginaliaはユーザーが補完カテゴリーをオーバーライドして、既存コマンド向けのカスタマイズされた注釈付けをユーザーの構成に追加できる手段の提供を意図したパッケージである。**Marginaliaが向き合うのはユーザーであって、ライブラリーとしての使用は考慮していない。**Marginaliaは公開APIの一部としてライブラリー関数を公開していないのはこの理由による。あなたのパッケージに独自の補完関数を追加する場合には、Marginaliaの依存関係を回避するために`annotation-function`や`affixation-function`を指定する方法をお勧めする。`annotation-function`と`affixation-function`については[Emacs Lispリファレンスマニュアル](https://www.gnu.org/software/emacs/manual/html_node/elisp/Completion.html)で文書化されている。`consult--read`を使っているならキーワード引数`:annotate`を指定すればよいだろう。

<!-- There is an exception to our recommendation: If you want to implement annotations for an existing package `hypothetic.el`, which does not have annotations and where annotations cannot be added, then the creation of a `marginalia-hypothetic.el` package is a good idea, since Marginalia provides the facilities to enhance existing commands from the outside. -->

この推奨事項には例外がある: 注釈がなく注釈が追加できないような既存のパッケージ`hypothetic.el`(訳注: hypotheticは仮説、仮想という意味)にたいして注釈を実装したい場合に、`marginalia-hypothetic.el`というパッケージを作成するというアイデアは悪くない。なぜならMarginaliaは外部の既存コマンドを強化する機能を提供しているからだ。

<!-- Commands that support minibuffer completion use a completion table of all the available candidates. Candidates are associated with a **category** such as `command`, `file`, `face`, or `variable` depending on what the candidates are. Based on the category of the candidates, Marginalia selects an **annotator** to generate annotations for display for each candidate. -->

ミニバッファー補完をサポートしているコマンドは、利用可能なすべての候補の補完テーブルを使用している。その補完候補が何であるかに応じて`command`、`file`、`face`、`variable`といった**カテゴリー**が候補に関連付けられているのだ。候補それぞれにたいして表示する注釈を生成するために、Marginaliaは候補のカテゴリーに基づいた**注釈付け(annotator)**を選択している。

<!-- Unfortunately, not all commands (including Emacs' builtin ones) specify the category of their candidates. To compensate for this shortcoming, Marginalia hooks into the Emacs completion framework and runs the **classifiers** listed in the variable `marginalia-classifiers`, which use the command's prompt or other properties of the candidates to specify the completion category. -->

残念だが(Emacsのビルトインコマンドも含めて)すべてのコマンドが候補のカテゴリーを指定する訳ではない。MarginaliaはEmacsの補完フレームワークにフックして、変数`marginalia-classifiers`にリストされた、((補完カテゴリーを指定するためにそのコマンドのコマンドプロンプトや候補のその他プロパティを使用する))**クラス分け(classifiers)**を実行してこの欠点を克服している。

<!-- For example, the `marginalia-classify-by-prompt` classifier checks the minibuffer prompt against regexps listed in the `marginalia-prompt-categories` alist to determine a category. The following is already included but would be a way to assign the category `face` to all candidates from commands with prompts that include the word "face". -->

たとえば`marginalia-classify-by-prompt`というクラス分けでは`marginalia-prompt-categories`というalist(訳注: association list、連想配列のこと; 今風にはハッシュ型とか辞書型のことです)にリストされたregexp(訳注: Emacsでは正規表現として評価される文字列値を指して使用されることが多いです)にたいしてミニバッファーのプロンプトをチェックしている。以下は"face"という単語を含むコマンドからのすべての候補に、(既に含まれているが)カテゴリーとして`face`を割り当てる方法を示している。

```lisp
    (add-to-list 'marginalia-prompt-categories '("\\<face\\>" . face))
```

<!-- The `marginalia-classify-by-command-name` classifier uses the alist `marginalia-command-categories` to specify the completion category based on the command name. This is particularly useful if the prompt classifier yields a false positive. -->

`marginalia-classify-by-command-name`というクラス分けでは、コマンド名に基づいた補完カテゴリーを指定するために`marginalia-command-categories`というalistが用いられている。プロンプトによるクラス分けでは誤検知が生じるような場合に特に有用だろう。

<!-- Completion categories are also important for [Embark](https://github.com/oantolin/embark), which associates actions based on the completion category and benefits from Marginalia's classifiers. -->

補完カテゴリーに応じてアクションを割り当てる[Embark](https://github.com/oantolin/embark)にとっても補完カテゴリーは重要であり、Marginaliaのクラス分けにより恩恵を受けることができるだろう。

<!-- Once the category of the candidates is known, Marginalia looks in the `marginalia-annotator-registry` to find the associated annotator to use. An annotator is a function that takes a completion candidate string as an argument and returns an annotation string to be displayed after the candidate in the minibuffer. More than one annotator can be assigned to each each category, displaying more, less or different information. Use the `marginalia-cycle` command to cycle between the annotations of different annotators defined for the current category. -->

候補のカテゴリーが一度判明してしまえば、Marginaliaが`marginalia-annotator-registry`を調べて、使用すべき割り当てられたannotatorを見つける筈だ。annotatorとは補完候補となる文字列を引数として、ミニバッファーの候補の後に表示される注釈文字列をリターンする関数のことだ。カテゴリーそれぞれにたいしてより多く、あるいはより少ない、もしくは異なる情報を表示できるようにするために、1つ以上のannotatorを割り当てることができる。`marginalia-cycle`は、カレントカテゴリーにたいして定義されている異なるannotator間を巡回するために使用するコマンドだ。

<!-- Here's an example of a basic face annotator: -->

以下はフェイス用の基本的なannotatorの例:

```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))))
```

<!-- After defining a new annotator, associate it with a category in the annotator registry as follows: -->

新たなannotatorを定義したら、以下のようにannotatorレジストリのカテゴリーに関連付けよう:

```lisp
    (add-to-list 'marginalia-annotator-registry
                 '(face my-face-annotator marginalia-annotate-face builtin none))
```

<!-- This makes the `my-face-annotator` the first of four annotators for the face category. The others are the annotator provided by Marginalia (`marginalia-annotate-face`), the `builtin` annotator as defined by Emacs and the `none` annotator, which disables the annotations. With this setting, after invoking `M-x describe-face RET` you can cycle between all of these annotators using `marginalia-cycle`. -->

これによりfaceカテゴリーの4つのannotatorの1つ目が`my-face-annotator`になる。それ以外のannotatorはMarginaliaが提供する`marginalia-annotate-face`、Emacsが定義する`builtin`、そして注釈を無効にする`none`だ。この設定を使えば`M-x describe-face RET`を呼び出した後に、`marginalia-cycle`を使ってこれらすべてのannotatorを巡回できるようになるだろう。

# annotator、ビルトインのannotator、軽量annotatorの無効化

<!-- Marginalia activates rich annotators by default. Depending on your preference you may want to use the builtin annotators or even no annotators by default and only activate the annotators on demand by invoking `marginalia-cycle`. -->

Marginaliaはデフォルトではリッチなannotatorをアクティブにする。
Marginalia activates rich s by default. 
お好み次第ではビルトインのannotatorの方がよいかもしれないし、デフォルトではannotatorなし、`marginalia-cycle`呼び出しでオンデマンドでannotatorをアクティブにしたい場合さえあるかもしれない。

<!-- In order to disable an annotator permanently, the `marginalia-annotator-registry` can be modified. For example if you prefer to never see file annotations, you can delete all file annotators from the registry. -->

`marginalia-annotator-registry`を変更すれば、annotatorを永続的に無効化できる。たとえばファイル用の注釈を見たいと思うことが絶対ないのであれば、レジストリからファイル用のannotatorを削除すればよい。

```lisp
    (setq marginalia-annotator-registry
          (assq-delete-all 'file marginalia-annotator-registry))
```

<!-- To use the builtin annotators by default, you can run the following code. Replace `builtin` by `none` to disable annotators by default. -->

ビルトインのannotatorをデフォルトで使用したければ、以下のコードを実行するとよいだろう。`builtin`を`none`に置き換えれば、デフォルトでannotatorを無効にできる。

```lisp
    (mapc (lambda (x)
            (setcdr x (cons 'builtin (remq 'builtin (cdr x)))))
          marginalia-annotator-registry)
```

<!-- As an alternative to `marginalia-cycle`, if a completion category supports two annotators, you can toggle between them using the following command. -->

補完カテゴリーがサポートするannotatorが2つであれば、`marginalia-cycle`のかわりに以下のコマンドでannotatorを切り替えることができる。

```lisp
    (defun marginalia-toggle ()
      (interactive)
      (mapc
       (lambda (x)
         (setcdr x (append (reverse (remq 'none
                                          (remq 'builtin (cdr x))))
                           '(builtin none))))
       marginalia-annotator-registry))
```

<!-- After cycling the annotators you may want to automatically save the configuration. This can be achieved using an advice which calls -->

annotatorを巡回した後におの構成を自動保存したいと思うかもしれない。これは呼び出しにadviceを使用して実現できるだろう。

```lisp
`customize-save-variable`.

    (advice-add #'marginalia-cycle :after
                (lambda ()
                  (let ((inhibit-message t))
                    (customize-save-variable 'marginalia-annotator-registry
                                             marginalia-annotator-registry))))
```

# ミニバッファーでのアイコン表示

<!-- Marginalia focuses on text annotations. The [nerd-icons-completion](https://github.com/rainstormstudio/nerd-icons-completion) package is compatible with Marginalia and uses the special NerdFonts to add icons in front of minibuffer completion candidates. There exist related packages to enhance Dired, Ibuffer, Corfu and other modes with icons consistently. -->

marginaliaが焦点を当てる対象はテキスト注釈だ。[nerd-icons-completion](https://github.com/rainstormstudio/nerd-icons-completion)はMarginaliaと互換性のあるパッケージであり、特別なNerdFontsを使用してミニバッファーの補完候補の前にアイコンを追加している。Dired、Ibuffer、Corfu、その他のモードにたいして一貫したアイコン強化を行う関連パッケージも存在する。

# 貢献

<!-- Since this package is part of [GNU ELPA](https://elpa.gnu.org/packages/marginalia.html) contributions require a copyright assignment to the FSF.  -->

このパッケージは[GNU ELPA](https://elpa.gnu.org/packages/marginalia.html)の一部なので、コードの貢献にはFSFへの著作権譲渡が必要だ。

- - -

# おまけ

- [org-remark](https://qiita.com/ayatakesi/items/69d43671b28bb27a9c52)をインストールします

- "init.el"か"\*scratch*"で以下を評価します

<details><summary>評価する式</summary><div>

```lisp
    (org-remark-global-tracking-mode +1)
    
    (with-eval-after-load 'eww
      (org-remark-eww-mode +1))

    ;; 省略可
    (define-key global-map (kbd "C-c n m") #'org-remark-mark)
    (define-key global-map (kbd "C-c n l") #'org-remark-mark-line) ; new in v1.3
    
    ;; The rest of keybidings are done only on loading `org-remark'
    (with-eval-after-load 'org-remark
      (define-key org-remark-mode-map (kbd "C-c n o") #'org-remark-open)
      (define-key org-remark-mode-map (kbd "C-c n ]") #'org-remark-view-next)
      (define-key org-remark-mode-map (kbd "C-c n [") #'org-remark-view-prev)
      (define-key org-remark-mode-map (kbd "C-c n r") #'org-remark-remove)
      (define-key org-remark-mode-map (kbd "C-c n d") #'org-remark-delete))

```

</div></details>

- "init.el"のあるディレクトリ、"~/.emacs.d/"とかに"marginalia.org"というファイル作って以下を入力します

<details><summary>marginalia.orgの内容</summary>
<div>

```text

* 203e9011d5eaba902683
:PROPERTIES:
:org-remark-file: qiita.com/ayatakesi/items/203e9011d5eaba902683
:END:

** marginalia-annotator-registry
:PROPERTIES:
:org-remark-id: 6cb0e187
:org-remark-label: nil
:org-remark-beg: 2185
:org-remark-end: 2214
:org-remark-link: [[https://qiita.com/ayatakesi/items/203e9011d5eaba902683]]
:org-remark-original-text: marginalia-annotator-registry
:END:
注釈付け関数(annotator function)のレジストリ

注釈関数に補完カテゴリーを割り当てる
注釈関数はそれぞれ文字列をリターンしなければならない
その文字列は補完候補に付け加えられる

** marginalia--symbol-class
:PROPERTIES:
:org-remark-id: 45b64893
:org-remark-label: nil
:org-remark-beg: 2345
:org-remark-end: 2369
:org-remark-link: [[https://qiita.com/ayatakesi/items/203e9011d5eaba902683]]
:org-remark-original-text: marginalia--symbol-class
:END:
シンボルSにたいするシンボルクラス文字をリターンする

これはhelp--symbol-classの拡張関数であり、より細かく詳細なシンボル情報をリターンする

Function:
f function
c command
C interactive-only command
m macro
F special-form
M module function
P primitive
g cl-generic
p pure
s side-effect-free
@ autoloaded
! advised
- obsolete
& alias

Variable:
u custom (U modified compared to global value)
v variable
l local (L modified compared to default value)
- obsolete
& alias

Other:
G custom group
a face
t cl-type

** marginalia-classifiers
:PROPERTIES:
:org-remark-id: ccb72fac
:org-remark-label: nil
:org-remark-beg: 3336
:org-remark-end: 3358
:org-remark-link: [[https://qiita.com/ayatakesi/items/203e9011d5eaba902683]]
:org-remark-original-text: marginalia-classifiers
:END:
カレント補完カテゴリーを判定する関数のリスト

関数はそれぞれ引数をとらずカテゴリを示すシンボル、判定不可能ならnilをリターンすること

** marginalia-classify-by-prompt
:PROPERTIES:
:org-remark-id: 0c2df715
:org-remark-label: nil
:org-remark-beg: 3464
:org-remark-end: 3493
:org-remark-link: [[https://qiita.com/ayatakesi/items/203e9011d5eaba902683]]
:org-remark-original-text: marginalia-classify-by-prompt
:END:
ミニバッファープロンプトにたいしてregexpをマッチすることでカテゴリを判定

marginalia-prompt-categoriesというalistを走査実行してプロンプトにマッチするregexpを調べる

** marginalia-prompt-categories
:PROPERTIES:
:org-remark-id: 1b9a061f
:org-remark-label: nil
:org-remark-beg: 3503
:org-remark-end: 3531
:org-remark-link: [[https://qiita.com/ayatakesi/items/203e9011d5eaba902683]]
:org-remark-original-text: marginalia-prompt-categories
:END:
ミニバッファープロンプトにマッチするregexpによりカテゴリを関連付ける

プロンプトのマッチは大文字小文字を区別しない

** marginalia-classify-by-command-name
:PROPERTIES:
:org-remark-id: f08ca62d
:org-remark-label: nil
:org-remark-beg: 3823
:org-remark-end: 3858
:org-remark-link: [[https://qiita.com/ayatakesi/items/203e9011d5eaba902683]]
:org-remark-original-text: marginalia-classify-by-command-name
:END:
カレントコマンドにたいしてカテゴリを調べる

** marginalia-command-categories
:PROPERTIES:
:org-remark-id: 314579ec
:org-remark-label: nil
:org-remark-beg: 3895
:org-remark-end: 3924
:org-remark-link: [[https://qiita.com/ayatakesi/items/203e9011d5eaba902683]]
:org-remark-original-text: marginalia-command-categories
:END:
コマンドと補完カテゴリを関連付ける

照合のキーとしてthis-commandの値を用いる

** marginalia-annotate-face
:PROPERTIES:
:org-remark-id: 7014f188
:org-remark-label: nil
:org-remark-beg: 4911
:org-remark-end: 4935
:org-remark-link: [[https://qiita.com/ayatakesi/items/203e9011d5eaba902683]]
:org-remark-original-text: marginalia-annotate-face
:END:
ドキュメント文字列とフェイス例にフェイスCANDで注釈をつける
```

</div></details>

- ewwで[このページ](https://qiita.com/ayatakesi/items/203e9011d5eaba902683)を開きます

- もしかしたらハイライトと注釈が表示されるかもしれません