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

3 files changed, 48 insertions, 35 deletions

diff --git a/NEWS.org b/NEWS.org
index 15cfac2..c9bca95 100644
--- a/NEWS.org
+++ b/NEWS.org
@@ -271,8 +271,8 @@
       use it e.g., with something like:
 
       #+begin_src elisp
-	(require 'mu4e-transient)
-	(global-set-key (kbd "C-c m") #'mu4e-transient-menu)
+        (require 'mu4e-transient)
+        (global-set-key (kbd "C-c m") #'mu4e-transient-menu)
       #+end_src
       This will change/improve, but is already quite useful.
 
@@ -317,6 +317,9 @@
       read/unread counts of bookmarked queries) on the DBus session bus.
       See [[info:mu4e#DBus
        service][DBus service]] in the mu4e manual for further details.
+
+    - 1.12.15: in ~mu4e-view-save-attachments~, by default save /all/.
+
 *** scm
 
     - 1.12.12: add new guile/scheme binding in ~scm/~. These are to replace the
@@ -441,7 +444,7 @@
       may have been enhanced by various completion frameworks), use:
     #+begin_src elisp
        (setq mu4e-read-option-use-builtin nil
-	 mu4e-completing-read-function 'completing-read)
+         mu4e-completing-read-function 'completing-read)
     #+end_src
 
     - when moving messages (which includes changing flags), file-flags changes
@@ -687,22 +690,22 @@
      - the remaining common functionality has ended up in =mu4e-helpers.el=
 
      - =mu4e-search.el= takes the search-specific code from =mu4e-headers.el=,
-	and adds a minor-mode for the keybindings.
+        and adds a minor-mode for the keybindings.
 
      - =mu4e-context.el= and =mu4e-update.el= also define minor modes with
-	keybindings, which saves a lot of code in the various views, since they
-	don't need explicitly bind all those function.
+        keybindings, which saves a lot of code in the various views, since they
+        don't need explicitly bind all those function.
 
      - also =mu4e-vars.el= had become very big, we're refactoring the =defvar= /
-	=defcustom= declarations to the topic-specific files.
+        =defcustom= declarations to the topic-specific files.
 
      - =mu4e-proc.el= has been renamed =mu4e-server.el=.
 
      - Between =mu= and =mu4e=, contact cells are now represented as a plist ~(:name
-	"Foo Bar" :email "foobar@example.com")~ rather than a cons-cell ~("Foo
-	Bar" . "foobar@example.com").~
+        "Foo Bar" :email "foobar@example.com")~ rather than a cons-cell ~("Foo
+        Bar" . "foobar@example.com").~
 
-	If you have scripts depending on the old format, there's the
+        If you have scripts depending on the old format, there's the
        ~mu4e-contact-cons~ function which takes a news-style contact and yields
        the old form.
 
@@ -729,7 +732,7 @@
       the following in the mu top source directory:
 
 #+BEGIN_SRC sh
-	$ meson build && ninja -C build
+        $ meson build && ninja -C build
 #+END_SRC
 
     - However, note that =autogen.sh= has been updated, and there's a
@@ -1031,7 +1034,7 @@
 
       For now this is experimental ("tech preview"), but might replace the
       current message-view in a future release. Enable it with:
-	       (setq mu4e-view-use-gnus t)
+               (setq mu4e-view-use-gnus t)
 
       Thanks to Christophe Troestler for his work on fixing various encoding
       issues.
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