* mu4e: update the mail/indexing update process:

- M-x mu4e-update-mail-and-index (C-S-U in main/headers/view/compose, with
  prefix arg, run in background
  - M-x mu4e-update-index to only update the index
  - document / add to FAQ

mu4e/mu4e-compose.el

@@ -528,6 +528,8 @@ needed, set the Fcc header, and register the handler function."
 	    (boundp 'completion-at-point-functions))
       (mu4e~compose-setup-completion))
 
+    (define-key mu4e-compose-mode-map (kbd "C-S-u") 'mu4e-update-mail-and-index)
+    
     ;; setup the fcc-stuff, if needed
     (add-hook 'message-send-hook
       (lambda ()

mu4e/mu4e-headers.el

@@ -443,6 +443,8 @@ after the end of the search results."
   (setq mu4e-headers-mode-map
     (let ((map (make-sparse-keymap)))
 
+      (define-key map  (kbd "C-S-u") 'mu4e-update-mail-and-index)
+      
       (define-key map "s" 'mu4e-headers-search)
       (define-key map "S" 'mu4e-headers-search-edit)
 

mu4e/mu4e-main.el

@@ -44,8 +44,12 @@
 
     (define-key map "m" 'mu4e~main-toggle-mail-sending-mode)
     (define-key map "f" 'smtpmail-send-queued-mail)
-    (define-key map "U" 'mu4e-update-mail-show-window)
 
+    ;;
+    (define-key map "U" 'mu4e-update-mail-and-index)
+    (define-key map  (kbd "C-S-u") 'mu4e-update-mail-and-index)
+    
+    
     (define-key map "$" 'mu4e-show-log)
     (define-key map "A" 'mu4e-about)
     (define-key map "H" 'mu4e-display-manual)

mu4e/mu4e-utils.el

@@ -505,35 +505,6 @@ process."
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
 
-(defconst mu4e~update-buffer-name "*mu4e-update*"
-  "Name of the buffer for message retrieval/database updating.")
-
-(defconst mu4e~update-buffer-height 8
-  "Height of the mu4e message retrieval/update buffer.")
-
-(defun mu4e-update-mail-show-window ()
-  "Try to retrieve mail (using the user-provided shell command),
-and update the database afterwards, and show the progress in a
-split-window."
-  (interactive)
-  (unless mu4e-get-mail-command
-    (mu4e-error "`mu4e-get-mail-command' is not defined"))
-  ;; delete any old update buffer
-  (when (buffer-live-p mu4e~update-buffer-name)
-    (with-current-buffer mu4e~update-buffer-name
-      (kill-buffer-and-window)))
-  ;; create a new one
-  (let ((buf (get-buffer-create mu4e~update-buffer-name))
-	 (win (split-window (selected-window)
-	     (- (window-height (selected-window)) 8))))
-    (with-selected-window win
-      (switch-to-buffer buf)
-      (set-window-dedicated-p win t)
-      (erase-buffer)
-      (insert "\n") ;; FIXME -- needed so output starts
-      (mu4e-update-mail buf t))))
-
-
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;; start and stopping
@@ -618,7 +589,8 @@ FUNC (if non-nil) afterwards."
 	      (when (and mu4e-update-interval (null mu4e~update-timer))
 		(setq mu4e~update-timer
 		  (run-at-time
-		    0 mu4e-update-interval 'mu4e-update-mail)))
+		    0 mu4e-update-interval
+		    (lambda () (mu4e-update-mail-and-index t)))))
 	      (mu4e-message "Started mu4e with %d message%s in store"
 		doccount (if (= doccount 1) "" "s"))))))
 
@@ -653,23 +625,28 @@ FUNC (if non-nil) afterwards."
 	  (kill-buffer))))
     (buffer-list)))
 
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; getting mail / updating the index 
+;;
+;;
 (defvar mu4e~update-timer nil
   "The mu4e update timer.")
-
-(defconst mu4e~update-mail-name "*mu4e-update-mail*"
-  "Name of the process to update mail.")
+(defconst mu4e~update-name "*mu4e-update*"
+  "Name of the process and buffer to update mail.")
+(defconst mu4e~update-buffer-height 8
+  "Height of the mu4e message retrieval/update buffer.")
 
 (defvar mu4e~get-mail-ask-password "mu4e get-mail: Enter password: "
   "Query string for `mu4e-get-mail-command' password.")
-
 (defvar mu4e~get-mail-password-regexp "^Remote: Enter password: $"
   "Regexp to match a password query in the `mu4e-get-mail-command' output.")
 
-(defun mu4e~process-filter (proc msg)
+(defun mu4e~get-mail-process-filter (proc msg)
   "Filter the output of `mu4e-get-mail-command'.
-Currently the filter only checks if the command asks for a password by matching
-the output against `mu4e~get-mail-password-regexp'.  The messages are inserted
-into the process buffer."
+Currently the filter only checks if the command asks for a password
+by matching the output against `mu4e~get-mail-password-regexp'.
+The messages are inserted into the process buffer."
   (save-current-buffer
     (when (process-buffer proc)
       (set-buffer (process-buffer proc)))
@@ -677,28 +654,46 @@ into the process buffer."
       ;; Check whether process asks for a password and query user
       (when (string-match mu4e~get-mail-password-regexp msg)
         (if (process-get proc 'x-interactive)
-            (process-send-string proc (concat
-                                       (read-passwd mu4e~get-mail-ask-password)
-                                       "\n"))
-           ;; TODO kill process?
-          (error "Get-mail process requires a password")))
+            (process-send-string proc
+	      (concat (read-passwd mu4e~get-mail-ask-password) "\n"))
+	  ;; TODO kill process?
+          (mu4e-error "Unrecognized password request")))
       (when (process-buffer proc)
         (insert msg)))))
 
-(defun mu4e-update-mail (&optional buf interactive)
-  "Update mail (retrieve using `mu4e-get-mail-command' and update
-the database afterwards), with output going to BUF if not nil, or
-discarded if nil. After retrieving mail, update the database. Note,
-function is asynchronous, returns (almost) immediately, and all the
-processing takes part in the background, unless buf is non-nil.
-If INTERACTIVE is not nil then the user might be asked for a
-password."
+(defun  mu4e-update-index ()
+  "Update the mu4e index."
+  (interactive)
+  (unless mu4e-maildir
+    (mu4e-error "`mu4e-maildir' is not defined"))
+  (mu4e~proc-index mu4e-maildir mu4e-user-mail-address-list))
+
+;; complicated function, as it:
+;;   - needs to check for errors
+;;   - (optionally) pop-up a window
+;;   - (optionally) check password requests
+(defun mu4e-update-mail-and-index (run-in-background)
+  "Get a new mail by running `mu4e-get-mail-command'. If
+run-in-background is non-nil (or functional called with
+prefix-argument), run in the background; otherwise, pop up a
+window."
+  (interactive "P")
   (unless mu4e-get-mail-command
     (mu4e-error "`mu4e-get-mail-command' is not defined"))
-  (let* ((process-connection-type t)
+  (let* ((buf (unless run-in-background
+		(get-buffer-create mu4e~update-name)))
+	  (win (and buf (split-window (selected-window)
+			  (- (window-height (selected-window)) 8))))
+	  (process-connection-type t)
 	  (proc (start-process-shell-command
-		 mu4e~update-mail-name buf mu4e-get-mail-command)))
+		  mu4e~update-name buf mu4e-get-mail-command)))
     (mu4e-message "Retrieving mail...")
+    (when (window-live-p win)
+      (with-selected-window win
+	(switch-to-buffer buf)
+	(set-window-dedicated-p win t)
+	(erase-buffer)
+	(insert "\n"))) ;; FIXME -- needed so output starts   
     (set-process-sentinel proc
       (lambda (proc msg)
 	(let* ((status (process-status proc))
@@ -710,14 +705,15 @@ password."
 		(buf (process-buffer proc)))
 	  (message nil)
 	  ;; there may be an error, give the user up to 5 seconds to check
-	  (when maybe-error
-	    (sit-for 5))
-	  (mu4e~proc-index mu4e-maildir mu4e-user-mail-address-list)
-	  (when (buffer-live-p buf)
-	    (kill-buffer buf)))))
-    (process-put proc 'x-interactive interactive)
-    (set-process-filter proc 'mu4e~process-filter)))
-
+	  (when maybe-error (sit-for 5))
+	  (mu4e-update-index)
+	  (when (buffer-live-p buf) (kill-buffer buf)))))
+    ;; if we're running in the foreground, handle password requests
+    (unless run-in-background
+      (process-put proc 'x-interactive (not run-in-background))
+      (set-process-filter proc 'mu4e~get-mail-process-filter))))
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+ 
 
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

mu4e/mu4e-view.el

@@ -475,6 +475,8 @@ at POINT, or if nil, at (point)."
   (setq mu4e-view-mode-map
     (let ((map (make-sparse-keymap)))
 
+      (define-key map  (kbd "C-S-u") 'mu4e-update-mail-and-index)
+      
       (define-key map "q" 'mu4e~view-quit-buffer)
 
       ;; note, 'z' is by-default bound to 'bury-buffer'

mu4e/mu4e.texi

@@ -389,10 +389,9 @@ worked, by trying some command-line searches, for example
 @end example
 
 which should list all messages that match @t{hello}. For more examples of
-searches, see @ref{Queries}, or check the @t{mu-find} and @t{mu-easy} man pages.
-
-If all of this worked well, we are well on our way setting up @t{mu}; the next
-step is to do some basic configuration for @t{mu4e}.
+searches, see @ref{Queries}, or check the @t{mu-find} and @t{mu-easy} man
+pages. If all of this worked well, we are well on our way setting up @t{mu};
+the next step is to do some basic configuration for @t{mu4e}.
 
 @node Basic configuration
 @section Basic configuration
@@ -445,14 +444,18 @@ As we have seen, we can do all of the mail retrieval @emph{outside} of
 @command{emacs}/@t{mu4e}. However, you can also do it from within
 @t{mu4e}. For that, set the variable @code{mu4e-get-mail-command} to the
 program or shell command you want to use for retrieving mail. You can then
-retrieve your e-mail from the @ref{Main view}. You can also set
-@code{mu4e-get-mail-command} to @t{"true"}, in which case @t{mu4e} won't try
-to get new mail, but still re-index your messages.
+retrieve your e-mail using @kbd{M-x mu4e-update-mail-and-index}, or
+@kbd{C-S-u} in all @t{mu4e}-views.
 
-You can also have this command run periodically in the background, by setting
-the variable @code{mu4e-update-interval} to the number of seconds between
-these updates. If set to @code{nil}, it won't update at all. After you make
-changes to @code{mu4e-update-interval}, @t{mu4e} must be restarted before
+If you don't have a specific command for getting mail, for example because you
+are running your own mail-server, you can set @code{mu4e-get-mail-command} to
+@t{"true"}, in which case @t{mu4e} won't try to get new mail, but still
+re-index your messages.
+
+You can also update your mail and index periodically in the background, by
+setting the variable @code{mu4e-update-interval} to the number of seconds
+between these updates. If set to @code{nil}, it won't update at all. After you
+make changes to @code{mu4e-update-interval}, @t{mu4e} must be restarted before
 the changes take effect.
 
 A simple setup could look something like:
@@ -650,7 +653,7 @@ Finally, there are some @emph{Misc} (miscellaneous) actions:
 @itemize
 @item @t{[U]pdate email & database} executes the shell-command in the variable
  @code{mu4e-get-mail-command}, and afterwards updates the @t{mu} database;
-see @ref{Indexing your messages} and @ref{Getting mail} for details
+see @ref{Indexing your messages} and @ref{Getting mail} for details.
 @item @t{toggle [m]ail sending mode (direct)} toggles between sending
 mail directly, and queuing it first (for example, when you are offline), and
 @t{[f]lush queued mail} flushes any queued mail. This item is visible only
@@ -801,6 +804,7 @@ a            execute some custom action on a header
 |            pipe message through shell command
 C-+,C--      increase / decrease the number of headers shown
 H            get help
+C-S-u        update mail & reindex
 q,z          leave the headers buffer
 @end verbatim
 
@@ -1040,6 +1044,7 @@ v            show details about the cryptographic signature
 .            show the raw message view. 'q' takes you back.
 C-+,C--      increase / decrease the number of headers shown
 H            get help
+C-S-u        update mail & reindex
 q,z          leave the message view
 @end verbatim
 
@@ -1272,6 +1277,9 @@ C-c C-c      send message
 C-c C-d      save to drafts and leave
 C-c C-k      kill the message
 C-c C-a      attach a file (pro-tip: drag & drop works as well)
+
+(mu4e-specific)
+C-S-u        update mail & reindex
 @end verbatim
 
 @node Address autocompletion
@@ -2803,6 +2811,8 @@ through my own mailserver. What should I use for
 @code{mu4e-get-mail-command}}? Use @t{"true"} (or don't do anything, it's the
 default). This makes getting mail a no-op, but the messages are still
 re-indexed.
+@item @emph{How can I re-index my messages without getting new mail?}
+{@tkbd{M-x mu4e-update-index}}
 @item @emph{When I try to run @t{mu index} while @t{mu4e} is running I get
 errors like:}
 @verbatim