INSTALL/README: Clean up the description of how to run the emacs interface.
authorCarl Worth <cworth@cworth.org>
Tue, 1 Jun 2010 17:44:32 +0000 (10:44 -0700)
committerCarl Worth <cworth@cworth.org>
Tue, 1 Jun 2010 17:51:42 +0000 (10:51 -0700)
The INSTALL file still had old information about the "make
install-emacs" command which no longer exists. README was also giving
pointers on how to develop a real interface, (which is not the right
thing since README should be addressed to users, not coders).

So remove the stale and misplaced information, and instead add a new
"Running notmuch" section to the README describing how to run the
notmuch command-line interface and how to run the emacs interface.

INSTALL
README

diff --git a/INSTALL b/INSTALL
index 9cf328eea3186910ad9dd5cbbc44893325d46b74..e51b397cc2a9d77a56424074775dfcdaf4b5abfb 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -18,16 +18,6 @@ will call configure for you). See this command:
 for detailed documentation of the things you can control at the
 configure stage.
 
-notmuch.el installation
------------------------
-Installing the notmuch.el emacs lisp function systemwide:
-
-       sudo make install-emacs
-
-Each user needs to add (require 'notmuch) in his ~/.emacs to make it
-available and then start emacs running notmuch with "emacs -f notmuch"
-or start notmuch from within emacs with "M-x notmuch".
-
 Dependencies
 ------------
 Notmuch depends on three libraries: Xapian, GMime 2.4, and Talloc
diff --git a/README b/README
index 5f029c828280f6661ea045d2a06496214686cc82..3a003ad9cb7573d51879c945509da51ae8b2bd70 100644 (file)
--- a/README
+++ b/README
@@ -12,6 +12,48 @@ Building notmuch
 ----------------
 See the INSTALL file for notes on compiling and installing notmuch.
 
+Running notmuch
+---------------
+After installing notmuch, start by running "notmuch setup" which will
+interactively prompt for configuration information such as your name,
+email address, and the directory which contains your mail archive to
+be indexed. You can change any answers later by running "notmuch
+setup" again or by editing the .notmuch-config file in your home
+directory.
+
+With notmuch configured you should next run "notmuch new" which will
+index all of your existing mail. This can take a long time, (several
+hours) if you have a lot of email, (hundreds of thousands of
+files). When new mail is delivered to your mail archive in the future,
+you will want to run "notmuch new" again. These runs will be much
+faster as they will only index new messages.
+
+Finally, you can prove to yourself that things are working by running
+some command-line searches such as "notmuch search
+from:someone@example.com" or "notmuch search subject:topic". See
+"notmuch help search-terms" for more details on the available search
+syntax.
+
+The command-line search output is not expected to be particularly
+friendly for day-to-day usage. Instead, it is expected that you will
+use an email interface that builds on the notmuch command-line tool or
+the libnotmuch library.
+
+Notmuch installs a full-featured email interface for use within
+emacs. To use this, first add the following line to your .emacs file:
+
+       (require 'notmuch)
+
+Then, either run "emacs -f notmuch" or execute the command "M-x
+notmuch" from within a running emacs.
+
+If you're interested in a non-emacs-based interface to notmuch, then
+please join the notmuch community. Various other interfaces are
+already in progress, (an interface within vim, a curses interface,
+graphical interfaces based on evolution, and various web-based
+interfaces). The authors of these interfaces would love further
+testing or contribution. See contact information below.
+
 Contacting users and developers
 -------------------------------
 The website for Notmuch is:
@@ -33,39 +75,3 @@ developing notmuch:
 
        IRC server:     irc.freenode.net
        Channel:        #notmuch
-
-Interface options
------------------
-Notmuch includes a "notmuch" command-line interface to the system.
-This is not a very convenient interface and it is not expected that
-users will find it satisfying. Instead, there are two option for
-obtaining a more sophisticated interface:
-
-     1. Build on top of the "notmuch" command-line interface.
-
-       This might be a reasonable option for a very text-oriented
-       client environment. For example, an emacs-based interface for
-       notmuch is already under development and is available in the
-       notmuch.el file in this distribution.
-
-       If someone were to write a curses-based interface, or similar,
-       it might also be reasonable to build on the "notmuch"
-       command-line interface.
-
-     2. Build on top of the notmuch library interface.
-
-       This is a better choice for developing an interface that has
-       full control of the presentation of email threads and
-       messages. It is expected that anyone integrating Notmuch into
-       an existing, graphical email program use the notmuch library
-       interface.
-
-       The public interface to the notmuch library is contained in
-       the notmuch.h header file. The "notmuch" command-line program
-       in notmuch.c can be used as good example code, since it is a
-       simple program that is written on top of the library
-       interface.
-
-As can be seen, alternate interfaces to the Notmuch mail system are
-still in development. We would appreciate any contributions to these
-efforts.