-
marginalia.elのバージョン1.8のREADME.org日本語訳です
-
元の文書: https://github.com/minad/marginalia/blob/main/README.org
-
ライセンス: パッケージのライセンスと同じ、すなわちGPLv3.0ライセンスです
TOC
=================
- 構成
- 注釈付けによって表示される情報
- カスタマイズされた注釈付けやクラス分けの追加
- annotator、ビルトインのannotator、軽量annotatorの無効化
- ミニバッファーでのアイコン表示
- 貢献
このパッケージはミニバッファーの補完にたいして、Marginaliaを追加するmarginalia-modeを提供する。Marginaliaとは本のページの余白・欄外(margin: マージン)にある印し(mark: マーク)や書き込み(annotation: 注釈)、あるいはこのパッケージだと補完候補にたいしてミニバッファーのマージンに配置されるカラフルで役に立つ注釈のことだ。Marginaliaが注釈を追加できるのは補完候補にたいしてだけである。補完候補自体の見栄えは変更できないので、元のコマンドによって提供されたままの見栄えをそのまま表示する。
注釈はその補完のカテゴリーに基づいて追加される。たとえばfind-fileではfileカテゴリー、M-xではcommandカテゴリーが報告される。詳細な注釈付けから注釈付けの無効化まで、注釈付けの強弱はコマンドmarginalia-cycleで巡回できる。
構成
MarginaliaはVertico、Mct、Icomplete、あるいはデフォルトの補完ユーザーインタフェースと一緒に使用することをお勧めする。更にアクションをサポートするためにEmbark、有用なコマンドを多数提供するConsultと組み合わせることもできるだろう。
;; 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))
注釈付けによって表示される情報
それぞれ異なる注釈の意味について理解を深めるためには、まずmarginalia-annotator-registryの調査を出発点として、興味があるカテゴリーの注釈関数の知識を補う方法が一般的だろう。たとえばElispシンボルの注釈には変数はv、関数はf、コマンドならcといったシンボルクラスが含まれている。この異なるクラス分けが何を意味しているかについての詳細については、marginalia--symbol-classのドキュメント文字列を参照して欲しい。
カスタマイズされた注釈付けやクラス分けの追加
パッケージ作者向けの重要な注意事項: Marginaliaはユーザーが補完カテゴリーをオーバーライドして、既存コマンド向けのカスタマイズされた注釈付けをユーザーの構成に追加できる手段の提供を意図したパッケージである。**Marginaliaが向き合うのはユーザーであって、ライブラリーとしての使用は考慮していない。**Marginaliaは公開APIの一部としてライブラリー関数を公開していないのはこの理由による。あなたのパッケージに独自の補完関数を追加する場合には、Marginaliaの依存関係を回避するためにannotation-functionやaffixation-functionを指定する方法をお勧めする。annotation-functionとaffixation-functionについてはEmacs Lispリファレンスマニュアルで文書化されている。consult--readを使っているならキーワード引数:annotateを指定すればよいだろう。
この推奨事項には例外がある: 注釈がなく注釈が追加できないような既存のパッケージhypothetic.el(訳注: hypotheticは仮説、仮想という意味)にたいして注釈を実装したい場合に、marginalia-hypothetic.elというパッケージを作成するというアイデアは悪くない。なぜならMarginaliaは外部の既存コマンドを強化する機能を提供しているからだ。
ミニバッファー補完をサポートしているコマンドは、利用可能なすべての候補の補完テーブルを使用している。その補完候補が何であるかに応じてcommand、file、face、variableといったカテゴリーが候補に関連付けられているのだ。候補それぞれにたいして表示する注釈を生成するために、Marginaliaは候補のカテゴリーに基づいた**注釈付け(annotator)**を選択している。
残念だが(Emacsのビルトインコマンドも含めて)すべてのコマンドが候補のカテゴリーを指定する訳ではない。MarginaliaはEmacsの補完フレームワークにフックして、変数marginalia-classifiersにリストされた、((補完カテゴリーを指定するためにそのコマンドのコマンドプロンプトや候補のその他プロパティを使用する))**クラス分け(classifiers)**を実行してこの欠点を克服している。
たとえばmarginalia-classify-by-promptというクラス分けではmarginalia-prompt-categoriesというalist(訳注: association list、連想配列のこと; 今風にはハッシュ型とか辞書型のことです)にリストされたregexp(訳注: Emacsでは正規表現として評価される文字列値を指して使用されることが多いです)にたいしてミニバッファーのプロンプトをチェックしている。以下は"face"という単語を含むコマンドからのすべての候補に、(既に含まれているが)カテゴリーとしてfaceを割り当てる方法を示している。
(add-to-list 'marginalia-prompt-categories '("\\<face\\>" . face))
marginalia-classify-by-command-nameというクラス分けでは、コマンド名に基づいた補完カテゴリーを指定するためにmarginalia-command-categoriesというalistが用いられている。プロンプトによるクラス分けでは誤検知が生じるような場合に特に有用だろう。
補完カテゴリーに応じてアクションを割り当てるEmbarkにとっても補完カテゴリーは重要であり、Marginaliaのクラス分けにより恩恵を受けることができるだろう。
候補のカテゴリーが一度判明してしまえば、Marginaliaがmarginalia-annotator-registryを調べて、使用すべき割り当てられたannotatorを見つける筈だ。annotatorとは補完候補となる文字列を引数として、ミニバッファーの候補の後に表示される注釈文字列をリターンする関数のことだ。カテゴリーそれぞれにたいしてより多く、あるいはより少ない、もしくは異なる情報を表示できるようにするために、1つ以上のannotatorを割り当てることができる。marginalia-cycleは、カレントカテゴリーにたいして定義されている異なるannotator間を巡回するために使用するコマンドだ。
以下はフェイス用の基本的なannotatorの例:
(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))))
新たなannotatorを定義したら、以下のようにannotatorレジストリのカテゴリーに関連付けよう:
(add-to-list 'marginalia-annotator-registry
'(face my-face-annotator marginalia-annotate-face builtin none))
これにより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はデフォルトではリッチなannotatorをアクティブにする。
Marginalia activates rich s by default.
お好み次第ではビルトインのannotatorの方がよいかもしれないし、デフォルトではannotatorなし、marginalia-cycle呼び出しでオンデマンドでannotatorをアクティブにしたい場合さえあるかもしれない。
marginalia-annotator-registryを変更すれば、annotatorを永続的に無効化できる。たとえばファイル用の注釈を見たいと思うことが絶対ないのであれば、レジストリからファイル用のannotatorを削除すればよい。
(setq marginalia-annotator-registry
(assq-delete-all 'file marginalia-annotator-registry))
ビルトインのannotatorをデフォルトで使用したければ、以下のコードを実行するとよいだろう。builtinをnoneに置き換えれば、デフォルトでannotatorを無効にできる。
(mapc (lambda (x)
(setcdr x (cons 'builtin (remq 'builtin (cdr x)))))
marginalia-annotator-registry)
補完カテゴリーがサポートするannotatorが2つであれば、marginalia-cycleのかわりに以下のコマンドでannotatorを切り替えることができる。
(defun marginalia-toggle ()
(interactive)
(mapc
(lambda (x)
(setcdr x (append (reverse (remq 'none
(remq 'builtin (cdr x))))
'(builtin none))))
marginalia-annotator-registry))
annotatorを巡回した後におの構成を自動保存したいと思うかもしれない。これは呼び出しにadviceを使用して実現できるだろう。
`customize-save-variable`.
(advice-add #'marginalia-cycle :after
(lambda ()
(let ((inhibit-message t))
(customize-save-variable 'marginalia-annotator-registry
marginalia-annotator-registry))))
ミニバッファーでのアイコン表示
marginaliaが焦点を当てる対象はテキスト注釈だ。nerd-icons-completionはMarginaliaと互換性のあるパッケージであり、特別なNerdFontsを使用してミニバッファーの補完候補の前にアイコンを追加している。Dired、Ibuffer、Corfu、その他のモードにたいして一貫したアイコン強化を行う関連パッケージも存在する。
貢献
このパッケージはGNU ELPAの一部なので、コードの貢献にはFSFへの著作権譲渡が必要だ。
おまけ
-
org-remarkをインストールします
-
"init.el"か"*scratch*"で以下を評価します
評価する式
(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))
- "init.el"のあるディレクトリ、"~/.emacs.d/"とかに"marginalia.org"というファイル作って以下を入力します
marginalia.orgの内容
* 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で注釈をつける
-
ewwでこのページを開きます
-
もしかしたらハイライトと注釈が表示されるかもしれません