]> git.cworth.org Git - notmuch-wiki/blobdiff - emacstips.mdwn
emacstips: fix english usage
[notmuch-wiki] / emacstips.mdwn
index 1c84545104154ac8c24633806a63d22cfc16b545..36b70293cb7350d6220a5e44ccd4bec06cf8d7e2 100644 (file)
@@ -174,62 +174,39 @@ case you want this behaviour:
 
 ## Add a key binding to add/remove/toggle a tag
 
-The `notmuch-{search,show}-{add,remove}-tag` functions are very useful
-for making quick tag key bindings.  For instance, here's an example
-of how to make a key binding to add the "spam" tag and remove the
-"inbox" tag in notmuch-show-mode:
-
-In notmuch versions up to 0.11.x
-
-        (define-key notmuch-show-mode-map "S"
-          (lambda ()
-            "mark message as spam"
-            (interactive)
-            (notmuch-show-add-tag "spam")
-            (notmuch-show-remove-tag "inbox")))
-
-Starting from notmuch 0.12 the functions `notmuch-show-add-tag` and
-`notmuch-show-remove-tag` have changed to be more versatile and lost
-noninteractive use. When upgrading to 0.12 the above needs to be
-changed to this:
+The `notmuch-{search,show,tree}-tag` functions are very useful for
+making quick tag key bindings.  The arguments to these functions have
+changed as notmuch has evolved but the following should work on all
+versions of notmuch from 0.13 on.  These functions take a list of
+tag changes as argument. For example, an argument of (list "+spam"
+"-inbox) adds the tag spam and deletes the tag inbox. Note the
+argument must be a list even if there is only a single tag change
+e.g., use (list "+deleted") to add the deleted tag.
+
+For instance, here's an example of how to make a key binding to add
+the "spam" tag and remove the "inbox" tag in notmuch-show-mode:
 
         (define-key notmuch-show-mode-map "S"
           (lambda ()
             "mark message as spam"
             (interactive)
-            (notmuch-show-tag-message "+spam" "-inbox")))
+            (notmuch-show-tag (list "+spam" "-inbox"))))
 
 You can do the same for threads in `notmuch-search-mode` by just
-replacing "show" with "search" in the called functions.
-
-Starting from notmuch 0.12 use `notmuch-search-tag-thread` instead:
-
-        (define-key notmuch-search-mode-map "S"
-          (lambda ()
-            "mark messages in thread as spam"
-            (interactive)
-            (notmuch-show-tag-thread "+spam" "-inbox")))
-
-Starting from notmuch 0.13 use `notmuch-search-tag` -- it has a little
-different usage syntax:
-
-        (define-key notmuch-search-mode-map "S"
-          (lambda ()
-            "mark messages in thread as spam"
-            (interactive)
-            (notmuch-search-tag '("+spam" "-inbox"))))
+replacing "show" with "search" in the keymap and called functions, or
+for messages in `notmuch-tree-mode` by replacing "show" by "tree". If
+you want to tag a whole thread in `notmuch-tree-mode` use
+`notmuch-tree-tag-thread` instead of `notmuch-tree-tag`.
 
-The definition above makes use of a lambda function, but you could
+The definitions above make use of a lambda function, but you could
 also define a separate function first:
 
         (defun notmuch-show-tag-spam ()
           "mark message as spam"
           (interactive)
-          (notmuch-show-add-tag "spam")
-          (notmuch-show-remove-tag "inbox")))
-        (define-key notmuch-show-mode-map "S" 'notmuch-show-tag-spam)
+          (notmuch-show-add-tag (list "+spam" "-inbox")))
 
-(See above for analogy how to apply this for notmuch 0.12 and later)
+        (define-key notmuch-show-mode-map "S" 'notmuch-show-tag-spam)
 
 Here's a more complicated example of how to add a toggle "deleted"
 key:
@@ -239,18 +216,8 @@ key:
             "toggle deleted tag for message"
             (interactive)
             (if (member "deleted" (notmuch-show-get-tags))
-                (notmuch-show-remove-tag "deleted")
-              (notmuch-show-add-tag "deleted"))))
-
-And version for notmuch 0.12
-
-        (define-key notmuch-show-mode-map "d"
-          (lambda ()
-            "toggle deleted tag for message"
-            (interactive)
-            (notmuch-show-tag-message
-              (if (member "deleted" (notmuch-show-get-tags))
-                  "-deleted" "+deleted"))))
+                (notmuch-show-tag (list "-deleted"))
+              (notmuch-show-tag (list "+deleted")))))
 
 ## Adding many tagging keybindings
 
@@ -329,14 +296,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
@@ -742,3 +732,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)