EmbarkのREADME.org


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

- 元の文書: https://github.com/oantolin/embark/blob/master/README.org

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

- - -

Table of Contents
=================

* [概説](#概説)
   * [ターゲットへのアクション](#ターゲットへのアクション)
   * [ターゲットへのデフォルトアクション](#ターゲットへのデフォルトアクション)
   * [アクション可能なターゲット集合にたいする処理](#アクション可能なターゲット集合にたいする処理)
      * [即興の候補セット作成のためのターゲット選択](#即興の候補セット作成のためのターゲット選択)
      * [embark-live: embark-collectのライブアップデート版](#embark-live-embark-collectのライブアップデート版)
   * [無駄なタイプなしで違うコマンドに切り替える](#無駄なタイプなしで違うコマンドに切り替える)
* [クイックスタート](#クイックスタート)
* [高度な設定](#高度な設定)
   * [利用可能なターゲットとアクションの情報表示](#利用可能なターゲットとアクションの情報表示)
   * [キーバインディングではなく補完によるコマンド選択](#キーバインディングではなく補完によるコマンド選択)
      * [Embark外部の補完でコマンド選択](#embark外部の補完でコマンド選択)
   * [アクション後にミニバッファーを閉じる](#アクション後にミニバッファーを閉じる)
   * [ターゲット挿入後のセットアップ実行](#ターゲット挿入後のセットアップ実行)
   * [アクションの前、後、前後でのフック実行](#アクションの前後前後でのフック実行)
   * [独自キーマップの設定](#独自キーマップの設定)
   * [ターゲットの新たなカテゴリーにアクションを定義する](#ターゲットの新たなカテゴリーにアクションを定義する)
      * [ミニバッファーの新たなターゲットの例 - tab-barバー](#ミニバッファーの新たなターゲットの例---tab-barバー)
      * [通常バッファーにおける新たなターゲットの例 - Wikipediaへのショートリンク](#通常バッファーにおける新たなターゲットの例---wikipediaへのショートリンク)
* [Embarkはどうやってアクションを呼び出すのか?](#embarkはどうやってアクションを呼び出すのか)
   * [非interactiveな関数からアクションへ](#非interactiveな関数からアクションへ)
* [Embark、MarginaliaとConsult](#embarkmarginaliaとconsult)
   * [Marginalia](#marginalia)
   * [Consult](#consult)
* [関連パッケージ](#関連パッケージ)
* [リソース](#リソース)
* [貢献してくれる人たちへ](#貢献してくれる人たちへ)
* [謝辞](#謝辞)

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

- - -

# 概説

<!-- Embark makes it easy to choose a command to run based on what is near point, both during a minibuffer completion session (in a way familiar to Helm or Counsel users) and in normal buffers. Bind the command `embark-act` to a key and it acts like prefix-key for a keymap of *actions* (commands) relevant to the *target* around point. With point on an URL in a buffer you can open the URL in a browser or eww or download the file it points to. If while switching buffers you spot an old one, you can kill it right there and continue to select another. Embark comes preconfigured with over a hundred actions for common types of targets such as files, buffers, identifiers, s-expressions, sentences; and it is easy to add more actions and more target types. Embark can also collect all the candidates in a minibuffer to an occur-like buffer or export them to a buffer in a major-mode specific to the type of candidates, such as dired for a set of files, ibuffer for a set of buffers, or customize for a set of variables.  -->

ミニバッファーでの補完セッション、あるいは通常のバッファーにおいてポイント付近に何があるかに応じて、実行するコマンドを簡単に選べるようにするのがEmbarkだ(ある意味HelmやCounselのユーザーにとってはお馴染みの方法かもしれない)。何かのキーにコマンド`embark-act`をバインドしよう。これはポイント周辺の *target(ターゲット)*に関係のある*action(アクション; コマンドのこと)* のキーマップにたいして、プレフィックスキーのように振る舞うのだ。バッファーのURL上にポイントがあればブラウザやewwでオープンしたり、そのURLが指すファイルをダウンロードできるだろう。バッファーの切り替え中に古いバッファーを見つけたら、その場で古いバッファーをkillして(訳注: こバッファーを閉じる`kill-buffer`というコマンドがある)、別のバッファーを探す作業を継続できるのだ。Embarkにはファイル、バッファー、識別子、S式、センテンスといった一般的なターゲット用に100以上のアクションが事前に定義されている。Embarkはミニバッファーのすべての候補をoccur風のバッファーに収集(collect)することもできる。候補のタイプに特化したメジャーモードのバッファーにエクスポートすることも可能だ。ファイルのセット(set: 集合)ならdired、バッファーセットならibuffer、変数セットの場合にはcustomizeといったように、そのターゲット用のメジャーモードのバッファーにターゲットをエクスポートできるという訳だ。

## ターゲットへのアクション

<!-- You can think of `embark-act` as a keyboard-based version of a right-click contextual menu. The `embark-act` command (which you should bind to a convenient key), acts as a prefix for a keymap offering you relevant *actions* to use on a *target* determined by the context: -->

右クリックで表示されるコンテキストメニューという機能があるが、`embark-act`はそれのキーボード版と考えることができる。コンテキストにより*ターゲット*が決定される。そのターゲットに関係のある*アクション*を提供するキーマップがあり、そのキーマップのプレフィックスキーとして動作するのが`embark-act`コマンドだ(使いやすいキーにバインドしよう)。

<!-- -   In the minibuffer, the target is the current top completion candidate. -->
<!-- -   In the `*Completions*` buffer the target is the completion at point. -->
<!-- -   In a regular buffer, the target is the region if active, or else the file, symbol, URL, s-expression or defun at point. -->

-   ミニバッファーではカレントでトップにある補完候補がターゲット
-   `*Completions*`バッファーでのターゲットはポイント位置にある補完
-   通常のバッファーではリージョンがアクティブならリージョン、それ以外の場合にはポイント位置にあるファイル、シンボル、URL、S式、defunがターゲット

<!-- Multiple targets can be present at the same location and you can cycle between them by repeating the `embark-act` key binding. The type of actions offered depend on the type of the target. Here is a sample of a few of the actions offered in the default configuration: -->

同じ場所に複数のターゲットが存在する場合には、`embark-act`にバインドしたキーを繰り返し押下することで、それらのターゲット間を巡回できる。提案されるアクションのタイプはターゲットのタイプ次第だ。デフォルトのコンフィグにおいて提案されるアクションの例をいくつか挙げてみよう:

<!-- -   For files you get offered actions like deleting, copying, renaming, visiting in another window, running a shell command on the file, etc. -->
<!-- -   For buffers the actions include switching to or killing the buffer. -->
<!-- -   For package names the actions include installing, removing or visiting the homepage. -->
<!-- -   For Emacs Lisp symbols the actions include finding the definition, looking up documentation, evaluating (which for a variable immediately shows the value, but for a function lets you pass it some arguments first). There are some actions specific to variables, such as setting the value directly or though the customize system, and some actions specific to commands, such as binding it to a key. -->

-   ファイルにたいして提案されるアクションは削除、コピー、リネーム、別ウィンドウでのvisit、そのファイルへのシェルコマンド実行等

-   バッファーの場合にはバッファーへの切り替え、バッファーのkill等のアクション

-   パッケージ名ならインストール、削除、あるいはホームページへのvisit等のアクション

-   Emacs Lispのシンボルにたいするアクションは定義の検索、ドキュメント照会、評価(変数なら値を即座に表示、関数ならまず渡す引数を指定できる)など
    変数特有のアクション(直接値をセット、カスタマイズシステム経由でセット等)もあれば、コマンド特有のアクション(キーへのバインディング等)もある

<!-- By default when you use `embark-act` if you don't immediately select an action, after a short delay Embark will pop up a buffer showing a list of actions and their corresponding key bindings. If you are using `embark-act` outside the minibuffer, Embark will also highlight the current target. These behaviors are configurable via the variable `embark-indicators`. Instead of selecting an action via its key binding, you can select it by name with completion by typing `C-h` after `embark-act`. -->

デフォルトでは`embark-act`を使用する際にすぐにアクションが選択されなければ、短い遅延の後にアクションとそのアクションのキーバインディングのリストを表示するバッファーをEmbarkがポップアップする。ミニバッファーの外部で`embark-act`を使用していれば、Embarkがカレントターゲットのハイライトも行うだろう。これらの振る舞いは変数`embark-indicators`で設定可能だ。`embark-act`の後に`C-h`をタイプすれば、キーバインディングでアクションを選択するかわりに補完つきでアクションの名前を選択することもできる。

<!-- Everything is easily configurable: determining the current target, classifying it, and deciding which actions are offered for each type in the classification. The above introduction just mentions part of the default configuration. -->

カレントターゲットの決定、クラス分け、そのクラス分けしたタイプそれぞれにたいして提案するアクションの判断など、すべてのことが簡単に設定できるようになっている。上記の例はデフォルトのコンフィグの一部を記したに過ぎないのだ。

<!-- Configuring which actions are offered for a type is particularly easy and requires no programming: the variable `embark-keymap-alist` associates target types with variables containing keymaps, and those keymaps containing bindings for the actions. (To examine the available categories and their associated keymaps, you can use `C-h v embark-keymap-alist` or customize that variable.) For example, in the default configuration the type `file` is associated with the symbol `embark-file-map`. That symbol names a keymap with single-letter key bindings for common Emacs file commands, for instance `c` is bound to `copy-file`. This means that if you are in the minibuffer after running a command that prompts for a file, such as `find-file` or `rename-file`, you can copy a file by running `embark-act` and then pressing `c`. -->

あるタイプにどのアクションを提案するかについての設定は特に簡単であり、プログラミングはまったく必要ない。変数`embark-keymap-alist`にはターゲットのタイプにたいして、変数(キーマップを含んでいる)が関連付けられている。そのキーマップにアクション用のバインディングが含まれているのだ(利用可能なカテゴリーと関連付けられたキーマップを調べるには`C-h v embark-keymap-alist`、あるいはcustomize機能でこの変数を調べることができる)。たとえばデフォルトのコンフィグではタイプ`file`にはシンボル`embark-file-map`が関連付けされている。このシンボルが命名しているのは、一文字のキーをEmacsの一般的なファイルコマンドにバインディング(たとえば`c`は`copy-file`)するキーマップだ。`find-file`や`rename-file`のようなファイルの入力を求めるコマンドを実行、その後に`embark-act`を実行して`c`を押下すればファイルをコピーすることができることを意味している。

<!-- These action keymaps are very convenient but not strictly necessary when using `embark-act`: you can use any command that reads from the minibuffer as an action and the target of the action will be inserted at the first minibuffer prompt. After running `embark-act` all of your key bindings and even `execute-extended-command` can be used to run a command. For example, if you want to replace all occurrences of the symbol at point, just use `M-%` as the action, there is no need to bind `query-replace` in one of Embark's keymaps. Also, those action keymaps are normal Emacs keymaps and you should feel free to bind in them whatever commands you find useful as actions and want to be available through convenient bindings. -->

これらのアクション用キーマップは非常に便利ではあるが、`embark-act`を使用する際には必ずしも必要という訳ではない。何であれミニバッファーから読み取るコマンドならアクションとして使用できるし、最初のミニバッファーのプロンプトにはそのアクションのターゲットが挿入されるからだ。`embark-act`の実行後にはすべてのキーバインディング、`execute-extended-command`でさえコマンドの実行に使用できる。たとえばポイント位置にあるシンボルの出現箇所すべてを置換したい場合には、単にアクションとして`M-%`を使うだけでよい。`query-replace`をEmbarkのいずれかのキーマップでバインドする必要はないのである。その上これらのアクション用のキーマップはEmacsの普通のキーマップと同じなのだ。つまりあなたが便利だと思ったコマンドなら何であれ、使いやすいキーにバインドすることを躊躇う理由はない筈だ。

<!-- The actions in `embark-general-map` are available no matter what type of completion you are in the middle of. By default this includes bindings to save the current candidate in the kill ring and to insert the current candidate in the previously selected buffer (the buffer that was current when you executed a command that opened up the minibuffer). -->

どのようなタイプの補完中であっても、`embark-general-map`に定義されているアクションは利用可能である。このマップにはカレント候補をkillリングに保存するためのバインディングと、以前に選択したバッファー(ミニバッファーをオープンするコマンドを実行した時点でカレントだったバッファーのこと)にカレント候補を挿入するためのバインディングがデフォルトで含まれている。

<!-- Emacs's minibuffer completion system includes metadata indicating the *category* of what is being completed. For example, `find-file`'s metadata indicates a category of `file` and `switch-to-buffer`'s metadata indicates a category of `buffer`. Embark has the related notion of the *type* of a target for actions, and by default when category metadata is present it is taken to be the type of minibuffer completion candidates when used as targets. Emacs commands often do not set useful category metadata so the [Marginalia](https://github.com/minad/marginalia) package, which supplies this missing metadata, is highly recommended for use with Embark. -->

Emacsのミニバッファーの補完システムには、どの*カテゴリー*を補完しているかを示すメタデータが含まれている。たとえば`find-file`は`file`のカテゴリー、`switch-to-buffer`は`buffer`のカテゴリーを示すメタデータが含まれているのだ。Embarkにはアクションの対象となるターゲットの*タイプ*に関する概念があり、メタデータでカテゴリーが与えられた場合には、ミニバッファーの補完候補がターゲットとなった際のタイプと同じように解釈される。Emacsには有益なカテゴリーをメタデータにセットしないコマンドが多いのだが、この欠落したメタデータを提供するパッケージが[Marginalia](https://github.com/minad/marginalia)だ。Embarkと一緒に使用することを強く推奨する。

<!-- Embark's default configuration has actions for the following target types: files, buffers, symbols, packages, URLs, bookmarks, and as a somewhat special case, actions for when the region is active. You can read about the [default actions and their key bindings](https://github.com/oantolin/embark/wiki/Default-Actions) on the GitHub project wiki.  -->

Embarkのデフォルトのコンフィグにはファイル、バッファー、シンボル、パッケージ、URL、ブックマークといったターゲットタイプ用のアクション、更に特殊ケース向けとしてリージョンがアクティブなとき用のアクションが定義されている。GitHubのプロジェクトwikiにある[default actions and their key bindings](https://github.com/oantolin/embark/wiki/Default-Actions)に目を通すのもよいだろう。

## ターゲットへのデフォルトアクション

<!-- Embark has a notion of default action for a target: -->

Embarkにはターゲット用のデフォルトアクションという概念がある:

<!-- -   If the target is a minibuffer completion candidate, then the default action is whatever command opened the minibuffer in the first place. For example if you run `kill-buffer`, then the default action will be to kill buffers. -->
<!-- -   If the target comes from a regular buffer (i.e., not a minibuffer), then the default action is whatever is bound to `RET` in the keymap of actions for that type of target. For example, in Embark's default configuration for a URL found at point the default action is `browse-url`, because `RET` is bound to `browse-url` in the `embark-url-map` keymap. -->


-   ターゲットがミニバッファーの補完候補の場合には、そもそもミニバッファーをオープンする発端となったコマンドがデフォルトアクション。たとえば`kill-buffer`ならデフォルトのアクションはバッファーのkill。
    
-   ターゲットが通常バッファー由来(ミニバッファーではない)の場合のデフォルトアクションは、そのターゲットのタイプにたいするキーマップで`RET`にバインドされているアクション。たとえばEmbarkののデフォルトの設定では、ポイント位置にあるURLにたいするデフォルトアクションは`browse-url`になる。これはキーマップ`embark-url-map`で`RET`が`browse-url`にバインドされているから。

<!-- To run the default action you can press `RET` after running `embark-act`. Note that if there are several different targets at a given location, each has its own default action, so first cycle to the target you want and then press `RET` to run the corresponding default action. -->

デフォルトアクションは`embark-act`を実行した後に`RET`を押下すれば実行できる。与えられた位置に複数の異なるターゲット(それぞれ独自のデフォルトアクションがある)が存在する場合には、目標とするターゲットまで巡回してそれから`RET`を押下すれば、そのターゲットに応じたデフォルトアクションが実行されるだろう。

<!-- There is also `embark-dwim` which runs the default action for the first target found. It's pretty handy in non-minibuffer buffers: with Embark's default configuration it will: -->

最初に見つけたターゲットにデフォルトアクションを実行する`embark-dwim`もある。これはミニバッファー以外のバッファーでは非常に役に立つと思う。Embarkのデフォルトのコンフィグでは以下のようにデフォルトアクションを実行するのだ:

<!-- -   Open the file at point. -->
<!-- -   Open the URL at point in a web browser (using the `browse-url` -->
<!--     command). -->
<!-- -   Compose a new email to the email address at point. -->
<!-- -   In an Emacs Lisp buffer, if point is on an opening parenthesis or -->
<!--     right after a closing one, it will evaluate the corresponding -->
<!--     expression. -->
<!-- -   Go to the definition of an Emacs Lisp function, variable or macro at -->
<!--     point. -->
<!-- -   Find the file corresponding to an Emacs Lisp library at point. -->

-   ポイント位置のファイルをオープン

-   ポイント位置のURLをウェブブラウザでオープン(`browse-url`を使用)

-   ポイント位置のメールアドレスで電子メールを新たに作成

-   ポイントが開きカッコか閉じカッコの直後にあればその式を評価(Emacs Lispバッファーの場合)

-   ポイント位置のEmacs Lispの関数、変数、マクロの定義にジャンプ

-   ポイント位置のEmacs Lispライブラリーに相当するファイルを検索

## アクション可能なターゲット集合にたいする処理

<!-- Besides acting individually on targets, Embark lets you work collectively on a set of target *candidates*. For example, while you are in the minibuffer the candidates are simply the possible completions of your input. Embark provides three main commands to work on candidate sets: -->

Embarkはターゲットに個別にアクションする場合を除いて、ターゲットの*候補*セットを固まりとして処理できるようになっている。たとえばミニバッファーにいるときの候補とは、単に入力から補完可能な候補だろう。Emacsには候補セットの処理用に主に3つのコマンドを提供している:

<!-- -   The `embark-act-all` command runs the same action on each of the current candidates. It is just like using `embark-act` on each candidate in turn. (Because you can easily act on many more candidates than you meant to, by default Embark asks you to confirm uses of `embark-act-all`; you can turn this off by setting the user option `embark-confirm-act-all` to `nil`.) -->

<!-- -   The `embark-collect` command produces a buffer listing all the current candidates, for you to peruse and run actions on at your leisure. The candidates are displayed as a list showing additional annotations. If any of the candidates contain newlines, then horizontal lines are used to separate candidates. -->
    
<!--     The Embark Collect buffer is somewhat "dired-like": you can select and deselect candidates through `embark-select` (available as an action in `embark-act`, bound to `SPC`; but you could also give it a global key binding). In an Embark Collect buffer `embark-act` is bound to `a` and `embark-act-all` is bound to `A`; `embark-act-all` will act on all currently marked candidates if there any, and will act on all candidates if none are marked. In particular, this means that `a SPC` will toggle whether the candidate at point is selected, and `A SPC` will select all candidates if none are selected, or deselect all selected candidates if there are some. -->

<!-- -   The `embark-export` command tries to open a buffer in an appropriate major mode for the set of candidates. If the candidates are files export produces a Dired buffer; if they are buffers, you get an Ibuffer buffer; and if they are packages you get a buffer in package menu mode. -->
    
<!--     If you use the grepping commands from the [Consult](https://github.com/minad/consult/) package, `consult-grep`, `consult-git-grep` or `consult-ripgrep`, then you should install the `embark-consult` package, which adds support for exporting a list of grep results to an honest grep-mode buffer, on which you can even use [wgrep](https://github.com/mhayashi1120/Emacs-wgrep) if you wish. -->


-   `embark-act-all`はカレント候補それぞれにたいして同じアクションを実行するコマンド。候補ごとに順番に`embark-act`を行うのと同じ(意図したより多くの候補に簡単にアクションを実行できてしまうので、デフォルトでは`embark-act-all`を使用する際にはEmbarkが確認を求めるようになっているが、ユーザーオプション`embark-confirm-act-all`を`nil`にすれば確認をオフに切り替えられる)。

-   `embark-collect`は都合のいいタイミングで吟味したアクションを実行できるように、カレント候補すべてをリストしたバッファーを生成するコマンド。候補は追加の注釈を伴うリストとして表示される。いずれかの候補に改行が含まれる場合には、候補を区切るための水平線が使用される。

    EmbarkのCollectバッファーは幾分"dired的"なバッファーだ。候補の選択と選択解除は`embark-select`を通じて行う(`embark-act`では`SPC`にバインドされているアクションだがグローバルなキーバインディングを付与してもよいだろう)。EmbarkのCollectバッファーでは`embark-act`は`a`、`embark-act-all`は`A`にバインドされている。`embark-act-all`はもしあればカレントでマークされている候補、何もマークされていなければすべての候補にたいしてアクションを行う。これはつまり`a SPC`はポイント位置の候補が選択されているかどうかの切り替え、`A SPC`は候補が何も選択されていなければすべての候補を選択、選択された候補がある場合には選択された候補の選択を解除することを意味している。

-   `embark-export`は候補セットにたいして適切なメジャーモードでバッファーのオープンを試みるコマンド。ファイルが候補ならDiredバッファー、バッファーならIbufferのバッファー、パッケージの場合には`package-menu-mode`のバッファーにエクスポートされるだろう。

    [Consult](https://github.com/minad/consult/)パッケージの`consult-grep`、`consult-git-grep`、`consult-ripgrep`といったgrep コマンドを使っているのであれば、`embark-consult`パッケージをインストールするべきだろう。これはgrepの結果リストをgrep-modeのバッファーにエクスポートするためのサポートを追加する。なにせ由緒正しいgrep-modeのバッファーだから、お望みなら[wgrep](https://github.com/mhayashi1120/Emacs-wgrep)の使用さえ可能なのだ。

<!-- When in doubt choosing between exporting and collecting, a good rule of thumb is to always prefer `embark-export` since when an exporter to a special major mode is available for a given type of target, it will be more featureful than an Embark collect buffer, and if no such exporter is configured the `embark-export` command falls back to the generic `embark-collect`. -->

エクスポートと収集のいずれを選ぶか迷ったときには、常に`embark-export`を選ぶというのが失敗のない経験則だろう。与えられたタイプのターゲット向けの特別なメジャーモードへのエクスポートが利用可能ならEmbarkのCollectバッファーより機能豊富だろうし、そのようなエクスポートが設定されていなければ`embark-export`は汎用的な`embark-collect`にフォールバックするからである。

<!-- These commands are always available as "actions" (although they do not act on just the current target but on all candidates) for `embark-act` and are bound to `A`, `S` (for "snapshot"), and `E`, respectively, in `embark-general-map`. This means that you do not have to bind your own key bindings for these (although you can, of course!), just a key binding for `embark-act`. -->

これらのコマンドは常に`embark-act`の"アクション"として利用でき(たとえカレントターゲットにアクションを行えなくても、すべての候補にアクションすることは可能だから)、`embark-general-map`でそれぞれ`A`、`S`("Snapshot"の"S")、`E`にバインドされている。これはつまり必要なのは`embark-act`にたいするキーバインディングだけであり、これらのコマンドにたいして独自にキーをバインドする必要がないことを意味している(もちろんバインドしても問題ない!)

<!-- In Embark Collect or Embark Export buffers that were obtained by running `embark-collect` or `embark-export` from within a minibuffer completion session, `g` is bound to a command that restarts the completion session, that is, the command that opened the minibuffer is run again and the minibuffer contents restored. You can then interact normally with the command, perhaps editing the minibuffer contents, and, if you wish, you can rerun `embark-collect` or `embark-export` to get an updated buffer. -->

EmbarkのCollectバッファーとEmbarkのExportバッファーはミニバッファーの補完セッションから`embark-collect`か`embark-export`を実行することで取得できる。補完セッションを再開するコマンド、すなわちミニバッファーをオープンしたコマンドは`g`にバインドされており、それを実行することによってミニバッファーのコンテンツをリストアするのだ。その後は通常通りそのコマンドと対話(多分ミニバッファーのコンテンツの編集とか)して、もしお望みなら`embark-collect`や`embark-export`を再実行して更新されたバッファーの入手もできるだろう。

### 即興の候補セット作成のためのターゲット選択

<!-- The commands for working with sets of candidates just described, namely `embark-act-all`, `embark-export` and `embark-collect` by default work with all candidates defined in the current context. For example, in the minibuffer they operate on all currently completion candidates, or in a dired buffer they work on all marked files (or all files if none are marked). Embark also has a notion of *selection*, where you can accumulate an ad hoc list of targets for these commands to work on. -->

前述のように候補セットにたいして処理を行うコマンド、すなわち`embark-act-all`、`embark-export`、`embark-collect`は、デフォルトではカレントコンテキストで定義されたすべての候補に機能する。たとえばミニバッファーにおいてはカレントで補完された候補すべて、diredバッファーであればマークされているすべてのファイル(マークされたファイルがなければすべてのファイル)にたいして処理を行う。Embarkには *セレクション(selection: 選択されたもの)* という概念もある。セレクションにはこれらのコマンドが処理するターゲットの即興リストを蓄積することができるのだ。

<!-- The selection is controlled by using the `embark-select` action, bound to `SPC` in `embark-general-map` so that it is always available (you can also give `embark-select` a global key binding if you wish; when called directly, not as an action for `embark-act`, it will select the first target at point). Calling this action on a target toggles its membership in the current buffer's Embark selection; that is, it adds it to selection if not selected and removes it from the selection if it was selected. Whenever the selection for a buffer is non-empty, the commands `embark-act-all`, `embark-export` and `embark-collect` will act on the selection. -->

セレクションは`embark-select`(`embark-general-map`で`SPC`にバインドされている)というアクションで制御できるので、いつでも利用することができる(もしお望みなら`embark-select`にグローバルなキーバインディングを与えることもできる; `embark-act`にたいするアクションではなく直接呼び出された際には、ポイント位置にある最初のターゲットを選択することになる)。このアクションをターゲットにたいして呼び出すことにより、カレントバッファーのEmbarkセレクションにおけるそのターゲットのメンバーシップを切り替えることができる。つまり選択されていなければセレクションに追加、すでに選択されていればセレクションから削除するということだ。あるバッファーにたいするセレクションが空でなければコマンド`embark-act-all`、`embark-export`、`embark-collect`は常にそのセレクションにたいして処理を行うことになる。

<!-- To deselect all selected targets, you can use the `embark-select` action through `embark-act-all`, since this will run `embark-select` on each member of the current selection. Similarly if no targets are selected and you are in a minibuffer completion session, running `embark-select` from `embark-act-all` will select all the current completion candidates. -->

`embark-act-all`を通して`embark-select`を使用すれば、選択されたすべてのターゲットの選択を解除することができる。これによりカレントセレクションのメンバーそれぞれにたいして`embark-select`が実行されるからだ。同様にしてミニバッファーの補完セッション中、何もターゲットが選択されていない状態から`embark-act-all`経由で`embark-select`を実行することにより、カレントの補完候補すべてを選択できる。

<!-- By default, whenever some targets are selected in the current buffer, a count of selected targets appears in the mode line. This can be turned off or customized through the `embark-selection-indicator` user option. -->

カレントバッファーで何かターゲットが選択されていれば、デフォルトではモードラインに選択されているターゲットの個数が表示される。これはユーザーオプション`embark-selection-indicator`をカスタマイズしてオフに切り替えることができる。

<!-- The selection functionality is supported in every buffer: -->

セレクションの機能はすべてのバッファーでサポートされている:

<!-- -   In the minibuffer this gives a convenient way to act on several completion candidates that don't follow any simple pattern: just go through the completions selecting the ones you want, then use `embark-act-all`. For example, you could attach several files at once to an email. -->
<!-- -   For Embark Collect buffers this functionality enables a dired-like workflow, in which you mark various candidates and apply an action to all at once. (It supersedes a previous ad hoc dired-like interface that was implemented only in Embark Collect buffers, with a slightly different interface.) -->
<!-- -   In a eww buffer you could use this to select various links you wish to follow up on, and then collect them into a buffer. Similarly, while reading Emacs's info manual you could select some symbols you want to read more about and export them to an `apropos-mode` buffer. -->
<!-- -   You can use selections in regular text or programming buffers to do complex editing operations. For example, if you have three paragraphs scattered over a file and you want to bring them together, you can select each one, insert them all somewhere and finally delete all of them (from their original locations). -->

-   これはミニバッファーにおいて、シンプルなパターンにしたがわない複数の補完候補にアクションを行う、便利な手段を提供する。選択したいターゲットを補完で絞り込んでから`embark-act-all`を使用すれば、たとえば複数のファイルを一度でメールに添付することができるだろう。

-   この機能をEmbarkのCollectバッファーで使えば、さまざまな候補にマークをつけてからすべての候補に一度にアクションを適用するという、dired風のワークフローが有効になる(少しインターフェイスは異なるが、これはEmbarkのCollectバッファーでのみ実装されていた前述のdired風の即興リストを置き換えるワークフローである)。

-   これをewwバッファーで使用すれば、辿りたいさまざまなリンクを選択してバッファーに収集することができる。同様にしてEmacsのinfoマニュアルを読みながら、更にマニュアルを調べたいシンボルをいくつか選択、それを`apropos-mode`のバッファーにエクスポートすればよいだろう。

-   通常のテキストやプログラミング用のバッファーで複雑な編集操作を行う際にセレクションを使用できる。たとえば1つファイルに散在する3つのパラグラフを1つにまとめたい場合には、パラグラフそれぞれを選択してからすべてを他の場所に挿入、最後に(元の場所にある)パラグラフをすべて削除すればよいだろう。

### embark-live: embark-collectのライブアップデート版

<!-- Finally, there is also an `embark-live` variant of the `embark-collect` command which automatically updates the collection after each change in the source buffer. Users of a completion UI that automatically updates and displays the candidate list (such as Vertico, Icomplete, Fido-mode, or MCT) will probably not want to use `embark-live` from the minibuffer as they will then have two live updating displays of the completion candidates! -->

最後に`embark-collect`の変種として`embark-live`というコマンドも存在する。これはコレクションを収集した後にソースバッファーが変更されると、収集したコレクションを自動的に更新するコマンドだ。候補リストを自動的に更新、表示するような(Vertico、Icomplete、Fidoモード、MCTのような)補完UIのユーザーであれば、補完候補のライブ更新と表示を二重に所有することになるので、ミニバッファーから`embark-live`を使いたいと思うことは多分ないとは思うが!

<!-- A more likely use of `embark-live` is to be called from a regular buffer to display a sort of live updating "table of contents" for the buffer. This depends on having appropriate candidate collectors configured in `embark-candidate-collectors`. There are not many in Embark's default configuration, but you can try this experiment: open a dired buffer in a directory that has very many files, mark a few, and run `embark-live`. You'll get an Embark Collect buffer containing only the marked files, which updates as you mark or unmark files in dired. To make `embark-live` genuinely useful other candidate collectors are required. The `embark-consult` package (documented near the end of this manual) contains a few: one for imenu items and one for outline headings as used by `outline-minor-mode`. Those collectors really do give `embark-live` a table-of-contents feel. -->

より相応しいのは通常のバッファーから`embark-live`を呼び出して、そのバッファーの"目次"をライブ更新で表示するような使い方だろう。これは`embark-candidate-collectors`に適切な候補コレクターが設定されているかどうかに依存する。Embarkのデフォルトのコンフィグにはあまり存在しないが、次のような実験を試すのはどうだろう。非常に大量のファイルがあるディレクトリーをdiredでオープンして、いくつかファイルをマークしてから`embark-live`を実行するのだ。これによりマークしたファイルだけを含むEmbarkのCollectバッファーが入手できた。これはdiredでのファイルのマーク、マーク解除に応じて更新されるバッファーだ。正真正銘役に立つ`embark-live`にするためには、別の候補コレクターが必要になる。(このマニュアルの終わりで触れる)`embark-consult`パッケージにもいくつか含まれている。1つはimenuアイテム、もう1つは`outline-minor-mode`で使用するようなアウトラインのヘディングだ。実際に`embark-live`に目次のようなフィーリングを与えてくれるのは、これらのコレクターが行うこと次第といえるだろう。

## 無駄なタイプなしで違うコマンドに切り替える

<!-- Embark also has the `embark-become` command which is useful for when you run a command, start typing at the minibuffer and realize you meant a different command. The most common case for me is that I run `switch-to-buffer`, start typing a buffer name and realize I haven't opened the file I had in mind yet! I'll use this situation as a running example to illustrate `embark-become`. When this happens I can, of course, press `C-g` and then run `find-file` and open the file, but this requires retyping the portion of the file name you already typed. This process can be streamlined with `embark-become`: while still in the `switch-to-buffer` you can run `embark-become` and effectively make the `switch-to-buffer` command become `find-file` for this run. -->

Embarkには`embark-become`というコマンドもある。これは何かコマンドを実行してミニバッファーでタイプし始めてから、実は違うコマンドを実行したかったのに気づいたというような状況で役に立つコマンドだ。わたしの場合もっとも一般的なのは`switch-to-buffer`してバッファー名のタイプを始めた後に、念頭にあるファイルをまだオープンしていないことに気がついたといったケースだ! この状況を`embark-become`を説明するための実行例として用いることにしよう。このような事態が発生したとしても、`C-g`を押下してから`find-file`を実行してファイルをオープンできる。当然だ。しかしこれにはすでに部分的にタイプしたファイル名を、もう一度タイプする必要があるだろう。このプロセスは`embark-become`で無駄を減らすことができる。まだ`switch-to-buffer`の実行中に`embark-become`を実行すれば、この実行における`switch-to-buffer`を`find-file`コマンドに効率的に転生させることができるだろう。

<!-- You can bind `embark-become` to a key in `minibuffer-local-map`, but it is also available as an action under the letter `B` (uppercase), so you don't need a binding if you already have one for `embark-act`. So, assuming I have `embark-act` bound to, say, `C-.`, once I realize I haven't open the file I can type `C-. B C-x C-f` to have `switch-to-buffer` become `find-file` without losing what I have already typed in the minibuffer. -->

`minibuffer-local-map`で`embark-become`を何かしらのキーにバインドすることも可能だが、これは`B`(大文字)にバインドされたアクションとしても利用できるようにしてあるので、すでに`embark-act`にキーをバインドしてあれば必要ないだろう。たとえば`embark-act`を`C-.`にバインドしてあるとすると、ファイルをまだオープンしていないことに気がついたら`C-. B C-x C-f`とタイプすることで、すでにミニバッファーでタイプしたものを失うことなく`switch-to-buffer`を`find-file`に転生させることができるのだ。

<!-- But for even more convenience, `embark-become` offers shorter key bindings for commands you are likely to want the current command to become. When you use `embark-become` it looks for the current command in all keymaps named in the list `embark-become-keymaps` and then activates all keymaps that contain it. For example, the default value of `embark-become-keymaps` contains a keymap `embark-become-file+buffer-map` with bindings for several commands related to files and buffers, in particular, it binds `switch-to-buffer` to `b` and `find-file` to `f`. So when I accidentally try to switch to a buffer for a file I haven't opened yet, `embark-become` finds that the command I ran, `switch-to-buffer`, is in the keymap `embark-become-file+buffer-map`, so it activates that keymap (and any others that also contain a binding for `switch-to-buffer`). The end result is that I can type `C-. B f` to switch to `find-file`. -->

もっと利便性を向上させよう。カレントコマンドから転生させたいコマンドと比較して、より短いキーバインディングを`embark-become`に提案してもらうのだ。`embark-become`は`embark-become-keymaps`のリストに載っているすべてのキーマップからカレントコマンドを探して、そのコマンドを含んだキーマップをすべてアクティブにする。たとえば`embark-become-keymaps`のデフォルト値にはキーマップ`embark-become-file+buffer-map`が含まれている。これはファイルとバッファー関連の複数のコマンドにたいするバインディングを定義しているが、特に注目すべきは`switch-to-buffer`を`b`、`find-file`を`f`にバインドしている点だ。つまり勘違いしてまだオープンしていないファイルのバッファーへ切り替えようとしたとき、`embark-become`は実行した`switch-to-buffer`を`embark-become-file+buffer-map`で発見してこのキーマップ(および`embark-become-file+buffer-map`のバインディングを含む他のキーマップ)をアクティブにする。最終的には`C-. B f`とタイプすれば`find-file`に切り替えられるという結果を得られるだろう。

# クイックスタート

<!-- The easiest way to install Embark is from GNU ELPA, just run `M-x package-install RET embark RET`. (It is also available on MELPA.) It is highly recommended to also install [Marginalia](https://github.com/minad/marginalia) (also available on GNU ELPA), so that Embark can offer you preconfigured actions in more contexts. For `use-package` users, the following is a very reasonable starting configuration: -->

Embarkをもっとも簡単にインストールできるのはGNU ELPAからインストールする方法だろう。単に`M-x package-install RET embark RET`を実行するだけだ(MELPAも利用可)。[Marginalia](https://github.com/minad/marginalia)のインストールも強く推奨する(これもGNU ELPAでインストール可)。Embarkがより多くのコンテキストで事前に定義されたアクションを提案できるようになるからだ。`use-package`のユーザーは、使い始めは以下のようなコンフィグが妥当だろう:

```lisp
    (use-package marginalia
      :ensure t
      :config
      (marginalia-mode))
    
    (use-package embark
      :ensure t
    
      :bind
      (("C-." . embark-act)         ;; 何か使いやすいバインディングを選ぶべし
       ("C-;" . embark-dwim)        ;; M-.の代替えとして適切なキーを選ぶべし
       ("C-h B" . embark-bindings)) ;; `describe-bindings'の代役
    
      :init
    
      ;; completing-readインターフェイスでキーヘルプを置き換え(オプション)
      (setq prefix-help-command #'embark-prefix-help-command)
    
      ;; Eldocを通じてポイント位置のEmbarkターゲットを表示する
      ;; 複数プロバイダドキュメントを参照したければEldocストラテジの調節が必要かもしれない
      ;; これを使用すると少し目障りに感じるかもしれないことに注意
      ;; ミニバッファーに表示されるメッセージが2行以上になるとモードラインが上下に移動するので
      ;; (add-hook 'eldoc-documentation-functions #'embark-eldoc-first-target)
      ;; (setq eldoc-documentation-strategy #'eldoc-documentation-compose-eagerly)
    
      :config
    
      ;; Embarkのliveバッファーと補完バッファーでモードラインを非表示にする
      (add-to-list 'display-buffer-alist
                   '("\\`\\*Embark Collect \\(Live\\|Completions\\)\\*"
                     nil
                     (window-parameters (mode-line-format . none)))))
    
    ;; Consultユーザーにはembark-consultパッケージもよいだろう
    (use-package embark-consult
      :ensure t ; EmbarkがConsultが見つけたらロードするのでインストールに必要なだけ
      :hook
      (embark-collect-mode . consult-preview-at-point-mode))
```

<!-- About the suggested key bindings for `embark-act` and `embark-dwim`: -->

`embark-act`と`embark-dwim`に提案したキーバインディングについて:

<!-- -   Those key bindings are unlikely to work in the terminal, but terminal users are probably well aware of this and will know to select different bindings. -->
<!-- -   The suggested `C-.` binding is used by default in (at least some installations of) GNOME to input emojis, and Emacs doesn't even get a chance to respond to the binding. You can select a different key binding for `embark-act` or use `ibus-setup` to change the shortcut for emoji insertion (Emacs 29 uses `C-x 8 e e`, in case you want to set the same one system-wide). -->
<!-- -   The suggested alternative of `M-.` for `embark-dwim` is bound by default to `xref-find-definitions`. That is a very useful command but overwriting it with `embark-dwim` is sensible since in Embark's default configuration, `embark-dwim` will also find the definition of the identifier at point. (Note that `xref-find-definitions` with a prefix argument prompts you for an identifier, `embark-dwim` does not cover this case). -->

-   これらのキーバインディングは端末では機能しないと思うが、端末のユーザーならすぐ気づくだろうし別のバインディングを選択すべきことも知っているだろう。

-   提案した`C-.`というバインディングは、(少なくともいくつかのバージョンの)GNOMEではデフォルトでemoji入力に使用されているので、Emacsにはこのバインディングに応答する機会さえ巡ってこない。`embark-act`用に別のキーバインディングを選択するか、あるいは`ibus-setup`を使用してemoji挿入のショートカットを変更できるだろう(Emacs 29なら`C-x 8 e e`を使えばシステム全体で同じバインディングを使用できる筈だ)。

-   `M-.`の代替えとして`embark-dwim`に提案したキーバインディングは、デフォルトでは`xref-find-definitions`にバインドされている。これは非常に役に立つコマンドではあるが`embark-dwim`で上書きするのは理に適っている。Embarkのデフォルトのコンフィグであれば、`embark-dwim`でポイント位置の識別子の検索も行われるからだ(`xref-find-definitions`の場合にはプレフィックス引数を指定すると識別子の入力を求めるが、このケースは`embark-dwim`ではカバーされていないことに注意)。

<!-- Other Embark commands such as `embark-act-all`, `embark-become`, `embark-collect`, and `embark-export` can be run through `embark-act` as actions bound to `A`, `B`, `S` (for "snapshot"), and `E` respectively, and thus don't really need a dedicated key binding, but feel free to bind them directly if you so wish. If you do choose to bind them directly, you'll probably want to bind them in `minibuffer-local-map`, since they are most useful in the minibuffer (in fact, `embark-become` only works in the minibuffer). -->

`embark-act-all`、`embark-become`、`embark-collect`、`embark-export`といった他のEmbarkコマンドは`embark-act`の実行を通じたアクションとしてそれぞれ`A`、`B`、`S`("Snapshot"より)、`E`にバインドされているので、実際には重複したキーバインディングは不要だが、お望みなら直接バインドすることを躊躇う理由はない。直接バインドすることを選択した場合には、`minibuffer-local-map`でバインドしたいと思うのではないだろうか。これらのコマンドがもっとも役に立つ場所がミニバッファーだからだ(実際のところ`embark-become`はミニバッファーでしか機能しない)。

<!-- The command `embark-dwim` executes the default action at point. Another good keybinding for `embark-dwim` is `M-.` since `embark-dwim` acts like `xref-find-definitions` on the symbol at point. `C-.` can be seen as a right-click context menu at point and `M-.` acts like left-click. The keybindings are mnemonic, both act at the point (`.`). -->

`embark-dwim`はポイント位置でデフォルトアクションを実行するコマンドだ。`embark-dwim`のキーバインディングとして他に適しているのは`M-.`だろう。`embark-dwim`はポイント位置のシンボルにたいして`xref-find-definitions`のようなアクションを行うからだ。`C-.`は右クリックで表示されるコンテキストメニュー、`M-.`は左クリックのように動作するとみなすことができる。このキーバインディングはどちらもポイント(`.`)に作用するという点に着目した語呂合わせである。

<!-- Embark needs to know what your minibuffer completion system considers to be the list of candidates and which one is the current candidate. Embark works out of the box if you use Emacs's default tab completion, the built-in `icomplete-mode` or `fido-mode`, or the third-party packages [Vertico](https://github.com/minad/vertico) or [Ivy](https://github.com/abo-abo/swiper). -->

Embarkはあなたのミニバッファー補完システムが何を候補リストとみなすのか、どの候補がカレント候補なのかを知っておく必要がある。Emacsのデフォルトのタブ補完、ビルトインの`icomplete-mode`や`fido-mode`、サードパーティ製パッケージの[Vertico](https://github.com/minad/vertico) or [Ivy](https://github.com/abo-abo/swiper)を使っていれば、インストールするだけでEmbarkを使用することができる筈だ。

<!-- If you are a [Helm](https://emacs-helm.github.io/helm/) or [Ivy](https://github.com/abo-abo/swiper) user you are unlikely to want Embark since those packages include comprehensive functionality for acting on minibuffer completion candidates. (Embark does come with Ivy integration despite this.)  -->

[Helm](https://emacs-helm.github.io/helm/)や[Ivy](https://github.com/abo-abo/swiper)にはミニバッファーの補完候補に作用するための包括的な機能が含まれているので、これらのパッケージのユーザーがEmbarkを望むことは無さそうだ(にも関わらずEmbarkにはIvyとの統合が含まれている)。

# 高度な設定

## 利用可能なターゲットとアクションの情報表示

<!-- By default, if you run `embark-act` and do not immediately select an action, after a short delay Embark will pop up a buffer called `*Embark Actions*` containing a list of available actions with their key bindings. You can scroll that buffer with the mouse of with the usual commands `scroll-other-window` and `scroll-other-window-down` (bound by default to `C-M-v` and `C-M-S-v`). -->

`embark-act`を実行した後にすぐにアクションを選択しないと、デフォルトでは短い遅延を挟んでからEmbarkが`*Embark Actions*`という名前のバッファーをポップアップする。これは利用できるアクションとそのアクションのキーバインディングからなるリストを表示するバッファーだ。このバッファーは通常の`scroll-other-window`と`scroll-other-window-down`のコマンドでマウスでスクロールできる(デフォルトではそれぞれ`C-M-v`と`C-M-S-v`にバインドされている筈だ)。

<!-- That functionality is provided by the `embark-mixed-indicator`, but Embark has other indicators that can provide information about the target and its type, what other targets you can cycle to, and which actions have key bindings in the action map for the current type of target. Any number of indicators can be active at once and the user option `embark-indicators` should be set to a list of the desired indicators. -->

これは`embark-mixed-indicator`が提供する機能だが、Embarkにはターゲットとターゲットのタイプ、カレントターゲットのタイプ用のアクションマップでキーバインディングをもっているアクションはどれかといった情報を提供するために、別のインジケーターが存在する。一度に任意の個数のインジケーターをアクティブにできる。これを使用するには使用したいインジケーターのリストをユーザーオプション`embark-indicators`にセットする必要がある。

<!-- Embark comes with the following indicators: -->

Embarkに同梱されているインジケーターは以下の通りだ:

<!-- -   `embark-minimal-indicator`: shows a messages in the echo area or minibuffer prompt showing the current target and the types of all targets starting with the current one. -->
<!-- -   `embark-highlight-indicator`: highlights the target at point; on by default. -->
<!-- -   `embark-verbose-indicator`: displays a table of actions and their key bindings in a buffer; this is not on by default, in favor of the mixed indicator described next. -->
<!-- -   `embark-mixed-indicator`: starts out by behaving as the minimal indicator but after a short delay acts as the verbose indicator; this is on by default. -->
<!-- -   `embark-isearch-highlight-indicator`: this only does something when the current target is the symbol at point, in which case it lazily highlights all occurrences of that symbol in the current buffer, like isearch; also on by default. -->

-   `embark-minimal-indicator`: カレントターゲットを起点にすべてのターゲットとそのタイプを記したメッセージを、エコーエリアまたはミニバッファーのプロンプトに表示する。

-   `embark-highlight-indicator`: ポイント位置のターゲットをハイライト(デフォルトでオン)。

-   `embark-verbose-indicator`: バッファーにアクションとそのキーバインディングのテーブルを表示する。次に説明するミックスされたインジケーターの方を優先したため、デフォルトでオンにはなっていない。

-   `embark-mixed-indicator`: 最初は最小限のインジケーターとして振る舞うが、短い遅延を挟んだ後はverbose(冗長、情報が多い)なインジケーターとして振る舞う(デフォルトでオン)。

-   `embark-isearch-highlight-indicator`: ポイント位置のシンボルがカレントターゲットのときだけ何かを行うインジケーター。この場合だとIsearchのように、カレントバッファーでそのシンボルのすべての出現箇所を遅延ハイライトする(これもデフォルトでオン)。

<!-- Users of the popular [which-key](https://github.com/justbur/emacs-which-key) package may prefer to use the `embark-which-key-indicator` from the [Embark wiki](https://github.com/oantolin/embark/wiki/Additional-Configuration#use-which-key-like-a-key-menu-prompt). Just copy its definition from the wiki into your configuration and customize the `embark-indicators` user option to exclude the mixed and verbose indicators and to include `embark-which-key-indicator`. -->

人気パッケージの[which-key](https://github.com/justbur/emacs-which-key)のユーザーは、[Embark wiki](https://github.com/oantolin/embark/wiki/Additional-Configuration#use-which-key-like-a-key-menu-prompt)の`embark-which-key-indicator`の方が好みに合うかもしれない。このwikiからあなたのコンフィグに定義をコピーしたら、mixedとverboseのインジケーターを除外して`embark-which-key-indicator`を含めるように、ユーザーオプション`embark-indicators`をカスタマイズするだけでよい筈だ。

<!-- If you use [Vertico](https://github.com/minad/vertico), there is an even easier way to get a `which-key`-like display that also lets you use completion to narrow down the list of alternatives, described at the end of the next section.  -->

[Vertico](https://github.com/minad/vertico)を使っているのであれば、選択肢リストを補完で絞り込んで`which-key`風に表示する更に簡単な方法がある。次セクションの最後に説明しよう。

## キーバインディングではなく補完によるコマンド選択

<!-- As an alternative to reading the list of actions in the verbose or mixed indicators (see the previous section for a description of these), you can press the `embark-help-key`, which is `C-h` by default (but you may prefer `?` to free up `C-h` for use as a prefix) after running `embark-act`. Pressing the help key will prompt you for the name of an action with completion (but feel free to enter a command that is not among the offered candidates!), and will also remind you of the key bindings. You can press `embark-keymap-prompter-key`, which is `@` by default, at the prompt and then one of the key bindings to enter the name of the corresponding action. -->

verboseやmixedといったインジケーター(これらについては前セクションを参照)にリストされたアクションを読むかわりに、`embark-act`の実行後に`embark-help-key`(デフォルトでは`C-h`)を押下するという方法もある(`C-h`はプレフィックスとして使用できるように自由にしておいて、かわりに`?`を使う方が気に入るかもしれない)。ヘルプキーを押下することにより、補完付きでアクション名の入力を求めるプロンプトが表示されるだろう(提案された候補にないコマンドを入力しても構わない!)。更にキーバインディングのリマインド機能もついている。プロンプトで`embark-keymap-prompter-key`(デフォルトでは`@`)、その後に名前を入力したアクションに相当するキーバインディングを押下すればよいのだ。

<!-- You may think that with the `*Embark Actions*` buffer popping up to remind you of the key bindings you'd never want to use completion to select an action by name, but personally I find that typing a small portion of the action name to narrow down the list of candidates feels significantly faster than visually scanning the entire list of actions. -->

`*Embark Actions*`バッファーがポップアップしてキーバインディングを教えてくれるので、アクション名の選択に補完を使いたいと思う訳がないと考えるかもしれない。しかしわたしの個人的な経験が教えてくれたのは、アクションのリスト全体を視覚的にスキャンするよりも、候補リストを絞り込むためにアクション名のほんの一部をタイプする方が断然速く感じられるということだ。

<!-- If you find you prefer selecting actions that way, you can configure embark to always prompt you for actions by setting the variable )`embark-prompter` to `embark-completing-read-prompter`. -->

アクションの選択としてこの方法が気に入ったのなら、変数`embark-prompter`に`embark-completing-read-prompter`をセットすれば、常にアクションの入力を求めるようにEmbarkを設定できる。

<!-- On the other hand, you may wish to continue using key bindings for the actions you perform most often, and to use completion only to explore what further actions are available or when you've forgotten a key binding. In that case, you may prefer to use the minimal indicator, which does not pop-up an `*Embark Actions*` buffer at all, and to use the `embark-help-key` whenever you need help. This unobtrusive setup is achieved with the following configuration: -->

その一方でもっとも頻繁に行うアクションにはキーバインディングを使い続けて、利用可能なアクションを更に探すときやキーバインディングを忘れてしまった場合のみ補完を使いたい場合もあるだろう。このような場合には`*Embark Actions*`バッファーをポップアップしないminimalなインジケーターを使い、ヘルプが必要ならいつでも`embark-help-key`を使える方が気に入るかもしれない。この地味なセットアップは以下の設定で実現できる筈だ:

```lisp
    (setq embark-indicators
          '(embark-minimal-indicator  ; デフォルトはembark-mixed-indicator
            embark-highlight-indicator
            embark-isearch-highlight-indicator))
```

<!-- [Vertico](https://github.com/minad/vertico) users may wish to configure a grid display for the actions and key-bindings, reminiscent of the popular package [which-key](https://github.com/justbur/emacs-which-key), but, of course, enhanced by the use of completion to narrow the list of commands. In order to get the grid display, put the following in your Vertico configuration: -->

[Vertico](https://github.com/minad/vertico)ユーザーであれば、人気パッケージ[which-key](https://github.com/justbur/emacs-which-key)を想起させるが、もちろん補完によるコマンドリストの絞り込みによって強化されている、アクションとキーバインディング用のグリッド表示を設定したいと思うかもしれない。グリッド表示を手に入れるためには、以下をVerticoのコンフィグに記述すればよいだろう:

```lisp
    (add-to-list 'vertico-multiform-categories '(embark-keybinding grid))
    (vertico-multiform-mode)
```

<!-- This will make the available keys be shown in a compact grid like in `which-key`. The `vertico-multiform-mode` also enables keys such as `M-V`, `M-G`, `M-B`, and `M-U` for manually switching between layouts in Vertico buffers. -->

これで利用可能なキーが`which-key`のようなコンパクトなグリッドに表示されるだろう。`vertico-multiform-mode`では`M-V`、`M-G`、`M-B`、`M-U`といったキーが利用できる。これはVerticoバッファーのレイアウト間を手動で切り替えるコマンドだ。

### Embark外部の補完でコマンド選択

<!-- If you like this completion interface for exploring key bindings for Embark actions, you may want to use it elsewhere in Emacs. You can use Embark's completion-based command prompter to list: -->

このEmbarkアクションのキーバインディングを探す補完インターフェイスが気に入ったならば、Emacsのどこでもこれを使いたいのではないだろうか。Embarkの補完ベースのコマンドプロンプターをリストにした:

<!-- -   key bindings under a prefix, -->
<!-- -   local key bindings, or -->
<!-- -   all key bindings. -->

-   プレフィックス配下のキーバインディング

-   ローカルなキーバインディング

-   キーバインディングすべて

<!-- To use it for key bindings under a prefix (you can use this to replace the `which-key` package, for example), use this configuration: -->

プレフィックス配下のキーバインディングを使用するのであれば、以下のコンフィグを使うとよいだろう:


```lisp
    (setq prefix-help-command #'embark-prefix-help-command)
```

<!-- Now, when you have started on a prefix sequence such as `C-x` or `C-c`, pressing `C-h` will bring up the Embark version of the built-in `prefix-help-command`, which will list the keys under that prefix and their bindings, and lets you select the one you wanted with completion, or by key binding if you press `embark-keymap-prompter-key`. -->

こうしておけば`C-x`や`C-c`といったプレフィックスシーケンスで開始したときには、`C-h`を押下することでビルトインの`prefix-help-command`のEmbark版が立ち上がる筈だ。これにはそのプレフィックスの配下にあるキーがリストされていて、目当てのコマンドを補完で選択したり、`embark-keymap-prompter-key`を押下すればキーバインディングで選択できるようになっている。

<!-- To list local or global key bindings, use the command `embark-bindings`. You can bind that to `C-h b`, which is the default key binding for the built-in `describe-bindings` command, which this command can replace. By default, `embark-bindings` lists local key bindings, typically those bound in the major mode keymap; to get global bindings as well, call it with a `C-u` prefix argument. -->

ローカルのキーバインディングやグローバルなキーバインディングをリストする場合には、コマンド`embark-bindings`を使用できる。このコマンドを`C-h b`にバインドすれば、これはビルトインの`describe-bindings`にたいするデフォルトのキーバインディングなので、コマンドの置き換えが完了だ。デフォルトでは`embark-bindings`がリストするのはローカルのキーバインディングであり、典型的にはメジャーモードのキーマップによってバインドされたキーが該当するだろう。プレフィックス引数`C-u`とともに呼び出せば、同じようにしてグローバルなキーバインディングを得ることができるだろう。

## アクション後にミニバッファーを閉じる

<!-- By default, if you call `embark-act` from the minibuffer it quits the minibuffer after performing the action. You can change this by setting the user option `embark-quit-after-action` to `nil`. Having `embark-act` *not* quit the minibuffer can be useful to turn commands into little "thing managers". For example, you can use `find-file` as a little file manager or `describe-package` as a little package manager: you can run those commands, perform a series of actions, and then quit the command. -->

ミニバッファーから`embark-act`を呼び出すと、デフォルトではアクションを実行した後にミニバッファーは閉じられるようになっている。これはユーザーオプション`embark-quit-after-action`を`nil`にセットすることで変更可能だ。`embark-act`がミニバッファーを*閉じない*ようにすることで、コマンドを小さな"thing manager"に変身させる役に立つかもしれない。たとえば小さなファイルマネージャーとして`find-file`、小さなパッケージマネージャーとして`describe-package`といったコマンドを実行して、一連のアクションを行い、そのコマンドを終了するといった使い方ができるだろう。

<!-- If you want to control the quitting behavior in a fine-grained manner depending on the action, you can set `embark-quit-after-action` to an alist, associating commands to either `t` for quitting or `nil` for not quitting. When using an alist, you can use the special key `t` to specify the default behavior. For example, to specify that by default actions should not quit the minibuffer but that using `kill-buffer` as an action should quit, you can use the following configuration: -->

コマンドごとに`t`(閉じる)または`nil`(閉じない)を関連付けるalistを`embark-quit-after-action`にセットすれば、アクションに応じてよりきめ細かいやり方で閉じる際の挙動を制御できる。alistを使用する際には、デフォルトの挙動を指定するための特別なキーとして`t`を使うことができる。たとえばデフォルトアクションではミニバッファーを閉じないが、アクションとして`kill-buffer`を使用したときには閉じるような指定には、以下のコンフィグを使用できるだろう:

```lisp
    (setq embark-quit-after-action '((kill-buffer . t) (t . nil)))
```

<!-- The variable `embark-quit-after-action` only specifies a default, that is, it only controls whether or not `embark-act` quits the minibuffer when you call it without a prefix argument, and you can select the opposite behavior to what the variable says by calling `embark-act` with `C-u`. Also note that both the variable `embark-quit-after-action` and `C-u` have no effect when you call `embark-act` outside the minibuffer. -->

変数`embark-quit-after-action`に指定できるのはデフォルトだけである。つまりプレフィックス引数なしで`embark-act`を呼び出したときに、ミニバッファーを閉じるか否かの制御だけを行うのだ。ただしプレフィックス引数`C-u`とともに`embark-act`を呼び出した場合には、この変数の指定とは反対の挙動を選択できる仕組みにしてある。ミニバッファーの外部で`embark-act`を呼び出したときには、変数`embark-quit-after-action`とプレフィックス引数`C-u`のどちらとも効果がないことに注意して欲しい。

<!-- If you find yourself using the quitting and non-quitting variants of `embark-act` about equally often, independently of the action, you may prefer to simply have separate commands for them instead of a single command that you call with `C-u` half the time. You could, for example, keep the default exiting behavior of `embark-act` and define a non-quitting version as follows: -->

何のアクションかに関係なく閉じるバージョンの`embark-act`と閉じない変種バージョンの使用頻度が同程度であるようなら、1つのコマンドを2回に1回は`C-u`付きで呼び出すやり方よりも、シンプルに別のコマンドを定義する方が好みに合うかもしれない。たとえば以下のようにすれば、デフォルトでは閉じる`embark-act`の挙動を維持しつつ、閉じないバージョンを定義できるだろう:

```lisp
    (defun embark-act-noquit ()
      "アクションを実行した後にミニバッファーを閉じない"
      (interactive)
      (let ((embark-quit-after-action nil))
        (embark-act)))
```

## ターゲット挿入後のセットアップ実行

<!-- You can customize what happens after the target is inserted at the minibuffer prompt of an action. There are `embark-target-injection-hooks`, that are run by default after injecting the target into the minibuffer. The variable `embark-target-injection-hooks` is an alist associating commands to their setup hooks. There are two special keys: if no setup hook is specified for a given action, the hook associated to `t` is run; and the hook associated to `:always` is run regardless of the action. (This variable used to have the less explicit name of `embark-setup-action-hooks`, so please update your configuration.) -->

あるアクションのミニバッファープロンプトにターゲットを挿入した後に何が発生するかはカスタマイズ可能だ。ミニバッファーへターゲットを差し込んだ後にデフォルトで実行されるのが`embark-target-injection-hooks`である(inject: 注射、導入、差し挟む)。`embark-target-injection-hooks`はコマンドとコマンドのセットアップのフックを関連付けるalistを格納する変数だ。特別なキーが2つある。あるアクションにセットアップフックが指定されていない場合には`t`に関連付けられたフックが実行される、もう1つアクションとは関係なく常に実行されるのが`:always`に関連付けられたフックである(この変数の以前の少し曖昧な`embark-setup-action-hooks`は変更されたので、コンフィグを更新して欲しい)。

<!-- For example, consider using `shell-command` as an action during file completion. It would be useful to insert a space before the target file name and to leave the point at the beginning, so you can immediately type the shell command to run on that file. That's why in Embark's default configuration there is an entry in `embark-target-injection-hooks` associating `shell-command` to a hook that includes `embark--shell-prep`, a simple helper function that quotes all the spaces in the file name, inserts an extra space at the beginning of the line and leaves point to the left of it. -->

たとえばファイル補完中のアクションとして`shell-command`を使用する場合を考えてみよう。ポイントをプロンプトの先頭に残したままターゲットのファイル名の前にスペースが挿入してあれば、そのファイルに実行するシェルコマンドをすぐにタイプできるので役に立つのではないだろうか。Embarkの`embark-target-injection-hooks`のデフォルト設定では、`shell-command`に関連付けられたフックに`embark--shell-prep`(ファイル名に含まれるすべてのスペースをクォートしてその行の左端にポイントを残したまま行頭に余分なスペースを挿入するシンプルなヘルパー関数)を含んだエントリーがに存在するのは、これが理由である。

<!-- Now, the preparation that `embark--shell-prep` does would be useless if Embark did what it normally does after it inserts the target of the action at the minibuffer prompt, which is to "press `RET`" for you, accepting the target as is; if Embark did that for `shell-command` you wouldn't get a chance to type in the command to execute! That is why in Embark's default configuration the entry for `shell-command` in `embark-target-injection-hooks` also contains the function `embark--allow-edit`. -->

そうなると今度はアクションのターゲットをミニバッファープロンプトに挿入後にEmbarkが通常行うこと、つまり"`RET`の押下"でそのターゲットを受け入れるという動作をEmbarkが行った場合には、`embark--shell-prep`が計らった準備は役立たずになってしまうだろう。`shell-command`にたいしてEmbarkがこれを行った場合には、実行するコマンドをあなたがタイプする機会は巡ってこないのだ! これがEmbarkのデフォルト設定で`embark-target-injection-hooks`の`shell-command`にたいするエントリーに、関数`embark--allow-edit`が含まれている理由だ。

<!-- Embark used to have a dedicated variable `embark-allow-edit-actions` to which you could add commands for which Embark should forgo pressing `RET` for you after inserting the target. Since its effect can also be achieved via the general `embark-target-injection-hooks` mechanism, that variable has been removed to simplify Embark. Be sure to update your configuration; if you had something like: -->

以前のEmbarkには`embark-allow-edit-actions`という変数があった。これはターゲットを挿入した後に、Embarkに`RET`を押下させないコマンドを追加するための専用の変数だった。この効果は汎用的なメカニズムである`embark-target-injection-hooks`を通じて実現できたこともあり、この変数はEmbarkを簡素化するために削除された。以下のような設定をしていたら忘れずに更新して欲しい:

```lisp
    (add-to-list 'embark-allow-edit-actions 'my-command)
```

<!-- you should replace it with: -->

以下のように書き換える必要がある:

```lisp
    (push 'embark--allow-edit
          (alist-get 'my-command embark-target-injection-hooks))
```

<!-- Also note that while you could abuse `embark--allow-edit` so that you have to confirm "dangerous" actions such as `delete-file`, it is better to implement confirmation by adding the `embark--confirm` function to the appropriate entry of a different hook alist, namely, `embark-pre-action-hooks`. -->

同意を要する`delete-file`のような"危険(dangerous)"なアクションに、`embark--allow-edit`を悪用することもできるが別のフック、具体的には`embark-pre-action-hooks`の適切なエントリーに`embark--confirm`関数を追加して同意を求める処理を実装する方がよい。

<!-- Besides `embark--allow-edit`, Embark comes with another function that is of general utility in action setup hooks: `embark--ignore-target`. Use it for commands that do prompt you in the minibuffer but for which inserting the target would be inappropriate. This is not a common situation but does occasionally arise. For example it is used by default for `shell-command-on-region`: that command is used as an action for region targets, and it prompts you for a shell command; you typically do *not* want the target, that is the contents of the region, to be entered at that prompt! -->

`embark--allow-edit`とは別に、Embarkにはアクションのセットアップフックにおける汎用的なユーティリティとして、`embark--ignore-target`という別の関数が同梱されている。これはターゲットの挿入には適していないが、ミニバッファーでプロンプトに入力を求めるコマンドに使用できるだろう。一般的な状況では発生しないだろうが、ときどき発生することはあるだろう。`shell-command-on-region`にたいするデフォルトとして使用されているのがその一例だ。このコマンドはリージョンターゲットのアクションとして使用されており、シェルコマンドの入力を求めるのだ。このケースではターゲットはリージョンのコンテンツになるので、普通はプロンプトに入力して欲しいとは*思わない*筈だ!

## アクションの前、後、前後でのフック実行

<!-- Embark has three variables, `embark-pre-action-hooks`, `embark-post-action-hooks` and `embark-around-action-hooks`, which are alists associating commands to hooks that should run before or after or as around advice for the command when used as an action. As with `embark-target-injection-hooks`, there are two special keys for the alists: `t` designates the default hook to run when no specific hook is specified for a command; and the hook associated to `:always` runs regardless. -->

Embarkには`embark-pre-action-hooks`、`embark-post-action-hooks`、`embark-around-action-hooks`という3つの変数がある。これはコマンド、アクションとして使用した際にそのコマンドの前、後、あるいは前後のどのタイミングでフックを実行するべきかを関連付けるalistだ。`embark-target-injection-hooks`のときと同じように、alist用に2つの特別なキーが存在する。あるコマンドにたいして特に指定されたフックが存在しない場合に実行するデフォルトのフックを指定するキーが`t`、関連付けられたフックを無条件で実行するキーが`:always`である。

<!-- The default values of those variables are fairly extensive, adding creature comforts to make running actions a smooth experience. Embark comes with several functions intended to be added to these hooks, and used in the default values of `embark-pre-action-hooks`, `embark-post-action-hooks` and `embark-around-action-hooks`. -->

これらの変数のデフォルト値は非常に広範に渡るので、快適さを盛り込むことができれば、スムーズなアクションの実行体験を得られるだろう。。Embarkにはこれらのフックへの追加を意図した関数が複数同梱されており`embark-pre-action-hooks`、`embark-post-action-hooks`、`embark-around-action-hooks`のデフォルト値として使用されている。

<!-- For pre-action hooks: -->

pre-actionフック用:

<!-- -   **`embark--confirm`:** Prompt the user for confirmation before executing the action. This is used be default for commands deemed "dangerous", or, more accurately, hard to undo, such as `delete-file` and `kill-buffer`. -->
<!-- -   **`embark--unmark-target`:** Unmark the active region. Use this for commands you want to act on the region contents but without the region being active. The default configuration uses this function as a pre-action hook for `occur` and `query-replace`, for example, so that you can use them as actions with region targets to search the whole buffer for the text contained in the region. Without this pre-action hook using `occur` as an action for a region target would be pointless: it would search for the the region contents *in the region*, (typically, due to the details of regexps) finding only one match! -->
    <!-- -   **`embark--beginning-of-target`:** Move to the beginning of the target (for targets that report bounds). This is used by default for backward motion commands such as `backward-sexp`, so that they don't accidentally leave you on the current target. -->
<!-- -   **`embark--end-of-target`:** Move to the end of the target. This is used similarly to the previous function, but also for commands that act on the last s-expression like `eval-last-sexp`. This allow you to act on an s-expression from anywhere inside it and still use `eval-last-sexp` as an action. -->
<!-- -   **`embark--xref-push-markers`:** Push the current location on the xref marker stack. Use this for commands that take you somewhere and for which you'd like to be able to come back to where you were using `xref-pop-marker-stack`. This is used by default for `find-library`. -->

-   **`embark--confirm`:** アクション実行の前にユーザーに確認を求める。これは"危険"とみなされているコマンド、もっと正確にいうと`delete-file`や`kill-buffer`といったアンドゥ(undo)によって取り消すのが困難なコマンド用のデフォルトに使用されている。

-   **`embark--unmark-target`:** アクティブなリージョンのマークを解除(unmark)する。リージョンをアクティブにせずにそのコンテンツにアクションさせたいコマンドに使用する。デフォルトのコンフィグでは`occur`および`query-replace`にたいするpre-actionフックとしてこの関数を使用している。たとえばそのリージョンに含まれるテキストをバッファー全体から検索するために、リージョンのターゲットへのアクションとしてこれらの関数を使用するのだ。このpre-actionフックを使わずにリージョンのターゲットへのアクションとして`occur`を使うのは無意味だ。*そのリージョンの中*でそのリージョンのコンテンツを検索しても、(典型的にはregexpの詳細により)見つかるマッチは1つだけだろう!

-   **`embark--beginning-of-target`:** (境界を報告するターゲットにたいして)ターゲットの先頭に移動する。これは`backward-sexp`のような後方への移動コマンドのデフォルトとして使用されている。これを使えば間違ってカレントターゲット上に取り残される恐れはないだろう。

-   **`embark--end-of-target`:** ターゲットの終端に移動する。上記関数と同じように使用されるが、`eval-last-sexp`のような最後のS式(s-expressionsexpとも略される)にアクションするコマンドにも使用される。これによりS式内のどこからでもS式にアクションできるし、依然としてアクションとして`eval-last-sexp`を使うことができるだろう。

-   **`embark--xref-push-markers`:** カレントの位置をxrefマーカースタックにpushする。あなたをどこかへ連れて行った後に、`xref-pop-marker-stack`を使った場所に戻れるようなコマンドにたいして使用する。これは`find-library`にたいしてデフォルトで使用されている。

post-actionフック用:

<!-- -   **`embark--restart`:** Restart the command currently prompting in the minibuffer, so that the list of completion candidates is updated. This is useful as a post action hook for commands that delete or rename a completion candidate; for example the default value of `embark-post-action-hooks` uses it for `delete-file`, `kill-buffer`, `rename-file`, `rename-buffer`, etc. -->

-   **`embark--restart`:** 補完候補のリストを更新するために、ミニバッファーでカレントでプロンプトを表示しているコマンドをリスタートする。これは補完候補の削除やリネームを行うコマンドのpost-actionフックとして役に立つだろう。たとえば`embark-post-action-hooks`のデフォルト値では`delete-file`、`kill-buffer`、`rename-file`、`rename-buffer`等にたいしてこの関数を使用している。

around-actionフック用:

<!-- -   **`embark--mark-target`:** Save existing mark and point location, mark the target and run the action. Most targets at point outside the minibuffer report which region of the buffer they correspond to (this is the information used by `embark-highlight-indicator` to know what portion of the buffer to highlight); this function marks that region. It is useful as an around action hook for commands that expect a region to be marked, for example, it is used by default for `indent-region` so that it works on s-expression targets, or for `fill-region` so that it works on paragraph targets. -->
<!-- -   **`embark--cd`:** Run the action with `default-directory` set to the directory associated to the current target. The target should be of type `file`, `buffer`, `bookmark` or `library`, and the associated directory is what you'd expect in each case. -->
<!-- -   **`embark--narrow-to-target`:** Run the action with buffer narrowed to current target. Use this as an around hook to localize the effect of actions that don't already work on just the region. In the default configuration it is used for `repunctuate-sentences`. -->
<!-- -   **`embark--save-excursion`:** Run the action restoring point at the end. The current default configuration doesn't use this but it is available for users. -->

-   **`embark--mark-target`:** 既存のマークとポイントの位置を保存してから、ターゲットをマークしてアクションを実行する。ミニバッファー外部のポイント位置にあるターゲットのほとんどは、ターゲットがそれぞれバッファーのどのリージョンに対応するかを報告するようになっている(この情報は`embark-highlight-indicator`がバッファーのどの部分をハイライトするかを得るために使用している)。これはそのリージョンをマークするための関数だ。リージョンがマークされることを期待するコマンドのaround-actionフックとして役に立つだろう。たとえばこれはデフォルトでは、S式のターゲットに機能するために`embark-highlight-indicator`が使用しているし、パラグラフのターゲットに機能するために`fill-region`が使用している。

-   **`embark--cd`:** カレントターゲットに関連付けられたディレクトリーを`default-directory`にセットしてアクションを実行する。ターゲットのタイプは`file`、`buffer`、`bookmark`、`library`のいずれかであること。関連付けられたディレクトリーには、それぞれのターゲットにたいしてあなたが期待するディレクトリーをセットする。

-   **`embark--narrow-to-target`:** カレントターゲットにナローイングしたバッファーにアクションを実行する。リージョンに限定した動作をまだ行っていないアクションの影響を局所化するために、around-actionフックとして使用する。デフォルトのコンフィグでは`repunctuate-sentences`に使用されている。

-   **`embark--save-excursion`:** アクションを実行して最後にポイントをリストアする。カレントのデフォルトコンフィグでは使用していないが、ユーザーは利用可能。

## 独自キーマップの設定

<!-- All internal keymaps are defined with the standard helper macro `defvar-keymap`. For example a simple version of the file action keymap could be defined as follows: -->

内部的なキーマップは、すべて標準のヘルパーマクロ`defvar-keymap`で定義されている。たとえばファイル用のアクションキーマップの簡素化バージョンは、以下のように定義できるだろう:

```lisp
    (defvar-keymap embark-file-map
      :doc "ファイル用アクションをいくつか定義したキーマップ例"
      :parent embark-general-map
      "d" #'delete-file
      "r" #'rename-file
      "c" #'copy-file)
```

<!-- These action keymaps are perfectly normal Emacs keymaps.  You may want to inherit from the `embark-general-map` if you want to access the default Embark actions. Note that `embark-collect` and `embark-export` are also made available via `embark-general-map`. -->

これらのアクションキーマップは、正真正銘Emacsの通常のキーマップである。デフォルトのEmbarkアクションにアクセスする場合には、`embark-general-map`から継承したキーマップを使いたいと思うかもしれない。`embark-general-map`経由で`embark-collect`と`embark-export`も利用可能になることに注意。

## ターゲットの新たなカテゴリーにアクションを定義する

<!-- It is easy to configure Embark to provide actions for new types of targets, either in the minibuffer or outside it. I present below two very detailed examples of how to do this. At several points I'll explain more than one way to proceed, typically with the easiest option first. I include the alternative options since there will be similar situations where the easiest option is not available. -->

ミニバッファーあるいはミニバッファー外部の新たなターゲットのタイプにたいして、アクションを提供するようにEmbarkを設定するのは容易だ。これをどのように行うかについて、非常に詳細な例を2つ用意した。いくつかの存在する分岐点には、選べる複数の選択肢についても(簡単な方法順に)説明しようと思っている。似たような状況であっても、もっとも容易なオプションが利用できない場合もあるので、代替えのオプションも含めて説明するつもりだ。

### ミニバッファーの新たなターゲットの例 - tab-barバー

<!-- As an example let us take a look at the [tab bars](https://www.gnu.org/software/emacs/manual/html_node/emacs/Tab-Bars.html). I'll explain how to configure Embark to offer tab-specific actions when you use the tab-bar-mode commands that mention tabs by name. The configuration explained here is now built-in to Embark (and Marginalia), but it's still a good self-contained example. In order to setup up tab actions you would need to: (1) make sure Embark knows those commands deal with tabs, (2) define a keymap for tab actions and configure Embark so it knows that's the keymap you want. -->

例として[tab bars](https://www.gnu.org/software/emacs/manual/html_node/emacs/Tab-Bars.html)を覗いてみよう。名前でタブを指定する`tab-bar-mode`の使用時にはタブ固有のアクションを提案させるために、どのようにEmbarkを設定するかについて説明しよう。ここで説明するコンフィグは今ではEmbark(とMarginalia)に同梱されているが、自己完結型の設定例としての優秀度は以前と変わらない。タブアクションをセットアップするためには: (1) Embarkがタブを扱うコマンドを確かに知っていること、および(2) タブアクション用キーマップの定義、どのキーマップを提案するべきかをEmbarkが理解できるように設定する必要がある。

<!-- 1.  Telling Embark about commands that prompt for tabs by name -->

1.  タブの名前の入力を求めるコマンドをEmbarkに指示する

    <!-- For step (1), it would be great if the `tab-bar-mode` commands reported -->
    <!-- the completion category `tab` when asking you for a tab with -->
    <!-- completion. (All built-in Emacs commands that prompt for file names, -->
    <!-- for example, do have metadata indicating that they want a `file`.) They -->
    <!-- do not, unfortunately, and I will describe a couple of ways to deal -->
    <!-- with this. -->
    
    ステップ(1) 補完付きでタブを尋ねる際に`tab-bar-mode`コマンドが補完カテゴリーとして`tab`を報告してくれたら素晴らしいだろう(たとえばEmacsでファイル名の入力を求めるビルトインコマンドは、コマンドが期待しているのが`file`であることを示すメタデータをもっている)。残念ながらタブの場合は報告してくれないので、これに対処する方法についていくつか説明してみるとしよう。

    <!-- Maybe the easiest thing is to configure [Marginalia](https://github.com/minad/marginalia) -->
    <!-- to enhance those -->
    <!-- commands. All of the `tab-bar-*-tab-by-name` commands have the words -->
    <!-- "tab by name" in the minibuffer prompt, so you can use: -->
    
    これらのタブコマンドをもっとも簡単に強化できるのは、おそらく[Marginalia](https://github.com/minad/marginalia)を設定する方法だろう。`tab-bar-*-tab-by-name`のようなコマンドのミニバッファー用プロンプトには、すべて"tab by name"という単語が含まれているので、以下を使うことができる:

    ```lisp
        (add-to-list 'marginalia-prompt-categories '("tab by name" . tab))
    ```

    <!-- That's it! But in case you are ever in a situation where you don't -->
    <!-- already have commands that prompt for the targets you want, I'll -->
    <!-- describe how writing your own command with appropriate `category` -->
    <!-- metadata looks: -->

    これでOKだ! しかしこの例では、あなたが期待するターゲット用のプロンプトを備えたコマンドが、まだ存在しない状況に対処できるように、適切な`category`のメタデータを使って独自のコマンドを記述する方法について説明しよう:

    ```lisp
        (defun my-select-tab-by-name (tab)
          (interactive
           (list
            (let ((tab-list (or (mapcar (lambda (tab) (cdr (assq 'name tab)))
                                        (tab-bar-tabs))
                                (user-error "No tabs found"))))
              (completing-read
               "Tabs: "
               (lambda (string predicate action)
                 (if (eq action 'metadata)
                     '(metadata (category . tab))
                   (complete-with-action
                    action tab-list string predicate)))))))
          (tab-bar-select-tab-by-name tab))
    ```

    <!-- As you can see, the built-in support for setting the category -->
    <!-- meta-datum is not very easy to use or pretty to look at. To help with -->
    <!-- this I recommend the `consult--read` function from the excellent -->
    <!-- [Consult](https://github.com/minad/consult/) package. With that function we can rewrite the command as -->
    <!-- follows: -->

    ご覧いただいた通りカテゴリーのメタデータをセットするためのビルトインサポートは非常に使いやすいとはいえないし、見た目も可愛くない。これの助勢としてお勧めなのが、[Consult](https://github.com/minad/consult/)という素晴らしいパッケージが提供する`consult--read`関数だ。この関数を使えば、コマンドを以下のように書き直すことができるだろう:

    ```lisp
        (defun my-select-tab-by-name (tab)
          (interactive
           (list
            (let ((tab-list (or (mapcar (lambda (tab) (cdr (assq 'name tab)))
                                        (tab-bar-tabs))
                                (user-error "No tabs found"))))
              (consult--read tab-list
                             :prompt "Tabs: "
                             :category 'tab))))
          (tab-bar-select-tab-by-name tab))
    ```

    <!-- Much nicer! No matter how you define the `my-select-tab-by-name` -->
    <!-- command, the first approach with Marginalia and prompt detection has -->
    <!-- the following advantages: you get the `tab` category for all the -->
    <!-- `tab-bar-*-bar-by-name` commands at once, also, you enhance built-in -->
    <!-- commands, instead of defining new ones. -->

    よくなった! `my-select-tab-by-name`コマンドをどのように定義するかは関係なく、Marginaliaを使った最初のアプローチとプロンプト検出には、一度で`tab-bar-*-bar-by-name`コマンドすべての`tab`カテゴリーを入手でき、その上新たにコマンドを定義するのではなくビルトインコマンドの強化も実現できるというアドバンテージがあるのだ。

<!-- 2.  Defining and configuring a keymap for tab actions -->

2.  タブアクション用キーマップの定義と設定

    <!-- Let's say we want to offer select, rename and close actions for tabs -->
    <!-- (in addition to Embark general actions, such as saving the tab name to -->
    <!-- the kill-ring, which you get for free). Then this will do: -->

    (無料で手に入るkillリングへのタ名の保存のようなEmbarkの一般的なアクションに加えて)タブレットにたいする選択、リネーム、閉じるアクションを提供したいとする。それは以下のようになるだろう:

    ```lisp
        (defvar-keymap embark-tab-actions
          :doc "tab-barのタブ用のアクションのキーマップ(名前でタブ指定の場合)"
          :parent embark-general-map
          "s" #'tab-bar-select-tab-by-name
          "r" #'tab-bar-rename-tab-by-name
          "k" #'tab-bar-close-tab-by-name)
        
        (add-to-list 'embark-keymap-alist '(tab . embark-tab-actions))
    ```

    <!-- What if after using this for a while you feel closing the tab -->
    <!-- without confirmation is dangerous? You have a couple of options: -->
    
    これをしばらく使用した後に、同意の確認なしでタブを閉じるのは危険だと感じたらどうしよう? いくつかオプションが考えられる:

    <!-- 1.  You can keep using the `tab-bar-close-tab-by-name` command, but have -->
    <!--     Embark ask you for confirmation: -->
        
    1.  `tab-bar-close-tab-by-name`コマンドの使用は継続、ただしEmbarkに同意を求めさせる:

        ```lisp
            (push #'embark--confirm
                  (alist-get 'tab-bar-close-tab-by-name
                             embark-pre-action-hooks))
        ```

    <!-- 2.  You can write your own command that prompts for confirmation and -->
    <!--     use that instead of `tab-bar-close-tab-by-name` in the above keymap: -->

    2.  同意を求めるプロンプトをもったコマンドを独自に記述、上記キーマップで`tab-bar-close-tab-by-name`のかわりに使用する:

        ```lisp
            (defun my-confirm-close-tab-by-name (tab)
              (interactive "sTab to close: ")
              (when (y-or-n-p (format "Close tab '%s'? " tab))
                (tab-bar-close-tab-by-name tab)))
        ```

        <!-- Notice that this is a command you can also use directly from `M-x` -->
        <!-- independently of Embark. Using it from `M-x` leaves something to be -->
        <!-- desired, though, since you don't get completion for the tab names. -->
        <!-- You can fix this if you wish as described in the previous section. -->

        これはEmbarkに依存せずに`M-x`から直接使うこともできるコマンドだという点に注目して欲しい。`M-x`から私用した場合にはタブ名の補完が得られないので、幾分物足りなく感じるのではないだろうか。

<!-- You can fix this if you wish as described in the previous section. -->

お望みならこれは前のセクションで説明した通り修正すればよいだろう。

### 通常バッファーにおける新たなターゲットの例 - Wikipediaへのショートリンク

<!-- Say you want to teach Embark to treat text of the form `wikipedia:Garry_Kasparov` in any regular buffer as a link to Wikipedia, with actions to open the Wikipedia page in eww or an external browser or to save the URL of the page in the kill-ring. We can take advantage of the actions that Embark has preconfigured for URLs, so all we need to do is teach Embark that `wikipedia:Garry_Kasparov` stands for the URL `https://en.wikipedia.org/wiki/Garry_Kasparov`. -->

任意の通常バッファーにおいて`wikipedia:Garry_Kasparov`という形式のテキストをWikipediaへのリンクとして扱うこと、このターゲットにはリンク先のWikipediaページをewwや外部ブラウザでオープンしたり、あるいはそのページのURLをkillリングに保存するというアクションが用意されていることをEmbarkに教え込みたいとしよう。EmbarkにはURL用のアクションが事前定義されているというアドバンテージがあるので、わたしたちに必要なのは`wikipedia:Garry_Kasparov`が`https://en.wikipedia.org/wiki/Garry_Kasparov`というURLを意味していることをEmbarkに教え込むだけだ。

<!-- You can be as fancy as you want with the recognized syntax. Here, to keep the example simple, I'll assume the link matches the regexp `wikipedia:[[:alnum:]_]+`. We will write a function that looks for a match surrounding point, and returns a dotted list of the form `'(url URL-OF-THE-PAGE START . END)` where `START` and `END` are the buffer positions bounding the target, and are used by Embark to highlight it if you have `embark-highlight-indicator` included in the list `embark-indicators`. (There are a couple of other options for the return value of a target finder: the bounding positions are optional and a single target finder is allowed to return multiple targets; see the documentation for `embark-target-finders` for details.) -->

認識する必要がある構文次第では、好きなだけ趣向を凝らすことも可能だ。ここでは例をシンプルに保つために、これは`wikipedia:[[:alnum:]_]+`というregexpにマッチするようなリンクだと仮定する。ポイントを取り囲むマッチを探して、`'(url URL-OF-THE-PAGE START . END)`という形式のドットリストをリターンする関数を記述することにしよう。ここでターゲットの境界を示すバッファー位置の`START`および`END`は、(リスト`embark-indicators`に`embark-highlight-indicator`が含まれている場合には)Embarkがハイライトに使用するだろう(ターゲットファインダーのリターン値にたいするオプションは、境界位置はオプション、1つのターゲットファインダーが複数のターゲットをリターン可といったのように他にもいくつか存在する。詳細については`embark-target-finders`のドキュメントを参照のこと)。

```lisp
    (defun my-short-wikipedia-link ()
      "ターゲットはポイント位置にあるwikipedia:Page_Nameおいう形式のリンク"
      (save-excursion
        (let* ((start (progn (skip-chars-backward "[:alnum:]_:") (point)))
               (end (progn (skip-chars-forward "[:alnum:]_:") (point)))
               (str (buffer-substring-no-properties start end)))
          (save-match-data
            (when (string-match "wikipedia:\\([[:alnum:]_]+\\)" str)
              `(url
                ,(format "https://en.wikipedia.org/wiki/%s"
                         (match-string 1 str))
                ,start . ,end))))))
    
    (add-to-list 'embark-target-finders 'my-short-wikipedia-link)
```

# Embarkはどうやってアクションを呼び出すのか?

<!-- Embark actions are normal Emacs commands, that is, functions with an interactive specification. In order to execute an action, Embark calls the command with `call-interactively`, so the command reads user input exactly as if run directly by the user. For example the command may open a minibuffer and read a string (`read-from-minibuffer`) or open a completion interface (`completing-read`). If this happens, Embark takes the target string and inserts it automatically into the minibuffer, simulating user input this way. After inserting the string, Embark exits the minibuffer, submitting the input. (The immediate minibuffer exit can be disabled for specific actions in order to allow editing the input; this is done by adding the `embark--allow-edit` function to the appropriate entry of `embark-target-injection-hooks`). Embark inserts the target string at the first minibuffer opened by the action command, and if the command happens to prompt the user for input more than once, the user still interacts with the second and further prompts in the normal fashion. Note that if a command does not prompt the user for input in the minibuffer, Embark still allows you to use it as an action, but of course, never inserts the target anywhere. (There are plenty of examples in the default configuration of commands that do not prompt the user bound to keys in the action maps, most of the region actions, for instance.) -->

Embarkのアクションとはすなわち普通のEmacsのコマンドである。つまりinteractive仕様をもつ関数のことだ(訳注: interactiveすなわち対話的という意味もあるが、Emacsには本来は対話的ではない関数を対話的にするinteractiveというスペシャルフォームがある)。あるアクションを実行するためには、Embarkがそのコマンドを`call-interactively`で呼び出す必要がある。そうすればコマンドはあたかもユーザーが直接呼び出したかのように、ユーザーの入力を読み取ることができるのだ。たとえばミニバッファーをオープンして文字列読み取ったり(`read-from-minibuffer`)、補完インターフェイスをオープンする(`completing-read`)といったことが可能になる。これが行われるとEmbarkがターゲット文字列を受け取って、ユーザー入力を扱う場合と同じようにそれを自動的にミニバッファーへと挿入する。文字列を挿入した後はEmbarkがミニバッファーを抜けることで入力の完了だ(特定のアクションでは入力の編集を可能にするためにミニバッファーの即時脱出を無効にできる; これは`embark-target-injection-hooks`の適切なエントリーに`embark--allow-edit`関数を追加することで行われる)。Embarkはアクションのコマンドがミニバッファーを最初にオープンしたタイミングでターゲット文字列を挿入する。そのコマンドが2回目のプロンプトでユーザー入力を求めた場合には、2回目以降のプロンプトとも通常のやり方で依然として対話できるだろう。ミニバッファーでユーザーにプロンプトを表示して入力を求めないコマンドでも、そのコマンドのアクションとしての使用をEmbarkが禁ずることはなうが、ターゲットをどこかに挿入することはできなくなる(デフォルト設定のアクションマップにはユーザーにプロンプトで入力を求めないコマンド例が大量に存在するが、それはたとえばほとんどがリージョン用のアクションだ)。

<!-- This is how Embark manages to reuse normal commands as actions. The mechanism allows you to use as Embark actions commands that were not written with Embark in mind (and indeed almost all actions that are bound by default in Embark's action keymaps are standard Emacs commands). It also allows you to write new custom actions in such a way that they are useful even without Embark. -->

これがEmbarkが普通のコマンドをアクションとして管理する方法である。このメカニズムによってEmbarkを念頭に記述された訳ではないコマンドでも、Embarkのアクションコマンドとして使用することが可能なのだ(そして確かにEmbarkのアクションキーマップでデフォルトでバインドされているほとんどのアクションは、Emacsの標準コマンドである)。これは更にEmbark抜きでも役に立つような方法による、新たなカスタムアクションの記述の後押しにもなると思う。

<!-- Emacs has a variable `y-or-n-p-use-read-key`, which when set to `t` causes `y-or-n-p` to use `read-key` instead of `read-from-minibuffer`. Setting `y-or-n-p-use-read-key` to `t` is recommended for Embark users because it keeps Embark from attempting to insert the target at a `y-or-n-p` prompt, which would almost never be sensible. Also consider this as a warning to structure your own action commands so that if they use `y-or-n-p`, they do so only after the prompting for the target. -->

Emacsには`y-or-n-p-use-read-key`という変数がある。これが`t`にセットされていると、`y-or-n-p`は`read-from-minibuffer`のかわりに`read-key`を使用するのだ。Embarkユーザーには`y-or-n-p-use-read-key`を`t`にセットするようお勧めする。`y-or-n-p`のプロンプトにたいしてターゲットを挿入する動作をEmbarkに強いてもほとんど意味がないからだ。これは独自にアクションコマンドを構築する場合の教訓と考えることもできるだろう。そのコマンドが`y-or-n-p`を使用させるのは、ターゲットにプロンプトを使わせた後だけにしよう。

<!-- Here is a simple example illustrating the various ways of reading input from the user mentioned above. Bind the following commands to the `embark-symbol-map` to be used as actions, then put the point on some symbol and run them with `embark-act`: -->

上述したユーザーからの入力を読み取るさまざまな例を説明するためのシンプルな例を用意した。アクションとして使用できるように以下のコマンドを`embark-symbol-map`にバインドしてから、何かシンボルにポイントを置いて`embark-act`を実行してみて欲しい:


```lisp
    (defun example-action-command1 ()
      (interactive)
      (message "入力は `%s'." (read-from-minibuffer "Input: ")))
    
    (defun example-action-command2 (arg input1 input2)
      (interactive "P\nsInput 1: \nsInput 2: ")
      (message "1つ目の入力は %swas `%s'、2つ目は `%s'."
               (if arg "ガチで " "")
               input1
               input2))
    
    (defun example-action-command3 ()
      (interactive)
      (message "あなたの選択は `%s'."
               (completing-read "Select: " '("E" "M" "B" "A" "R" "K"))))
    
    (defun example-action-command4 ()
      (interactive)
      (message "入力のプロンプト出してない故にターゲット無視!"))
    
    (keymap-set embark-symbol-map "X 1" #'example-action-command1)
    (keymap-set embark-symbol-map "X 2" #'example-action-command2)
    (keymap-set embark-symbol-map "X 3" #'example-action-command3)
    (keymap-set embark-symbol-map "X 4" #'example-action-command4)
```

<!-- Also note that if you are using the key bindings to call actions, you can pass prefix arguments to actions in the normal way. For example, you can use `C-u X2` with the above demonstration actions to make the message printed by `example-action-command2` more emphatic. This ability to pass prefix arguments to actions is useful for some actions in the default configuration, such as `embark-shell-command-on-buffer`. -->

アクションの呼び出しにキーバインディングを使い場合には、通常の方法でアクションにプレフィックス引数を渡せることにも注意して欲しい。たとえば上記の`example-action-command2`は`C-u X2`と呼び出せばより強調されたメッセージをプリントするアクションをデモンストレーションしている。アクションにプレフィックス引数を渡せる能力は、デフォルトの設定にある`embark-shell-command-on-buffer`.のような一部のアクションにとって役に立つだろう。

## 非interactiveな関数からアクションへ

<!-- Alternatively, Embark does support one other type of action: a non-interactive function of a single argument. The target is passed as argument to the function. For example: -->

Embarkがサポートしているアクションのタイプはもう1つある。1つの引数を受け取る非interactiveな関数だ。ターゲットは関数に引数として渡される。たとえば:

```lisp
    (defun example-action-function (target)
      (message "The target was `%s'." target))
    
    (keymap-set embark-symbol-map "X 4" #'example-action-function)
```

<!-- Note that normally binding non-interactive functions in a keymap is useless, since when attempting to run them using the key binding you get an error message similar to "Wrong type argument: commandp, example-action-function". In general it is more flexible to write any new Embark actions as commands, that is, as interactive functions, because that way you can also run them directly, without Embark. But there are a couple of reasons to use non-interactive functions as actions: -->

通常だとキーマップで非インタラクティブな関数をバインドしても、実行しようとしても"Wrong type argument: commandp, example-action-function"というエラーメッセージが表示されるだけで使い物にならないことに注意。一般的に新たに何かEmbarkアクションを記述する場合にはコマンド、つまりinteractiveな関数として記述する方がより柔軟性がある。これならEmbarkを介さずに直接実行することもできるからだ。しかし非interactiveな関数をアクションとして使用するのにもいくつか利点があるのだ:

<!-- 1.  You may already have the function lying around, and it is convenient to simply reuse it. -->
<!-- 2.  For command actions the targets can only be simple string, with no text properties. For certain advanced uses you may want the action to receive a string *with* some text properties, or even a non-string target. -->

1.  関数ならその辺に常に転がっているし、単にそれを再利用する方が簡単なので

2.  コマンドのアクションのターゲットはテキストプロパティがないシンプルな文字列だけだが、*テキストプロパティをもった文字列*、何なら文字列以外のターゲットを受け取るようなアクションが欲しいという具体的で技術的な理由のため


# Embark、MarginaliaとConsult

<!-- Embark cooperates well with the [Marginalia](https://github.com/minad/marginalia) and [Consult](https://github.com/minad/consult) packages. Neither of those packages is a dependency of Embark, but both are highly recommended companions to Embark, for opposite reasons: Marginalia greatly enhances Embark's usefulness, while Embark can help enhance Consult. -->

Embarkが[Marginalia](https://github.com/minad/marginalia)、[Consult](https://github.com/minad/consult)の2つのパッケージと相性よく協力して動作する。Embarkはいずれのパッケージにたいしても依存関係をもっていない。むしろいずれのパッケージも連れ沿いとして強く推奨するべきパッケージである。EmbarkはConsultの強化の助けとなり、MarginaliaはEmbarkの有用性を飛躍的に向上させるだろう。

<!-- In the remainder of this section I'll explain what exactly Marginalia does for Embark, and what Embark can do for Consult. -->

このセクションの残りの部分でMarginaliaが正確には何をEmbarkにしてくれるのか、そしてEmbarkがConsultにできることを説明しよう。

## Marginalia

<!-- Embark comes with actions for symbols (commands, functions, variables with actions such as finding the definition, looking up the documentation, evaluating, etc.) in the `embark-symbol-map` keymap, and for packages (actions like install, delete, browse url, etc.) in the `embark-package-keymap`. -->

Embarkにはシンボルのための`embark-symbol-map`(コマンド、関数、変数にたいして定義検索、ドキュメント照会、評価等を行うアクション)、パッケージ用には`embark-package-keymap`(インストール、削除、URL閲覧等を行うアクション)というキーマップが同梱されている。

<!-- Unfortunately Embark does not automatically offers you these keymaps when relevant, because many built-in Emacs commands don't report accurate category metadata. For example, a command like `describe-package`, which reads a package name from the minibuffer, does not have metadata indicating this fact.  -->

これらのキーマップに関係のあるアクションであっても、残念ながらEmbarkがそれらを自動的に提案することはない。これはEmacsのビルトインコマンドの多くが正確なカテゴリーのメタデータを報告しないからだ。たとえばミニバッファーからパッケージの名前を読み取る`describe-package`のようなコマンドは、この事実を示すようなメタデータをもっていない。

<!-- In an earlier Embark version, there were functions to supply this missing metadata, but they have been moved to Marginalia, which augments many Emacs command to report accurate category metadata. Simply activating `marginalia-mode` allows Embark to offer you the package and symbol actions when appropriate again. Candidate annotations in the Embark collect buffer are also provided by the Marginalia package: -->

この欠落したメタデータを提供する関数はEmbarkの古いバージョンには存在したが、これらはMarginaliaに移動された。Emacsの多くのコマンドが正確なカテゴリーメタデータを報告するように強化するのがMarginaliaだ。単に`marginalia-mode`をアクティブにするだけで、前のようにシンボルやパッケージにたいするアクションを適切なときにEmbarkが提案できるようにしてくれる。Marginaliaパッケージは他にもEmbarkのCollectバッファーの候補用に注釈も提供する。

<!-- -   If you install Marginalia and activate `marginalia-mode`, Embark Collect buffers will use the Marginalia annotations automatically. -->
<!-- -   If you don't install Marginalia, you will see only the annotations that come with Emacs (such as key bindings in `M-x`, or the unicode characters in `C-x 8 RET`). -->

-   Marginaliaをインストールして`marginalia-mode`をアクティブにすれば、EmbarkのCollectバッファーが自動的にMarginaliaの注釈を使用する

-   Marginaliaをインストールしないで目にできるのはEmacsに同梱の注釈だけ(`M-x`のキーバインディングや`C-x 8 RET`のUnicode文字とか

## Consult

<!-- The excellent Consult package provides many commands that use minibuffer completion, via the `completing-read` function; plenty of its commands can be considered enhanced versions of built-in Emacs commands, and some are completely new functionality. One common enhancement provided in all commands for which it makes sense is preview functionality, for example `consult-buffer` will show you a quick preview of a buffer before you actually switch to it. -->

Consultは`completing-read`関数を介してミニバッファーで使用できる多くのコマンドを提供する素晴らしいパッケージだ。提供するコマンドの大部分はEmacsのビルトインコマンドの強化されたバージョンであり、一部のコマンドはまったく新しい機能をもっている。すべてのコマンドが提供する一般的な強化機能としてはプレビューという納得の機能が挙げられるだろう。たとえば`consult-buffer`は実際に切り替える前にバッファーのクイックプレビューを表示してくれるのだ。

<!-- If you use both Consult and Embark you should install the `embark-consult` package which provides integration between the two. It provides exporters for several Consult commands and also tweaks the behavior of many Consult commands when used as actions with `embark-act` in subtle ways that you may not even notice, but make for a smoother experience. You need only install it to get these benefits: Embark will automatically load it after Consult if found. -->

ConsultとEmbarkの両方を使うのであれば、両者間を統合する`embark-consult`をインストールしよう。これはいくつかのConsultコマンドをエクスポートするエクスポーター、そしてアクションとして`embark-act`を使用した際のスムーズなエクスペリエンスのために多くのConsultコマンドの振る舞いの(気づけさえしないような)微調整も提供してくれるのだ。これらのご利益は得るために必要なのはインストールだけである。Consultを見つけたらEmbarkが自動的にロードを行う。

<!-- The `embark-consult` package provides the following exporters: -->

`embark-consult`によって提供されるエクスポーターは以下の通り:

<!-- -   You can use `embark-export` from `consult-line`, `consult-outline`, or `consult-mark` to obtain an `occur-mode` buffer. As with the built-in `occur` command you use that buffer to jump to a match and after that, you can then use `next-error` and `previous-error` to navigate to other matches. You can also press `e` to activate `occur-edit-mode` and edit the matches in place! -->
<!-- -   You can export from any of the Consult asynchronous search commands, `consult-grep`, `consult-git-grep`, or `consult-ripgrep` to get a `grep-mode` buffer. Here too you can use `next-error` and `previous-error` to navigate among matches, and, if you install the [wgrep](http://github.com/mhayashi1120/Emacs-wgrep/raw/master/wgrep.el ) package, you can use it to edit the matches in place. -->

-   `consult-line`、`consult-outline`、`consult-mark`から`occur-mode`のバッファーを得るための`embark-export`
    ビルトインの`occur`コマンドのバッファーで行うようにマッチにジャンプしたら、その後は`next-error`と`previous-error`で他のマッチに移動できるだろう。`e`を押下して`occur-edit-mode`をアクティブにすれば、その場でマッチの編集も可能なのだ!

-   Consultの`consult-grep`、`consult-git-grep`、`consult-ripgrep`といった非同期検索のコマンドいずれからでも`grep-mode`バッファーにエクスポートできる
    ここでも`next-error`と`previous-error`でマッチの間を移動できるのは同じだ。更にもし[wgrep](http://github.com/mhayashi1120/Emacs-wgrep/raw/master/wgrep.el)パッケージをインストールしてあれば、その場でマッチを編集できるだろう

<!-- In both cases, pressing `g` will rerun the Consult command you had exported from and re-enter the input you had typed (which is similar to reverting but a little more flexible). You can then proceed to re-export if that's what you want, but you can also edit the input changing the search terms or simply cancel if you see you are done with that search. -->

どちらも`g`を押下すれば元のエクスポートしたConsultコマンドに戻って、再度入力を行うことができる(revertと似ているがこちらの方がより柔軟だ)。もしお望みなら再度エクスポートすることもできるが、入力を編集して検索する言葉を変更したり、その検索で満足したら単にキャンセルすればよいだろう。


<!-- The `embark-consult` also contains some candidates collectors that allow you to run `embark-live` to get a live-updating table of contents for your buffer: -->

`embark-consult`には候補コレクター(candidate collector)もいくつか含まれている。候補コレクターを使えばバッファーのコンテンツのライブアップデートを得ることができるのだ。

<!-- -   `embark-consult-outline-candidates` produces the outline headings of the current buffer, using `consult-outline`. -->
<!-- -   `embark-consult-imenu-candidates` produces the imenu items of the current buffer, using `consult-imenu`. -->
<!-- -   `embark-consult-imenu-or-outline-candidates` is a simple combination of the two previous functions: it produces imenu items in buffers deriving from `prog-mode` and otherwise outline headings. -->

-   `embark-consult-outline-candidates`は`consult-outline`を使用してバッファーコンテンツのアウトラインヘッダーを生成する

-   `embark-consult-imenu-candidates`は`consult-imenu`を使用してConsultバッファーのimenuアイテムを生成する

-   上記の2つの関数をシンプルに組み合わせたのが`embark-consult-imenu-or-outline-candidates`で、`prog-mode`から派生したバッファーならimenuアイテム、それ以外のバッファーにたいしてはアウトラインのヘッダーを生成する

<!-- The way to configure `embark-live` (or `embark-collect` and `embark-export` for that matter) to use one of these function is to add it at the end of the `embark-candidate-collectors` list. The `embark-consult` package by default adds the last one, which seems to be the most sensible default. -->

これらの関数を`embark-live`(あるいは`embark-collect`や`embark-export`の場合でも)で使用するには、`embark-candidate-collectors`リストの最後に関数を追加すればよい。`embark-consult`パッケージははデフォルトでは、最後に追加したものがもっとも賢明なデフォルトとみなされるからだ。

<!-- Besides those exporters and candidate collectors, the `embark-consult` package provides many subtle tweaks and small integrations between Embark and Consult. Some examples are: -->

これらのエクスポーターや候補コレクター以外にも`embark-consult`パッケージではEmbarkとConsultの間の精密な微調整、小さな統合がたくさん提供されている。いくつか例を挙げておこう:

<!-- -   When used as actions, the asynchronous search commands will search only the files associated to the targets: if the targets *are* files, it searches those files; for buffers it will search either the associated file if there is one, else all files in the buffer's `default-directory`; for bookmarks it will search the file they point to, same for Emacs Lisp libraries. This is particularly powerful when using `embark-act-all` to act on multiple files at once, for example you can use `consult-find` to search among file *names* and then `embark-act-all` and `consult-grep` to search within the matching files. -->
<!--     -   For all other target types, those that do not have a sensible notion of associated file, a Consult search command (asynchronous or not) will search for the text of the target but leave the minibuffer open so you can interact with the Consult command. -->
<!-- -   `consult-imenu` will search for the target and take you directly to the location if it matches a unique imenu entry, otherwise it will leave the minibuffer open so you can navigate among the matches. -->

-   非同期検索をアクションとして使用した場合には、ターゲットに関連のあるファイルだけを検索する:

    *ターゲット*がファイルならそれらのファイル、バッファーの場合にはバッファーに割り当てられたファイルがあればファイルから、なければそのバッファーの`default-directory`にあるすべてのファイルから、ブックマークならリンクが指すファイルから検索する(Emacs Lispライブラリーにたいしても同様)

    これはたとえば`consult-find`で*names*という名前のファイルを検索、`embark-act-all`で`consult-grep`すればマッチしたファイルを検索といったように、`embark-act-all`で一度に複数のファイルにアクションする際には特に強力な機能だ

-   関連付けられたファイルがない、あるいは取り扱う際のセオリーが存在しないその他のターゲットについては、(非同期かどうかに関係なく)ターゲットのテキストをConsultは検索するが、Consultコマンドと対話できるようにミニバッファーをオープンしたままにしておく

-   `consult-imenu`はターゲットを検索して一意なimenuエントリーにマッチしたら直接その場所に移動、そのようなエントリーがなければマッチ間を行き来できるようにミニバッファーをオープンしたままにしておく

# 関連パッケージ

<!-- There are several packages that offer functionality similar to Embark's.  -->

Embarkに似た機能を提供するパッケージもいくつか存在する。

<!-- -   **Acting on minibuffer completion candidates:** The popular Ivy and Helm packages have support for acting on the completion candidates of commands written using their APIs, and there is an extensive ecosystem of packages meant for Helm and for Ivy (the Ivy ones usually have "counsel" in the name) providing commands and appropriate actions. -->
<!-- -   **Acting on things at point:** The built-in `context-menu-mode` provides a mouse-driven context-sensitive configurable menu. The `do-at-point` package by Philip Kaludercic (available on GNU ELPA), on the other hand is keyboard-driven. -->
<!-- -   **Collecting completion candidates into a buffer:** The Ivy package has the command `ivy-occur` which is similar to `embark-collect`. As with Ivy actions, `ivy-occur` only works for commands written using the Ivy API. -->

-   **ミニバッファーの補完候補にアクション:** 有名なIvyとHelmというパッケージでも補完候補にアクションするコマンド(それぞれ独自のAPIで記述されている)がサポートされており、HelmやIvyを意識したパッケージ(Ivy用は普通は名前に"counsel"がある)からなる大規模なエコシステムがコマンドや相応のアクションを提供している

-   **ポイント位置にアクション:** ビルトインの`context-menu-mode`がマウス駆動で文脈依存、コンフィグ可能なメニューを提供しているし、キーボード駆動方式ならPhilip Kaludercic氏が提供する`do-at-point`パッケージがある(GNU ELPAで入手可)

-   **補完候補をバッファーに収集:** IvyにはIvyのAPIで記述された`ivy-occur`という`embark-collect`と似たコマンドがある

# リソース

<!-- If you want to learn more about how others have used Embark here are some links to read: -->

他の人たちがどのようにEmbarkを使っているか興味のある人のために、目を通すべきリンクをいくつか挙げておこう

<!-- -   [Fifteen ways to use Embark](https://karthinks.com/software/fifteen-ways-to-use-embark/), a blog post by Karthik Chikmagalur. -->
<!-- -   [Protesilaos Stavrou's dotemacs](https://protesilaos.com/dotemacs/), look for the section called "Extended minibuffer actions and more (embark.el and prot-embark.el)" -->

-   [Fifteen ways to use Embark](https://karthinks.com/software/fifteen-ways-to-use-embark/): Karthik Chikmagalur氏によるブログ投稿だ

-   [Protesilaos Stavrou氏のdotemacs](https://protesilaos.com/dotemacs/): "Extended minibuffer actions and more (embark.el and prot-embark.el)"というセクションを調べてみよう

<!-- And some videos to watch: -->

お勧めのビデオもいくつかある:

<!-- -   [Embark and my extras](https://protesilaos.com/codelog/2021-01-09-emacs-embark-extras/) by Protesilaos Stavrou. -->

<!-- -   [Embark &#x2013; Key features and tweaks](https://youtu.be/qpoQiiinCtY) by Raoul Comninos on the Emacs-Elements YouTube channel. -->
<!-- -   [Livestreamed: Adding an Embark context action to send a stream -->
<!--     message](https://youtu.be/WsxXr1ncukY) by Sacha Chua. -->
<!-- -   [System Crafters Live! - The Many Uses of Embark](https://youtu.be/qk2Is_sC8Lk) by David Wilson. -->
<!-- -   [Using Emacs Episode 80 - Vertico, Marginalia, Consult and Embark](https://youtu.be/5ffb2at2d7w) by -->
<!--     Mike Zamansky. -->


-   [Embark and my extras](https://protesilaos.com/codelog/2021-01-09-emacs-embark-extras/): Protesilaos Stavrou氏による

-   [Embark &#x2013; Key features and tweaks](https://youtu.be/qpoQiiinCtY): Raoul Comninos氏のYouTubeチャンネルEmacs-Elements

-   [Livestreamed: Adding an Embark context action to send a stream message](https://youtu.be/WsxXr1ncukY): Sacha Chua氏による
    
-   [System Crafters Live! - The Many Uses of Embark](https://youtu.be/qk2Is_sC8Lk): David Wilson氏による

-   [Using Emacs Episode 80 - Vertico, Marginalia, Consult and Embark](https://youtu.be/5ffb2at2d7w): Mike Zamansky氏による

# 貢献してくれる人たちへ

<!-- Contributions to Embark are very welcome. There is a [wish list](https://github.com/oantolin/embark/issues/95) for actions, target finders, candidate collectors and exporters. For other ideas you have for Embark, feel free to open an issue on the [issue tracker](https://github.com/oantolin/embark/issues). Any neat configuration tricks you find might be a good fit for the [wiki](https://github.com/oantolin/embark/wiki). -->

Embarkに貢献してくれる人は大歓迎だ。アクション、ターゲット、ファインダー、候補コレクター、エクスポーター用の[wish list](https://github.com/oantolin/embark/issues/95)がある。Embarkについて他にもアイデアがあれば、遠慮なく[issue tracker](https://github.com/oantolin/embark/issues)でissueをオープンしていただきたい。何かイカしたコンフィグのテクニックを提供する場としては、[wiki](https://github.com/oantolin/embark/wiki)がピッタリだろう。

<!-- Code contributions are very welcome too, but since Embark is now on GNU ELPA, copyright assignment to the FSF is required before you can contribute code. -->

コードへの貢献も大歓迎だがEmbarkは現在GNU ELPAに所属しているので、コードを貢献する前にFSFへの著作権譲渡が必要になるだろう。

# 謝辞

<!-- While I, Omar Antolín Camarena, have written most of the Embark code and remain very stubborn about some of the design decisions, Embark has received substantial help from a number of other people which this document has neglected to mention for far too long. In particular, Daniel Mendler has been absolutely invaluable, implementing several important features, and providing a lot of useful advice. -->


Embarkのコードのほとんどを記述し、かつ一部のデザイン上の決定に頑迷に拘り続けているのはわたくし、Omar Antolín Camarenaだが、他の人たちからの実のある助言について、わたしはあまりに長い間この文書に記すのを怠っていた。特にDaniel Mendlerは重要ないくつかの機能の実装、大量の有益なアイデアの価値は計り知れない。

コードに貢献してくれた人たち:

-   [Daniel Mendler](https://github.com/minad)
-   [Clemens Radermacher](https://github.com/clemera/)
-   [José Antonio Ortega Ruiz](https://codeberg.org/jao/)
-   [Itai Y. Efrat](https://github.com/iyefrat)
-   [a13](https://github.com/a13)
-   [jakanakaevangeli](https://github.com/jakanakaevangeli)
-   [mihakam](https://github.com/mihakam)
-   [Brian Leung](https://github.com/leungbk)
-   [Karthik Chikmagalur](https://github.com/karthink)
-   [Roshan Shariff](https://github.com/roshanshariff)
-   [condy0919](https://github.com/condy0919)
-   [Damien Cassou](https://github.com/DamienCassou)
-   [JimDBh](https://github.com/JimDBh)

アドバイスや有益な議論で貢献してくれた人たち:

-   [Daniel Mendler](https://github.com/minad)
-   [Protesilaos Stavrou](https://gitlab.com/protesilaos/)
-   [Clemens Radermacher](https://github.com/clemera/)
-   [Howard Melman](https://github.com/hmelman/)
-   [Augusto Stoffel](https://github.com/astoff)
-   [Bruce d'Arcus](https://github.com/bdarcus)
-   [JD Smith](https://github.com/jdtsmith)
-   [Karthik Chikmagalur](https://github.com/karthink)
-   [jakanakaevangeli](https://github.com/jakanakaevangeli)
-   [Itai Y. Efrat](https://github.com/iyefrat)
-   [Mohsin Kaleem](https://github.com/mohkale)