emacstips: add sample code for viewing patches in diff-mode

[notmuch-wiki] / emacstips.mdwn

diff --git a/emacstips.mdwn b/emacstips.mdwn
index 5f1ad2c007cd1df09c6193b3a3b279bd2c8be5d7..3a1a3dde0b3513b542dd6c071b91044d67c995ca 100644 (file)
--- a/emacstips.mdwn
+++ b/emacstips.mdwn
@@ -1,3 +1,4 @@
+[[!img notmuch-logo.png alt="Notmuch logo" class="left"]]
 # Tips and Tricks for using notmuch with Emacs
 
 One of the more popular notmuch message reading clients is
@@ -328,14 +329,37 @@ saved searches displayed can be modified directly from the notmuch
 interface (using the `[save]` button next to a previous search) or by
 customising the variable `notmuch-saved-searches`.
 
-An example setting might be:
+An example setting for notmuch versions up to 0.17.x might be:
 
         (setq notmuch-saved-searches '(("inbox" . "tag:inbox")
                         ("unread" . "tag:inbox AND tag:unread")
                         ("notmuch" . "tag:inbox AND to:notmuchmail.org")))
 
+Starting from notmuch 0.18 the variable changed. It is backwards
+compatible so the above will still work but the new style will be used
+if you use customize and there are some new features available. The above would become
+
+        (setq notmuch-saved-searches '((:name "inbox" :query "tag:inbox")
+                        (:name "unread" :query "tag:inbox AND tag:unread")
+                        (:name "notmuch" :query "tag:inbox AND to:notmuchmail.org")))
+
+The additional features are the possibility to set the search order
+for the search, and the possibility to specify a different query for
+displaying the count for the saved-search. For example
+
+        (setq notmuch-saved-searches '((:name "inbox"
+                                        :query "tag:inbox"
+                                        :count-query "tag:inbox and tag:unread"
+                                        :sort-order 'oldest-first)))
+
+specifies a single saved search for inbox, but the number displayed by
+the search will be the number of unread messages in the inbox, and the
+sort order for this search will be oldest-first.
+
 Of course, you can have any number of saved searches, each configured
-with any supported search terms (see "notmuch help search-terms").
+with any supported search terms (see "notmuch help search-terms"), and
+in the new style variable they can each have different count-queries
+and sort orders.
 
 Some users find it useful to add `and not tag:delete` to those
 searches, as they use the `delete` tag to mark messages as
@@ -585,7 +609,7 @@ Here is an example configuration.
         ;; Use "home" identity by default
         (setq gnus-alias-default-identity "home")
         ;; Define rules to match work identity
-        (setq gnus-alias-identity-rules
+        (setq gnus-alias-identity-rules)
               '(("work" ("any" "john.doe@\\(example\\.com\\|help\\.example.com\\)" both) "work"))
         ;; Determine identity when message-mode loads
         (add-hook 'message-setup-hook 'gnus-alias-determine-identity)
@@ -741,3 +765,33 @@ Then
 In general it is nice to have a key for org-links (not just for notmuch). For example
 
     (define-key global-map "\C-cl" 'org-store-link)
+
+## Viewing diffs in notmuch
+
+The following code allows you to view an inline patch in diff-mode
+directly from notmuch. This means that normal diff-mode commands like
+refine, next hunk etc all work.
+
+    (defun my-notmuch-show-view-as-patch ()
+      "View the the current message as a patch."
+      (interactive)
+      (let* ((id (notmuch-show-get-message-id))
+             (subject (concat "Subject: " (notmuch-show-get-subject) "\n"))
+             (diff-default-read-only t)
+             (buf (get-buffer-create (concat "*notmuch-patch-" id "*")))
+             (map (make-sparse-keymap)))
+        (define-key map "q" 'notmuch-kill-this-buffer)
+        (switch-to-buffer buf)
+        (let ((inhibit-read-only t))
+          (erase-buffer)
+          (insert subject)
+          (insert (notmuch-get-bodypart-internal id 1 nil)))
+        (set-buffer-modified-p nil)
+        (diff-mode)
+        (lexical-let ((new-ro-bind (cons 'buffer-read-only map)))
+                     (add-to-list 'minor-mode-overriding-map-alist new-ro-bind))
+        (goto-char (point-min))))
+
+and then this function needs to bound into the keymap with something like
+
+    (define-key 'notmuch-show-mode-map "D" 'my-notmuch-show-view-as-patch)