branch: elpa/projectile
commit 2ca225a7934d88116d8e76d3fc45803a8ff3360e
Author: Bozhidar Batsov <[email protected]>
Commit: Bozhidar Batsov <[email protected]>
Recommend Marginalia in the docs
The completion categories Projectile advertises exist so that packages
like Marginalia can do something with them, but the manual never
actually suggested installing it - it only name-dropped it in a list of
things that happen to work.
Add a short "recommended setup" section (vertico + marginalia +
orderless) with a before/after shot of `projectile-find-file', and point
the getting-started tip and the usage section at it.
---
.../ROOT/assets/images/projectile-marginalia.png | Bin 0 -> 196282 bytes
doc/modules/ROOT/pages/configuration.adoc | 53 +++++++++++++++++----
doc/modules/ROOT/pages/getting_started.adoc | 7 ++-
doc/modules/ROOT/pages/usage.adoc | 16 +++++--
4 files changed, 61 insertions(+), 15 deletions(-)
diff --git a/doc/modules/ROOT/assets/images/projectile-marginalia.png
b/doc/modules/ROOT/assets/images/projectile-marginalia.png
new file mode 100644
index 0000000000..ba1dc5f99c
Binary files /dev/null and
b/doc/modules/ROOT/assets/images/projectile-marginalia.png differ
diff --git a/doc/modules/ROOT/pages/configuration.adoc
b/doc/modules/ROOT/pages/configuration.adoc
index fa64ebf778..adf77cf95a 100644
--- a/doc/modules/ROOT/pages/configuration.adoc
+++ b/doc/modules/ROOT/pages/configuration.adoc
@@ -198,14 +198,48 @@ in particular should read the
xref:upgrading_to_projectile_3.adoc#ido-users[upgrade guide], which covers
`ido-completing-read+`.
-=== Embark and Marginalia
+[#recommended-completion-stack]
+=== A recommended setup
-Projectile ships a small integration layer for
-https://github.com/oantolin/embark[Embark] and
-https://github.com/minad/marginalia[Marginalia]. It's wired with
-`with-eval-after-load`, so neither package becomes a dependency - if you don't
-have them installed, nothing happens; if you do, it activates on its own with
no
-configuration.
+Nothing below is required, but this is the combination that gets the most out
of
+Projectile's completion metadata, and it's what the screenshots in this manual
+were taken with:
+
+[source,elisp]
+----
+(use-package vertico ; a vertical completion UI
+ :ensure t
+ :init (vertico-mode +1))
+
+(use-package marginalia ; annotations next to each candidate
+ :ensure t
+ :init (marginalia-mode +1))
+
+(use-package orderless ; space-separated, order-independent matching
+ :ensure t
+ :init (setq completion-styles '(orderless basic)))
+----
+
+https://github.com/minad/marginalia[Marginalia] is the one worth calling out,
+because Projectile does real work to make it useful. Every Projectile prompt
+tags its candidates with a completion category, and Marginalia keys off that
+category to decide what to show: file size, permissions and modification time
at
+`projectile-find-file`, buffer sizes and major modes at
+`projectile-switch-to-buffer`, and so on. The same prompt without Marginalia
+(top) and with it (bottom):
+
+image::projectile-marginalia.png[projectile-find-file without and with
Marginalia annotations]
+
+Picking a file by its size or by how recently you touched it, without leaving
+the prompt, turns out to be a much bigger deal in day-to-day use than it
sounds.
+
+=== Embark actions
+
+Projectile also ships a small integration layer for
+https://github.com/oantolin/embark[Embark]. Like the Marginalia support, it's
+wired with `with-eval-after-load`, so neither package becomes a dependency - if
+you don't have them installed, nothing happens; if you do, it activates on its
+own with no configuration.
Two things come out of it. First, `embark-act` on a file candidate targets the
right file. Projectile presents its file candidates relative to the project
@@ -244,9 +278,8 @@ any other keymap:
(define-key projectile-embark-project-map (kbd "b") #'projectile-ibuffer))
----
-Marginalia annotates the project candidates with its built-in file annotator,
-since they're just directory paths - so they look the same as they did before
-the category change.
+Project candidates keep their Marginalia annotations under the new category -
+they're directory paths, so Marginalia's file annotator handles them.
=== Custom completion function
diff --git a/doc/modules/ROOT/pages/getting_started.adoc
b/doc/modules/ROOT/pages/getting_started.adoc
index 0829aed5c4..6f51525e3c 100644
--- a/doc/modules/ROOT/pages/getting_started.adoc
+++ b/doc/modules/ROOT/pages/getting_started.adoc
@@ -21,8 +21,11 @@ NOTE: The rest of this manual writes keybindings as `s-p
...`; just substitute
whatever prefix you picked above.
TIP: Pair Projectile with a modern completion UI such as
-https://github.com/minad/vertico[Vertico] for a much nicer experience at every
-prompt. See xref:configuration.adoc#completion-options[Completion options].
+https://github.com/minad/vertico[Vertico], plus
+https://github.com/minad/marginalia[Marginalia] for annotations (file sizes,
+modification times, major modes) next to each candidate. It's a much nicer
+experience at every prompt. See
+xref:configuration.adoc#recommended-completion-stack[A recommended setup].
== Open a project
diff --git a/doc/modules/ROOT/pages/usage.adoc
b/doc/modules/ROOT/pages/usage.adoc
index 37a3c7420f..bcaf99ac1f 100644
--- a/doc/modules/ROOT/pages/usage.adoc
+++ b/doc/modules/ROOT/pages/usage.adoc
@@ -74,6 +74,14 @@ Here's how a typical Projectile configuration would look:
:init
(vertico-mode +1))
+;; Optional: marginalia annotates the completion candidates - file sizes and
+;; modification times at `projectile-find-file', major modes at
+;; `projectile-switch-to-buffer', and so on.
+(use-package marginalia
+ :ensure t
+ :init
+ (marginalia-mode +1))
+
;; Optional: which-key will show you options for partially completed
keybindings
;; It's extremely useful for packages with many keybindings like Projectile.
(use-package which-key
@@ -158,9 +166,11 @@ a prefix argument it also removes projects nested deeper
in the tree.
Projectile reads through Emacs's built-in `completing-read`, so it works with
whatever minibuffer UI you use. It works fine with the stock completion, but
you're encouraged to pair it with a modern package like `vertico` (+ `consult`,
-`marginalia`, `orderless`) or `fido-mode`/`fido-vertical-mode`. See the
-xref:configuration.adoc#completion-options[Completion Options] section for
-details, including how to plug in a custom completion function.
+`marginalia`, `orderless`) or `fido-mode`/`fido-vertical-mode`. See
+xref:configuration.adoc#recommended-completion-stack[A recommended setup] for
+the combination this manual assumes, and the surrounding
+xref:configuration.adoc#completion-options[Completion Options] section for the
+rest, including how to plug in a custom completion function.
=== Installing external tools
