X-Git-Url: https://git.cworth.org/git?a=blobdiff_plain;f=emacstips.mdwn;h=887f2429184270dda437578fa18a990987e31a95;hb=5607447c06ac11eac7fe2c991a76e41d316e08a4;hp=940ff211a5f6b562f97a974a1d444e9d69a7a371;hpb=4b09afee81119dc43a35a89e4186baf989b09dd0;p=obsolete%2Fnotmuch-wiki diff --git a/emacstips.mdwn b/emacstips.mdwn index 940ff21..887f242 100644 --- a/emacstips.mdwn +++ b/emacstips.mdwn @@ -1,63 +1,656 @@ -[[!img notmuch-logo.png alt="Notmuch logo" class="left"]] -#Tips and Tricks for using notmuch with Emacs - -* How to do FCC/BCC... - - Any notmuch reply will automatically include your primary email - address in a BCC so that any messages you send will (eventually) end - up in your mail store as well. - - But this doesn't do anything for messages that you compose that are - not replies. So we need to get sane message-mode FCC figured - out. Some investigation is still needed here. - -* How to customize notmuch-folders - - There's a "notmuch-folder" command available in the emacs client - that displays a list of "folders" and the number of messages in - each. Each folder is simply a named search specification. To - configure this mode, edit your ${HOME}/.emacs file and include text - something like the following: - - (setq notmuch-folders '(("inbox" . "tag:inbox") - ("unread" . "tag:inbox AND tag:unread") - ("notmuch" . "tag:inbox AND to:notmuchmail.org"))) - - Of course, you can have any number of folders, each configured - with any supported search terms (see "notmuch help search-terms"). - -* Viewing HTML messages with an external viewer - - The emacs client can often display an HTML message inline, but it - sometimes fails for one reason or another, (or is perhaps inadequate - if you really need to see the graphical presentation of the HTML - message). - - In this case, it can be useful to display the message in an external - viewer, such as a web browser. Here's a little script that Keith - Packard wrote, which he calls view-html: - - #!/bin/sh - dir=3D`mktemp -d` - trap "rm -r $dir" 0 - cat "$@" > "$dir"/msg - if munpack -C "$dir" -t < "$dir"/msg 2>&1 | grep 'Did not find'; then - sed -n '/[Hh][Tt][Mm][Ll]/,$p' "$dir"/msg > $dir/part1.html - rm "$dir"/msg - fi - for i in "$dir"/part*; do - if grep -q -i -e '' -e 'text/html' "$i"; then - iceweasel "$i" & - sleep 3 - exit 0 - fi - done - - Save that script somewhere in your ${PATH}, make it executable, and - change the invocation of iceweasel to any other HTML viewer if - necessary. Then within the emacs client, press "|" to pipe the - current message, then type "view-html". - - Keith mentions the following caveat, "Note that if iceweasel isn't - already running, it seems to shut down when the script exits. I - don't know why." +# Tips and Tricks for using notmuch with Emacs + +One of the more popular notmuch message reading clients is +**notmuch.el**, an [emacs](http://www.gnu.org/software/emacs/) major +mode for interacting with notmuch. It is included in the notmuch +package (notmuch-emacs in Debian). This page goes over some usage +tips for using notmuch with Emacs. + +[[!toc levels=2]] + +## Setup + +Have a look at the [Howto](http://notmuchmail.org/howto/) for +prerequisites. Be sure you have done the general setup using the +notmuch cli command! + +To use the Notmuch emacs mode, first add the following line to your +`.emacs` rc file: + + (require 'notmuch) + +or you can load the package via autoload: + + (autoload 'notmuch "notmuch" "notmuch mail" t) + +Then, either run "emacs -f notmuch", or execute the command `M-x +notmuch` from within a running emacs. + +## Navigating & reading mails + +When first starting notmuch in emacs, you will be presented with the +notmuch "hello" page. If it exits with an error after writing +"Welcome to notmutch. You have" you need to do the basic notmuch setup +first (see above). +From here you can do searches, see lists of recent +searches, saved searches, message tags, help information, etc. + +Executing a search will open a new buffer in `notmuch-search-mode` +displaying the search results. Each line in the search results +represents a message thread. Hitting the '?' key will show help for +this mode. + +In general, the 'q' will kill the current notmuch buffer and return +you to the previous buffer (sort of like a 'pop'). + +In search mode, navigating to a thread and hitting return will then +open a new buffer in `notmuch-show-mode`, which will show the actual +message contents of the thread. + +## Sending mail + +In any notmuch mode, you can start a new message by hitting the 'm' +key. To reply to a message or thread, just hit the 'r' key. + +When composing new messages, you will be entered in emacs's +`message-mode`, which is a powerful mode for composing and sending +messages. When in message mode, you can type `C-c ?` for help. + +If you would like to use address autocompletion when composing +messages, see [address completion](#address_completion). + +When you are ready to send a message, type `C-c C-c`. By default +message mode will use your sendmail command to send mail, so make sure +that works. One annoying standard configuration of message mode is +that it will hide the sent mail in your emacs frame stack, but it will +not close it. If you type several mails in an emacs session they will +accumulate and make switching between buffers more annoying. You can +avoid that behavior by adding `(setq message-kill-buffer-on-exit t)` +in your `.emacs` file (or doing `M-x +customize-variablemessage-kill-buffer-on-exit`) which will +really close the mail window after sending it. + +## Attaching files + +Using the `M-x mml-attach-file` command, you can attach any file to be +sent with your mail. By default this command is bound to the menu item +*Attachments--Attach File* with the key binding `C-c C-a`. The +variable `mml-dnd-attach-options` (`M-x +customize-variablemml-dnd-attach-options`) can be set to +allow the prompting for various attachment options (such as +inline/attachment) if you want to do that. + +For those who prefer a more graphical interface, you can also simply +drag and drop files from a file manager into a mail composition window +to have them attached. In Ubuntu this works without any modifications +if files are dragged from the file manager. + +And for those who prefer working from command line, the following +script opens new emacs window with empty message and attaches files +mentioned as script arguments. (Note: The script expects that you have +`(server-start)` in your `.emacs` file.) + + #!/bin/sh + attach_cmds="" + while [ "$1" ]; do + fullpath=$(readlink --canonicalize "$1") + attach_cmds="$attach_cmds (mml-attach-file \"$fullpath\")" + shift + done + emacsclient -a '' -c -e "(progn (compose-mail) $attach_cmds)" + +## Issues with Emacs 24 + +If notmuch-show-mode behaves badly for you in emacs 24.x try adding one of + + (setq gnus-inhibit-images nil) + +or + + (require 'gnus-art) + +to your .emacs file. + +----- + +# Advanced tips and tweaks + +## Use separate emacs lisp file for notmuch configuration + +Instead of adding notmuch configuration code to `.emacs`, there +is an option to collect those to a separate file (which is only +loaded when `notmuch` is invoked). To do this, write, for example +a file called `~/.emacs.d/my-notmuch.el`: + + ;;; my-notmuch.el -- my notmuch mail configuration + ;;; + + ;;; add here stuff required to be configured *before* + ;;; notmuch is loaded; + + ;; uncomment and modify in case some elisp files are not found in load-path + ;; (add-to-list 'load-path "~/vc/ext/notmuch/emacs") + + ;;; load notmuch + (require 'notmuch) + + ;;; add here stuff required to be configured *after* + ;;; notmuch is loaded; + + ;; uncomment & modify if you want to use external smtp server to send mail + ;; (setq smtpmail-smtp-server "smtp.server.tld" + ;; message-send-mail-function 'message-smtpmail-send-it) + ;; uncomment to debug smtp sending problems + ;; (setq smtpmail-debug-info t) + +Then, add to `.emacs`: + + (autoload 'notmuch "~/.emacs.d/my-notmuch" "notmuch mail" t) + + +## 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: + + (define-key notmuch-show-mode-map "S" + (lambda () + "mark message as spam" + (interactive) + (notmuch-show-tag-message "+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")))) + +The definition above makes 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) + +(See above for analogy how to apply this for notmuch 0.12 and later) + +Here's a more complicated example of how to add a toggle "deleted" +key: + + (define-key notmuch-show-mode-map "d" + (lambda () + "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")))) + +## Adding many tagging keybindings + +If you want to have have many tagging keybindings, you can save the typing +the few lines of boilerplate for every binding (for versions before 0.12, +you will need to change notmuch-show-apply-tag-macro). + + (eval-after-load 'notmuch-show + '(define-key notmuch-show-mode-map "`" 'notmuch-show-apply-tag-macro)) + + (setq notmuch-show-tag-macro-alist + (list + '("m" "+notmuch::patch" "+notmuch::moreinfo" "-notmuch::needs-review") + '("n" "+notmuch::patch" "+notmuch::needs-review" "-notmuch::pushed") + '("o" "+notmuch::patch" "+notmuch::obsolete" + "-notmuch::needs-review" "-notmuch::moreinfo") + '("p" "-notmuch::pushed" "-notmuch::needs-review" + "-notmuch::moreinfo" "+pending") + '("P" "-pending" "-notmuch::needs-review" "-notmuch::moreinfo" "+notmuch::pushed") + '("r" "-notmuch::patch" "+notmuch::review") + '("s" "+notmuch::patch" "-notmuch::obsolete" "-notmuch::needs-review" "-notmuch::moreinfo" "+notmuch::stale") + '("t" "+notmuch::patch" "-notmuch::needs-review" "+notmuch::trivial") + '("w" "+notmuch::patch" "+notmuch::wip" "-notmuch::needs-review"))) + + (defun notmuch-show-apply-tag-macro (key) + (interactive "k") + (let ((macro (assoc key notmuch-show-tag-macro-alist))) + (apply 'notmuch-show-tag-message (cdr macro)))) + +## Restore reply-to-all key binding to 'r' + +Starting from notmuch 0.12 the 'r' key is bound to reply-to-sender instead of +reply-to-all. Here's how to swap the reply to sender/all bindings in show mode: + + (define-key notmuch-show-mode-map "r" 'notmuch-show-reply) + (define-key notmuch-show-mode-map "R" 'notmuch-show-reply-sender) + +And in search mode: + + (define-key notmuch-search-mode-map "r" 'notmuch-search-reply-to-thread) + (define-key notmuch-search-mode-map "R" 'notmuch-search-reply-to-thread-sender) + + +## How to do FCC/BCC... + +The Emacs interface to notmuch will automatically add an `Fcc` +header to your outgoing mail so that any messages you send will also +be saved in your mail store. You can control where this copy of the +message is saved by setting the variables `message-directory` (which +defines a base directory) and `notmuch-fcc-dirs` which defines the +subdirectory relative to `message-directory` in which to save the +mail. Enter a directory (without the maildir `/cur` ending which +will be appended automatically). To customize both variables at the +same time, use the fancy command: + + M-x customize-apropos\(notmuch-fcc-dirs\)\|\(message-directory\) + +This mechanism also allows you to select different folders to be +used for the outgoing mail depending on your selected `From` +address. Please see the documentation for the variable +`notmuch-fcc-dirs` in the customization window for how to arrange +this. + +## How to customize `notmuch-saved-searches` + +When starting notmuch, a list of saved searches and message counts is +displayed, replacing the older `notmuch-folders` command. The set of +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: + + (setq notmuch-saved-searches '(("inbox" . "tag:inbox") + ("unread" . "tag:inbox AND tag:unread") + ("notmuch" . "tag:inbox AND to:notmuchmail.org"))) + +Of course, you can have any number of saved searches, each configured +with any supported search terms (see "notmuch help search-terms"). + +Some users find it useful to add `and not tag:delete` to those +searches, as they use the `delete` tag to mark messages as +deleted. This causes messages that are marked as deleted to be removed +from the commonly used views of messages. Use whatever seems most +useful to you. + +## Viewing HTML messages with an external viewer + +The emacs client can display an HTML message inline using either the +`html2text` library or some text browser, like w3m or lynx. This is +controlled by the `mm-text-html-renderer` variable. + +The first option is theorically better, because it can generate +strings formatted for emacs and do whatever you want, e.g., substitute +text inside <b> tags for bold text in the buffer. The library, however +is still in a very early development phase and cannot yet process +properly many elements, like tables and