Merge pull request #527 from jyp/master

mu4e: Document the mu4e-marks variable in the manual

mu4e/mu4e-mark.el

@@ -145,7 +145,6 @@ properties are:
    :char       "r"
    :prompt     "refile"
    :dyn-target  (lambda (target msg) (mu4e-get-refile-folder msg))
-   :show-target (lambda (target) target)
    :action      (lambda (docid msg target) (mu4e~proc-move docid (mu4e~mark-check-target target) "-N")))
   (delete
    :char "D"
@@ -161,7 +160,6 @@ properties are:
    :char "m"
    :prompt "move"
    :ask-target  mu4e~mark-get-move-target
-   :show-target (lambda (target) target)
    :action (lambda (docid msg target) (mu4e~proc-move docid (mu4e~mark-check-target target) "-N")))
   (read
    :char       "!"
@@ -172,7 +170,6 @@ properties are:
    :char      "d"
    :prompt "dtrash"
    :dyn-target (lambda (target msg) (mu4e-get-trash-folder msg))
-   :show-target (lambda (target) target)
    :action (lambda (docid msg target) (mu4e~proc-move docid (mu4e~mark-check-target target) "+T-N")))
   (unflag
    :char     "-"
@@ -192,12 +189,10 @@ properties are:
   (unmark
    :char     " "
    :prompt "unmark"
-   :show-target (lambda (target) nil)
    :action (mu4e-error "No action for unmarking"))
   (something
    :char  "*"
    :prompt "*something"
-   :show-target (lambda (target) "")
    :action (mu4e-error "No action for deferred mark"))
   )))
 
@@ -233,7 +228,10 @@ The following marks are available, and the corresponding props:
 	  (markdesc (cdr (or (assq mark mu4e-marks) (mu4e-error "Invalid mark %S" mark))))
 	  (markkar (plist-get markdesc :char))
           (target (mu4e~mark-get-dyn-target mark target))
-	  (shown-target (funcall (plist-get markdesc :show-target) target)))
+          (show-fct (plist-get markdesc :show-target))
+	  (shown-target (if show-fct
+                            (funcall show-fct target)
+                          target)))
     (unless docid (mu4e-warn "No message on this line"))
     (unless (eq major-mode 'mu4e-headers-mode) (mu4e-error "Not in headers-mode"))
     (save-excursion

mu4e/mu4e.texi

@@ -2099,7 +2099,7 @@ Custom mark functions are to be appended to the list
 first character of this string determines its shortcut, so these should be
 unique. If necessary, simply prefix the name with a unique character.
 @item a predicate function, taking two arguments @var{msg} and @var{param}.
-@var{msg} is the message plist (see @ref{Message functions} and @var{param} is
+@var{msg} is the message plist (see @ref{Message functions}) and @var{param} is
 a parameter provided by the third of the marker elements (see the next
 item). The predicate function should return non-@t{nil} if the message
 matches.
@@ -2335,6 +2335,66 @@ Suppose we want to inspect the number of recipients for a message in the
 After evaluating this, @kbd{a N} in the headers view shows the number of
 recipients for the message at point.
 
+@node Adding a new kind of mark
+@section Adding a new kind of mark
+
+It is possible to configure new marks. To do so one can add entries
+in the list @code{mu4e-marks}. Such an element must have the following form:
+
+@lisp
+(SYMBOL
+  :char STRING
+  :prompt STRING
+  :ask-target (lambda () TARGET)
+  :dyn-target (lambda (TARGET MSG) DYN-TARGET)
+  :show-target (lambda (DYN-TARGET) STRING)
+  :action (lambda (DOCID MSG DYN-TARGET) nil))
+@end lisp
+
+The symbol can be any symbol, except for 'unmark and 'something, which
+are reserved. The rest is a plist with the following
+elements:
+
+@itemize
+@item @code{:char} -- the character to display in the headers view.
+@item @code{:prompt} -- the prompt to use when asking for marks (used for example when marking a whole thread).
+@item @code{:ask-target} -- a function run once per bulk-operation, and thus suitable for
+querying the user about a target for move-like marks. If nil, the
+TARGET passed to @code{:dyn-target} is nil.
+@item @code{:dyn-target} -- a function run once per message
+(The message is passed as MSG to the function). This function allows
+to compute a per-message target, for refile-like marks. If nil, the
+DYN-TARGET passed to the @code{:action} is the TARGET obtained as above.
+@item @code{:show-target} -- how to display the target in the headers view.
+If @code{:show-target} is nil the DYN-TARGET is shown (and DYN-TARGET must be
+a string).
+@item @code{:action} -- the action to apply on the message when the mark is executed.
+@end itemize
+
+As an example, suppose we would like to add a mark for tagging
+messages (gmail-style), then we can run the following code (after
+loading mu4e):
+
+@lisp
+(add-to-list 'mu4e-marks
+   '(tag
+     :char       "g"
+     :prompt     "gtag"
+     :ask-target (lambda () (read-string "What tag do you want to add?"))
+     :action      (lambda (docid msg target)
+                    (mu4e-action-retag-message msg (concat "+" target)))))
+@end lisp
+
+Adding to @code{mu4e-marks} list allows to use the mark in bulk operations
+(for example when tagging a whole thread), but does not bind the mark
+to a key to use at the top-level. This must be done separately. In our
+example:
+
+@lisp
+(mu4e~headers-defun-mark-for tag)
+(define-key mu4e-headers-mode-map (kbd "g") 'mu4e-headers-mark-for-tag)
+@end lisp
+
 @node Adding an action in the message view
 @section Adding an action in the message view
 
@@ -2417,6 +2477,8 @@ variable @code{mu4e-attachment-dir}.
 see @ref{Adding an action in the headers view}
 @item Apply a function to a message in the message view - see @ref{Adding an
 action in the message view}
+@item Add a new kind of mark for use in the headers view
+- see @ref{Adding a new kind of mark}
 @item Apply a function to to an attachment - see @ref{Adding an attachment
 action}
 @item Custom function to mark certain messages - see @ref{Custom mark functions}