[elpa] externals/embark ab778510d5: Document new revert behavior for export & collect buffers

[ELPA Syncer]

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

    Document new revert behavior for export & collect buffers
---
 README.org  |  9 +++++++++
 embark.el   | 33 ++++++++++++++++++++++++++++++---
 embark.texi | 12 ++++++++++--
 3 files changed, 49 insertions(+), 5 deletions(-)

diff --git a/README.org b/README.org
index ed5e3142ad..882bfd119e 100644
--- a/README.org
+++ b/README.org
@@ -192,6 +192,15 @@ and are bound to =A=, =S= (for "snapshot"), and =E=, 
respectively, in
 key bindings for these (although you can, of course!), just a key
 binding for =embark-act=.
 
+Reverting an Embark Collect or Embark Export buffer has slightly
+unusual behavior if the buffer was obtained by running =embark-collect=
+or =embark-export= from within a minibuffer completion session. In that
+case reverting just 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.
+
 ** Switching to a different command without losing what you've typed
 
 Embark also has the =embark-become= command which is useful for when
diff --git a/embark.el b/embark.el
index 2b4a6c5c8a..b7d8e72abb 100644
--- a/embark.el
+++ b/embark.el
@@ -2660,7 +2660,16 @@ you might prefer to change the key binding to match your 
other
 key binding for it. Or alternatively you might want to enable the
 embark collect direct action minor mode by adding the function
 `embark-collect-direct-action-minor-mode' to
-`embark-collect-mode-hook'.")
+`embark-collect-mode-hook'.
+
+Reverting an Embark Collect buffer has slightly unusual behavior
+if the buffer was obtained by running `embark-collect' from
+within a minibuffer completion session.  In that case reverting
+just 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' to get an updated buffer.")
 
 (defun embark-collect--remove-zebra-stripes ()
   "Remove highlighting of alternate rows."
@@ -2873,7 +2882,16 @@ TYPE should be either `collect' or `export'."
   "Create an Embark Collect buffer.
 
 To control the display, add an entry to `display-buffer-alist'
-with key \"Embark Collect\"."
+with key \"Embark Collect\".
+
+Reverting an Embark Collect buffer has slightly unusual behavior
+if the buffer was obtained by running `embark-collect' from
+within a minibuffer completion session.  In that case reverting
+just 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' to get an updated buffer."
   (interactive)
   (let ((buffer (embark--collect (embark--descriptive-buffer-name 'collect))))
     (when (minibufferp)
@@ -2945,7 +2963,16 @@ The parameter KIND should be either `embark-export' or 
`embark-collect'."
 (defun embark-export ()
   "Create a type-specific buffer to manage current candidates.
 The variable `embark-exporters-alist' controls how to make the
-buffer for each type of completion."
+buffer for each type of completion.
+
+Reverting an Embark Export buffer has slightly unusual behavior if
+the buffer was obtained by running `embark-export' from within a
+minibuffer completion session.  In that case reverting just
+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-export' to get an updated buffer."
   (interactive)
   (let* ((transformed (embark--maybe-transform-candidates))
          (candidates (or (plist-get transformed :candidates)
diff --git a/embark.texi b/embark.texi
index b514b54b90..d1b97a3768 100644
--- a/embark.texi
+++ b/embark.texi
@@ -250,8 +250,7 @@ option @samp{embark-confirm-act-all} to @samp{nil}.)
 @item
 The @samp{embark-collect} command produces a buffer listing all the current
 candidates, for you to peruse and run actions on at your leisure.
-The candidates can be viewed in a grid or as a list showing
-additional annotations.
+The candidates are displayed as a list showing additional annotations.
 
 The Embark Collect buffer is ``dired-like'': you can mark and unmark
 candidates with @samp{m} and @samp{u}, you can unmark all marked candidates 
with @samp{U}
@@ -288,6 +287,15 @@ and are bound to @samp{A}, @samp{S} (for ``snapshot''), 
and @samp{E}, respective
 key bindings for these (although you can, of course!), just a key
 binding for @samp{embark-act}.
 
+Reverting an Embark Collect or Embark Export buffer has slightly
+unusual behavior if the buffer was obtained by running @samp{embark-collect}
+or @samp{embark-export} from within a minibuffer completion session. In that
+case reverting just 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 @samp{embark-collect} or @samp{embark-export} to get an updated buffer.
+
 @node Switching to a different command without losing what you've typed
 @section Switching to a different command without losing what you've typed