News for release 0.38.3

[notmuch-wiki] / notmuch-emacs.mdwn

diff --git a/notmuch-emacs.mdwn b/notmuch-emacs.mdwn
index 2e09dd27ffc2c1a748219c7b3509fa0ecf5127e8..f5c8f013867fbb9870ad8e5ae7c22e3e2abc1ca7 100644 (file)
--- a/notmuch-emacs.mdwn
+++ b/notmuch-emacs.mdwn
@@ -2,22 +2,43 @@
 # Notmuch Emacs Interface
 
 One of the more popular Notmuch message reading clients is **notmuch.el**, or
-`notmuch-emacs`, 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).
+`notmuch-mode`, an [Emacs](https://www.gnu.org/software/emacs/) major mode for
+interacting with Notmuch. It is included in the Notmuch package (as
+`elpa-notmuch` within the `notmuch` package in current Debian or as
+`notmuch-emacs` in Debian 10 or prior). The [[screenshots|screenshots]] give a
+good overview of the mode.
 
 This page is a basic guide for setting up and using Notmuch with Emacs. See also
 the [[tips and tricks page|emacstips]] for more advanced details.
 
 [[!toc levels=2]]
 
-## Setup
+## Prerequisites
+
+The Notmuch Emacs interface uses the Notmuch [command line
+interface](https://notmuchmail.org/doc/latest/man1/notmuch.html) to
+interact with the Notmuch database and your mail store. Please make
+sure you've [[set up Notmuch|getting-started]] first.
+
+## Installation
 
-Have a look at the [[Howto|howto]] for prerequisites. Be sure you have done the
-general setup using the Notmuch cli command!
+Due to the dependency on the command line interface, the Notmuch Emacs interface
+version must be compatible with the Notmuch version. On Linux, the easiest way
+to ensure this is to use the package(s) in your distribution's package
+repository.
 
-To use the Notmuch Emacs mode, first add the following line to your `.emacs` rc
-file:
+If you've installed Notmuch from a [git
+checkout](https://git.notmuchmail.org/git/notmuch) or a [source
+release](https://notmuchmail.org/releases/), Notmuch Emacs is included by
+default.
+
+It is **not** recommended to install Notmuch Emacs from the Emacs Lisp Package
+Archive (ELPA), as the version there is likely not in sync with the command line
+interface.
+
+## Setup
+
+First, you need to tell Emacs about Notmuch. Add this to your `.emacs` rc file:
 
         (autoload 'notmuch "notmuch" "notmuch mail" t)
 
@@ -25,12 +46,17 @@ or if you always want to load Notmuch when you start Emacs:
 
         (require 'notmuch)
 
-Then, either run `emacs -f notmuch`, or execute the command `M-x notmuch` from
-within a running Emacs.
+To start Notmuch Emacs, either run `emacs -f notmuch`, or execute the command
+`M-x notmuch RET` from within a running Emacs. This will bring you to the
+Notmuch Hello view.
 
-### <span id="notmuch_init_file"> Notmuch Emacs configuration file: </span>
+## Customization
 
-(Since Notmuch 0.18)
+Notmuch Emacs uses the Emacs customization interface extensively for
+configuration. Execute `M-x customize-group RET notmuch RET` to get to the
+Notmuch main customization group.
+
+### <span id="notmuch_init_file"> Notmuch Emacs configuration file </span>
 
 After Notmuch is loaded `notmuch-init-file` (typically
  `~/.emacs.d/notmuch-config.el`) is checked out. If such file exists
@@ -68,7 +94,7 @@ When composing new messages, you will be entered in Emacs's
 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).
+messages, see [address completion](/emacstips#index13h2).
 
 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
@@ -109,3 +135,7 @@ mentioned as script arguments. (Note: The script expects that you have
             shift
         done
         emacsclient -a '' -c -e "(progn (compose-mail) $attach_cmds)"
+
+Also, if you're the kind of person who forgets to add attachments,
+there's a cure for that disease. See [Never forget
+attachments](/emacstips#index27h2) for all the details.