[elpa] externals/marginalia d400032 228/241: README: Document lightweight annotator usage

[Stefan Monnier]

branch: externals/marginalia
commit d4000325a18467fe0900be78883c363c2b43219b
Author: Daniel Mendler <mail@daniel-mendler.de>
Commit: Daniel Mendler <mail@daniel-mendler.de>

    README: Document lightweight annotator usage
---
 README.org      | 28 ++++++++++++++++++++++++++++
 marginalia.texi | 45 +++++++++++++++++++++++++++++++++------------
 2 files changed, 61 insertions(+), 12 deletions(-)

diff --git a/README.org b/README.org
index 20fad3f..855c287 100644
--- a/README.org
+++ b/README.org
@@ -63,6 +63,34 @@ commands.
   (marginalia-mode))
 #+end_src
 
+* Using builtin or lightweight annotators
+
+Marginalia activates visually heavy annotators by default. Depending on your
+preference you may want to use the builtin annotators or even no annotators by
+default and only activate the annotators on demand by invoking
+~marginalia-cycle~.
+
+In order to use the builtin annotators by default, you can use the following
+snippet. Replace =builtin= by =none= to disable annotators by default.
+
+#+begin_src emacs-lisp
+  (mapc
+   (lambda (x) (setcdr x (cons 'builtin (delete 'builtin (cdr x)))))
+   marginalia-annotator-registry)
+#+end_src
+
+After having cycled the annotators you may want to automatically save the
+annotator configuration. This can be achieved using an advice which calls
+~customize-save-variable~:
+
+#+begin_src emacs-lisp
+  (advice-add #'marginalia-cycle :after
+              (lambda ()
+                (let ((inhibit-message t))
+                  (customize-save-variable 'marginalia-annotator-registry
+                                           marginalia-annotator-registry))))
+#+end_src
+
 * Contributions
 
 Since it is planned to submit this package to GNU ELPA, contributions require a
diff --git a/marginalia.texi b/marginalia.texi
index a80c9fc..da79e06 100644
--- a/marginalia.texi
+++ b/marginalia.texi
@@ -27,6 +27,7 @@
 @menu
 * Introduction::
 * Configuration::
+* Using builtin or lightweight annotators::
 * Contributions::
 @end menu
 
@@ -45,9 +46,8 @@ the original commands.
 
 The annotations are added based on the completion category. For example
 @samp{find-file} reports the @samp{file} category and @samp{M-x} reports the 
@samp{command}
-category. You can choose between more or less detailed annotators, by
-setting the variable @samp{marginalia-annotators} or by invoking the command
-@samp{marginalia-cycle}.
+category. You can cycle between more or less detailed annotators with the
+command @samp{marginalia-cycle}.
 
 Since many commands do not report a completion category themselves,
 Marginalia provides a classifier system, which tries to guess the
@@ -80,15 +80,36 @@ commands.
 
   ;; Must be in the :init section of use-package such that the mode gets
   ;; enabled right away. Note that this forces loading the package.
-  (marginalia-mode)
-
-  ;; Prefer richer, more heavy, annotations over the lighter default variant.
-  ;; E.g. M-x will show the documentation string additional to the keybinding.
-  ;; By default only the keybinding is shown as annotation.
-  ;; Note that there is the command `marginalia-cycle' to
-  ;; switch between the annotators.
-  ;; (setq marginalia-annotators '(marginalia-annotators-heavy 
marginalia-annotators-light nil))
-)
+  (marginalia-mode))
+@end lisp
+
+@node Using builtin or lightweight annotators
+@chapter Using builtin or lightweight annotators
+
+Marginalia activates visually heavy annotators by default. Depending on your
+preference you may want to use the builtin annotators or even no annotators by
+default and only activate the annotators on demand by invoking
+@code{marginalia-cycle}.
+
+In order to use the builtin annotators by default, you can use the following
+snippet. Replace @samp{builtin} by @samp{none} to disable annotators by 
default.
+
+@lisp
+(mapc
+ (lambda (x) (setcdr x (cons 'builtin (delete 'builtin (cdr x)))))
+ marginalia-annotator-registry)
+@end lisp
+
+After having cycled the annotators you may want to automatically save the
+annotator configuration. This can be achieved using an advice which calls
+@code{customize-save-variable}:
+
+@lisp
+(advice-add #'marginalia-cycle :after
+            (lambda ()
+              (let ((inhibit-message t))
+                (customize-save-variable 'marginalia-annotator-registry
+                                         marginalia-annotator-registry))))
 @end lisp
 
 @node Contributions