From 93214e7018e145bbfb1f853da665e350b32fdf8d Mon Sep 17 00:00:00 2001
From: Jean-Philippe Bernardy <jeanphilippe.bernardy@gmail.com>
Date: Sun, 30 Nov 2014 23:11:57 +0100
Subject: [PATCH] take a stab at the documentation of mu4e-marks

---
 mu4e/mu4e.texi | 64 +++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 63 insertions(+), 1 deletion(-)

diff --git a/mu4e/mu4e.texi b/mu4e/mu4e.texi
index 62d9b178..887ab2af 100644
--- a/mu4e/mu4e.texi
+++ b/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}