mu4e: update docs for mu4e-view-save-attachments

2 files changed, 33 insertions, 23 deletions

diff --git a/mu4e/mu4e-mime-parts.el b/mu4e/mu4e-mime-parts.el
index d06cdb5..fa97dad 100644
--- a/mu4e/mu4e-mime-parts.el
+++ b/mu4e/mu4e-mime-parts.el
@@ -160,7 +160,8 @@ Otherwise, return a file with a unique number appended to the base-name."
 (defvar mu4e--completions-table nil)
 
 (defun mu4e-view-complete-all ()
-  "Pick all current candidates."
+  "Pick all current candidates.
+Note: this is not compatible with `helm-mode'."
   (interactive)
   (if (bound-and-true-p helm-mode)
       (mu4e-warn "Not supported with helm")
@@ -290,10 +291,13 @@ Optionally,
 (defun mu4e-view-save-attachments (&optional ask-dir)
   "Save files from the current view buffer.
 
-Save the specific files selected, if no files are explicitly
-selected then all attachments will be saved.  Note all MIME-parts
-that are \"attachment-like\" (have a filename) will be considered
-a file regardless of their disposition.
+Save the attachments that are selected. If none are explicitly
+selected then *all* attachments will be saved. For using subset,
+there is \\[mu4e-view-complete-all] to select all attachments.
+
+Note all MIME-parts that are \"attachment-like\" (have a
+filename) will be considered a file, regardless of their
+disposition.
 
 With ASK-DIR is non-nil, user can specify the target-directory; otherwise
 one is determined using `mu4e-attachment-dir'.
@@ -313,9 +317,12 @@ files."
          (candidates  (seq-map
                        (lambda (fpart)
                          (let ((fname (plist-get fpart :filename)))
-                           (when (and crm-separator (string-match-p crm-separator fname))
-                             (mu4e-warn (concat  "File(s) match `crm-separator'; "
-                                                 "use mu4e-view-mime-part-action instead")))
+                           (when (and crm-separator
+                                      (string-match-p crm-separator fname))
+                             (mu4e-warn
+                              (concat
+                               "File(s) match `crm-separator'; "
+                               "use mu4e-view-mime-part-action instead")))
                            ;; (filename . annotation)
                            (cons fname fpart)))
                        (seq-filter
@@ -323,8 +330,9 @@ files."
                         parts)))
          (candidates (or candidates
                          (mu4e-warn "No attachments for this message")))
-         (files (or (mu4e--completing-read "Save files (default ALL): " candidates
-                                            'attachment 'multi)
+         (files (or (mu4e--completing-read
+                     "Save attachments (default: save all): " candidates
+                     'attachment 'multi)
                     (mapcar #'car-safe candidates)))
          (custom-dir (when ask-dir (read-directory-name
                                     "Save to directory: "))))
@@ -336,7 +344,7 @@ files."
                              (or custom-dir (plist-get part :target-dir))
                              (plist-get part :filename))))
                      (handle (plist-get part :handle)))
-                (when handle ;; completion may fail, and then there's no handle.
+                (when handle ;; completion may fail, and no handle.
                   (mm-save-part-to-file handle path))))
             files)))
 
diff --git a/mu4e/mu4e.texi b/mu4e/mu4e.texi
index f8d11a5..a9bdc64 100644
--- a/mu4e/mu4e.texi
+++ b/mu4e/mu4e.texi
@@ -1579,29 +1579,31 @@ parts is the 'body', which is the main text of the message your are readings.
 Other MIME-parts in the messages include @emph{attachments}.
 
 @subsection Attachments
+@cindex attachments
 
-Many e-mail messages also contain @emph{attachments}, which are MIME-parts that
-contain files@footnote{Attachments come in two flavors: @t{inline} and
+Many e-mail messages contain @emph{attachments}, which are MIME-parts that
+encode files@footnote{Attachments come in two flavors: @t{inline} and
 @t{attachment}. @code{mu4e} does not distinguish between the two when operating on
 them: everything that specifies a filename is considered an attachment}.
 
-To save such attachments as files on your computer, @code{mu4e}'s message-view
+To save attachments as files on your computer, @code{mu4e}'s message-view
 offers the command @code{mu4e-view-save-attachments}; its default keybinding is
 @key{e} (think @emph{extract}).
 
-Note that when point is on the attachment label in the message, e.g., on
-something that looks like @t{[4. application/pdf; Some Document.pdf]...}, Gnus'
-binding for @kbd{e} prevails, which is @code{gnus-mime-view-part-externally}.
-You can of course customize this in the usual (Emacs) way.
+When point is on the attachment label in the message, e.g., on something that
+looks like @t{[4. application/pdf; Some Document.pdf]...}, the Gnus' binding for
+@kbd{e} prevails, which is @code{gnus-mime-view-part-externally}. You can of
+course customize this in the usual (Emacs) way.
 
 After invoking the command, you can enter the file names to save,
 comma-separated, with completion support. Press @key{RET} to save the chosen
-attachments as files to your computer.
+attachments as files to your computer. If you do not specify any attachments,
+@emph{all} are saved.
 
-@code{mu4e} determines the target directory using the variable
-@code{mu4e-attachment-dir} (which can be either file-system path or a function; see
-its docstring for details. However, you can manually set the target by calling
-@code{mu4e-view-save-attachments} with a prefix argument.
+@code{mu4e} determines the target directory, using the variable
+@code{mu4e-attachment-dir} (which can be either file-system path or a function;
+see its docstring for details. However, you can manually set the target by
+calling @code{mu4e-view-save-attachments} with a prefix argument.
 
 When completing the file names, @code{mu4e-view-completion-minor-mode} is
 active, which offers @code{mu4e-view-complete-all} (bound to @key{C-c C-a} to