[elpa] externals/embark ebf12d9a66 2/2: Document embark-live and live-updating TOC (fix #407)

[ELPA Syncer]

branch: externals/embark
commit ebf12d9a665a2e7ac6d3651024508e5a8aa4302b
Author: Omar Antolín <omar.antolin@gmail.com>
Commit: Omar Antolín <omar.antolin@gmail.com>

    Document embark-live and live-updating TOC (fix #407)
---
 README.org  | 54 ++++++++++++++++++++++++++++++++++++++++++------
 embark.texi | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++++------
 2 files changed, 110 insertions(+), 12 deletions(-)

diff --git a/README.org b/README.org
index d3857380ee..4bb2fd8554 100644
--- a/README.org
+++ b/README.org
@@ -201,6 +201,30 @@ 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-live= a live-updating variant of =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,
+Selectrum, 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!
+
+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.
+
 ** Switching to a different command without losing what you've typed
 
 Embark also has the =embark-become= command which is useful for when
@@ -959,12 +983,30 @@ typed. 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.
 
-Besides those exporters, the =embark-consult= package provides many
-subtle tweaks and small integrations between Embark and Consult. For
-example, if you run =embark-collect= from any of the the =consult-yank=
-family of commands, you'll see the Embark Collect buffers has full
-multi-line kill-ring entries with zebra stripes, so you can easily tell
-where they start and end.
+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-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.
+
+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.
+
+Besides those exporters and candidate collectors, the =embark-consult=
+package provides many subtle tweaks and small integrations between
+Embark and Consult. For example, if you run =embark-collect= from any of
+the the =consult-yank= family of commands, you'll see the Embark Collect
+buffers has full multi-line kill-ring entries with zebra stripes, so
+you can easily tell where they start and end.
 
 Some examples of little tweaks provided by =embark-consult= to the
 behavior of Consult commands when used as Embark actions are:
diff --git a/embark.texi b/embark.texi
index bf4143d9bb..fb5ddd6502 100644
--- a/embark.texi
+++ b/embark.texi
@@ -44,6 +44,10 @@ Overview
 * Working with sets of possible targets::
 * Switching to a different command without losing what you've typed::
 
+Working with sets of possible targets
+
+* @samp{embark-live} a live-updating variant of @samp{embark-collect}::
+
 Advanced configuration
 
 * Showing information about available targets and actions::
@@ -301,6 +305,35 @@ contents restored. You can then interact normally with the 
command,
 perhaps editing the minibuffer contents, and, if you wish, you can
 rerun @samp{embark-collect} or @samp{embark-export} to get an updated buffer.
 
+@menu
+* @samp{embark-live} a live-updating variant of @samp{embark-collect}::
+@end menu
+
+@node @samp{embark-live} a live-updating variant of @samp{embark-collect}
+@subsection @samp{embark-live} a live-updating variant of @samp{embark-collect}
+
+Finally, there is also an @samp{embark-live} variant of the 
@samp{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,
+Selectrum, Fido-mode, or MCT) will probably not want to use
+@samp{embark-live} from the minibuffer as they will then have two live
+updating displays of the completion candidates!
+
+A more likely use of @samp{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
+@samp{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 @samp{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
+@samp{embark-live} genuinely useful other candidate collectors are required.
+The @samp{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 @samp{outline-minor-mode}. Those collectors really do give
+@samp{embark-live} a table-of-contents feel.
+
 @node Switching to a different command without losing what you've typed
 @section Switching to a different command without losing what you've typed
 
@@ -1148,12 +1181,35 @@ typed. 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.
 
-Besides those exporters, the @samp{embark-consult} package provides many
-subtle tweaks and small integrations between Embark and Consult. For
-example, if you run @samp{embark-collect} from any of the the 
@samp{consult-yank}
-family of commands, you'll see the Embark Collect buffers has full
-multi-line kill-ring entries with zebra stripes, so you can easily tell
-where they start and end.
+The @samp{embark-consult} also contains some candidates collectors that allow
+you to run @samp{embark-live} to get a live-updating table of contents for
+your buffer:
+
+@itemize
+@item
+@samp{embark-consult-outline-candidates} produces the outline headings of
+the current buffer, using @samp{consult-outline}.
+@item
+@samp{embark-consult-imenu-candidates} produces the imenu items of
+the current buffer, using @samp{consult-imenu}.
+@item
+@samp{embark-consult-imenu-or-outline-candidates} is a simple combination
+of the two previous functions: it produces imenu items in buffers
+deriving from @samp{prog-mode} and otherwise outline headings.
+@end itemize
+
+The way to configure @samp{embark-live} (or @samp{embark-collect} and 
@samp{embark-export}
+for that matter) to use one of these function is to add it at the end
+of the @samp{embark-candidate-collectors} list. The @samp{embark-consult} 
package by
+default adds the last one, which seems to be the most sensible
+default.
+
+Besides those exporters and candidate collectors, the @samp{embark-consult}
+package provides many subtle tweaks and small integrations between
+Embark and Consult. For example, if you run @samp{embark-collect} from any of
+the the @samp{consult-yank} family of commands, you'll see the Embark Collect
+buffers has full multi-line kill-ring entries with zebra stripes, so
+you can easily tell where they start and end.
 
 Some examples of little tweaks provided by @samp{embark-consult} to the
 behavior of Consult commands when used as Embark actions are: