+[[!toc levels=2]]
+
+The main Notmuch message reading client is **notmuch.el**, which is an
+[emacs](http://www.gnu.org/software/emacs/) major mode, and is
+included in the notmuch package.
+
+## Setup
+
+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. 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-variable<RET>message-kill-buffer-on-exit<RET>`) 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-variable<RET>mml-dnd-attach-options<RET>`) 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)"
+
+
+-----
+
+# 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;
+
+ ;(setq user-mail-address (notmuch-user-primary-email)
+ ; user-full-name (notmuch-user-name))
+
+ ; 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)
+
+Then, adto `.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 (not released yet) 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")))