* mu4e-marks.el: some improvements in marking:

- use 'r' for marking as 'read'
   - show an overlay string for all marks to tell what they do
   - (this can be disabled by setting mu4e-headers-show-target to nil)
   - document this

emacs/mu4e-mark.el

@@ -39,8 +39,15 @@
   :type 'symbol
   :group 'mu4e-headers)
 
+(defvar mu4e-headers-show-target t
+  "Whether to show targets (such as '-> delete', '-> /archive')
+when marking message. Normally, this is useful information for the
+user, however, when you often mark large numbers (thousands) of
+message, showing the target makes this quite a bit slower (showing
+the target uses an emacs feature called 'overlays', which aren't
+particularly fast).")
 
-;;; marks ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;;; insert stuff;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 (defvar mu4e~mark-map nil
   "Map (hash) of docid->markinfo; when a message is marked, the
 information is added here.
@@ -95,17 +102,22 @@ The following marks are available, and the corresponding props:
    `unmark'   n         unmark this message"
   (interactive)
   (let* ((docid (mu4e~headers-docid-at-point))
-	  (markkar
+	  ;; get a cell with the mark char and the 'target' 'move' already has a
+	  ;; target (the target folder) the other ones get a pseudo "target", as
+	  ;; info for the user.
+	  (markcell
 	    (case mark ;; the visual mark
-	      ('move    "m")
+	      ('move    `("m" . ,target))
-	      ('trash   "d")
+	      ('trash   '("d" . "trash"))
-	      ('delete  "D")
+	      ('delete  '("D" . "delete"))
-	      ('unread  "U")
+	      ('unread  '("o" . "unread"))
-	      ('read    "R")
+	      ('read    '("r" . "read"))
-	      ('flag    "+")
+	      ('flag    '("+" . "flag"))
-	      ('unflag  "-")
+	      ('unflag  '("-" . "unflag"))
-	      ('unmark  " ")
+	      ('unmark  '(" " . nil))
-	      (t (error "Invalid mark %S" mark)))))
+	      (t (error "Invalid mark %S" mark))))
+	  (markkar (car markcell))
+	  (target (cdr markcell)))
     (unless docid (error "No message on this line"))
     (save-excursion
       (when (mu4e~headers-mark docid markkar)
@@ -114,13 +126,12 @@ The following marks are available, and the corresponding props:
 	(remhash docid mu4e~mark-map)
 	;; remove possible overlays
 	(remove-overlays (line-beginning-position) (line-end-position))
-
 	;; now, let's set a mark (unless we were unmarking)
 	(unless (eql mark 'unmark)
 	  (puthash docid (list mark target) mu4e~mark-map)
 	  ;; when we have a target (ie., when moving), show the target folder in
 	  ;; an overlay
-	  (when target
+	  (when (and target mu4e-headers-show-target)
 	    (let* ((targetstr (propertize (concat "-> " target " ")
 				'face 'mu4e-system-face))
 		    ;; mu4e~headers-goto-docid docid t \will take us just after the

emacs/mu4e.texi

@@ -526,10 +526,13 @@ these actions are also listed in the @t{Headers} menu in the Emacs menu bar.
 
 @verbatim
 key          description
----          -----------
+===========================================================
 n,p          go to next, previous message
 y            select the message view (if it's visible)
+RET          open the message at point in the message view
 
+searching
+---------
 s            search
 S            edit last query
 /            narrow the search
@@ -543,33 +546,34 @@ O            change sort order
 P            toggle threading
 Q            toggle full-search
 
-a            execute some action on header
 
+marking
+-------
 d            mark for moving to the trash folder
 DEL,D        mark for immediate deletion
 m            mark for moving to another maildir folder
 +,-          mark for flagging/unflagging
+o,r          mark message as unread, read
+
 u            unmark message at point
+U            unmark *all* messages 
+
 %            mark based on a regular expression
 T,t          mark whole thread, subthread
 
+x            execute actions for the marked messages
+
+composition
+-----------
 R,F,C        reply/forward/compose
 E            edit (only allowed for draft messages)
 
+
+misc
+----
+a            execute some custom action on a header
 |            pipe message through shell command
-
 C-+,C--      increase / decrease the number of headers shown
-
-d            mark for moving to the trash folder
-DEL,D        mark for immediate deletion
-m            mark for moving to another maildir folder
-o            mark message as unread
-r            mark message as read
-u            unmark message at point
-U            unmark *all* messages
-x            execute actions for the marked messages
-RET          open the message at point in the message view
-
 H            get help
 q,z          leave the headers buffer
 @end verbatim
@@ -642,7 +646,7 @@ include the previously captured message as an attachment, using
 
 The file @file{mu4e-actions.el} in the @t{mu4e} source distribution contains a
 number of example actions.
-  
+ 
 
 @subsection Split view
 
@@ -941,7 +945,6 @@ configuration:
 (setq message-kill-buffer-on-exit t)
 @end lisp
 
-
 @subsection Queuing mail
 @anchor{Queuing mail}
 
@@ -1159,7 +1162,6 @@ The very same shortcuts are used by the @code{mu4e-mark-for-move} (default
 shortcut @key{m}); so, for example, if you want to move a message the
 @t{/archive} folder, you can do so by typing @key{ma}.
 
-
 @node Other search functionality
 @section Other search functionality
 
@@ -1211,6 +1213,7 @@ Marking can happen in both the @ref{Headers view} and the @ref{Message view}.
 @menu
 * Selecting messages for marking::
 * What to mark for::
+* Executing the marks::
 * Leaving the headers buffer::
 * Some marking examples::
 @end menu
@@ -1238,16 +1241,34 @@ respectively
 @t{mu4e} supports a number of different marks - i.e., different actions to
 apply to messages:
 
-@itemize
+@verbatim
-@item moving to trash (@key{t})
+| mark for     | keybinding  | description              |
-@item delete (@key{D} or @key{<delete>})
+|--------------+-------------+--------------------------|
-@item move to some maildir (@key{m})
+| trash        | d           | move to the trash folder |
-@item flag/unflag (@key{+}, @key{-})
+| delete       | D, <delete> | delete                   |
-@item mark as read/unread (@key{r}, @key{o})
+| move         | m           | move to some maildir     |
-@item remove the mark (@key{u})
+| flag         | +           | mark as 'flagged'        |
-@end itemize
+| unflag       | -           | remove 'flagged' mark    |
+| read         | r           | mark as read             |
+| unread       | o           | marks as unread          |
+| unmark       | u           | remove mark at point     |
+| remove all   | U           | remove all marks         |
+@end verbatim
+  
+After marking a header for something, the leftmost columns shows a character
+(same as the keybinding) to remind you what you marked it with. Next to that,
+@t{mu4e} displays the name of the mark, on top of the beginning of the header
+line. This latter display is informative, but if you often mark many
+(thousands) messages, this may slow down things significantly@footnote{this
+uses an emacs feature called @emph{overlays}, which are slow when used a lot
+in a buffer}. For this reason, you can disable this by setting
+@code{mu4e-headers-show-target} to @code{nil}.
 
-You can remove @emph{all} marks in the @ref{Headers view} with @key{U}.
+@node Executing the marks
+@section Executing the marks
+
+After you have marked some messages, you can execute them with @key{x}
+(@code{mu4e-mark-execute-all}).
 
 @node Leaving the headers buffer
 @section Leaving the headers buffer
@@ -1270,7 +1291,6 @@ press @key{% + s hello RET}. Note, the menu system helps you here; all you
 need to remember is @key{%} for @code{mu4e-headers-mark-pattern}.
 @end itemize
 
-
 @node Actions
 @chapter Actions
 
@@ -1735,6 +1755,9 @@ An (almost) minimal configuration for @t{mu4e} might look something like this:
    ;; with 'mu mkdir', i.e.. mu mkdir /home/user/Maildir/queue
    smtpmail-queue-mail  nil
    smtpmail-queue-dir  "/home/user/Maildir/queue/cur")
+
+   ;; don't keep message buffers around
+   (setq message-kill-buffer-on-exit t)
 @end lisp
 
 
@@ -1865,6 +1888,9 @@ Now, let's make a @t{mu4e} configuration for this:
       smtpmail-default-smtp-server "smtp.gmail.com"
       smtpmail-smtp-server "smtp.gmail.com"
       smtpmail-smtp-service 587)
+
+;; don't keep message buffers around
+(setq message-kill-buffer-on-exit t)
 @end lisp
 
 And that's it -- put the above in your @file{~/.emacs} (obviously you need to