* mu4e: documentation updates

mu4e/mu4e.texi

@@ -166,7 +166,7 @@ a mail server. That task is delegated to other tools, such as
 @t{offlineimap}@footnote{@url{http://offlineimap.org/}},
 @t{isync}@footnote{@url{http://isync.sourceforge.net/}} or
 @t{fetchmail}@footnote{@url{http://www.fetchmail.info/}}. As long as the
-messages end up in a Maildir, @t{mu4e} and @t{mu} are happy to deal with them.
+messages end up in a maildir, @t{mu4e} and @t{mu} are happy to deal with them.
 
 @t{mu4e} also does @emph{not} implement sending of messages; instead, it
 depends on @t{smptmail} (@inforef{Top,smtpmail,smtpmail}), which is part of
@@ -209,26 +209,26 @@ yourself. However, if there are no packages for your distribution, or if you
 want to use the latest development versions, you can follow the steps below.
 
 First, you need make sure you have the necessary dependencies. On a Debian or
-Ubuntu system, you can get these with:
+Ubuntu system, you can get these with the following commands:
 
 @example
-sudo apt-get install libgmime-2.6-dev libxapian-dev
+$ sudo apt-get install libgmime-2.6-dev libxapian-dev
 # if libgmime-2.6-dev is not available, try libgmime-2.4-dev
 
 # get macs if you don't have it yet, mu4e works with GNU-Emacs 23 and 24
 # emacs 24 works better; it may be available as 'emacs-snapshot'
-sudo apt-get install emacs23
+$ sudo apt-get install emacs23
 
 # optional
-sudo apt-get install guile-2.0-dev html2text xdg-utils
+$ sudo apt-get install guile-2.0-dev html2text xdg-utils
 
 # optional: only needed for msg2pdf and mug (toy gtk+ frontend)
-sudo apt-get install libwebkit-dev
+$ sudo apt-get install libwebkit-dev
 @end example
 
 Using a release-tarball (as available from
 GoogleCode@footnote{@url{http://code.google.com/p/mu0/downloads/list}},
-Installation follows the normal sequence:
+installation follows the normal steps:
 
 @example
 $ tar xvfz mu-<version>.tar.gz  # use the specific version
@@ -238,14 +238,14 @@ $ sudo make install
 @end example
 
 Alternatively, if you build from the git repository or use a tarball like the
-ones that @t{github} produces, the instructions are slightly different (and
+ones that @t{github} produces, the instructions are slightly different, and
-require you to have @t{autotools} installed):
+require you to have @t{autotools} installed:
 
 @example
-# get from git, or from a github tarball
+# get from git (alternatively, use a github tarball)
-# git clone git://github.com/djcb/mu.git 
+$ git clone git://github.com/djcb/mu.git 
 
-$ cd mu-<version>
+$ cd mu
 $ autoreconf -i && ./configure && make
 $ sudo make install
 @end example
@@ -260,51 +260,56 @@ You may need to restart @t{emacs}, so it can find @t{mu4e} in its
 
 @subsection mu4e and emacs customization
 
-There is @emph{experimental} support for using the @t{emacs} customization
+There is some support for using the @t{emacs} customization system in
-system in @t{mu4e}, but for now, we recommend setting the values
+@t{mu4e}, but for now, we recommend setting the values manually. Please refer
-manually. Please refer to @ref{Example configuration} for a couple of examples
+to @ref{Example configuration} for a couple of examples of this; here we go
-of this.
+through things step-by-step.
 
 @node Getting mail
 @section Getting mail
 
 In order for @t{mu} (and, by extension, @t{mu4e}) to work, you need to have
-your e-mail messages stored in a Maildir - a specific directory structure with
+your e-mail messages stored in a
-one-file-per-message. If you are already using Maildirs, you are lucky;
+@emph{maildir}@footnote{@url{http://en.wikipedia.org/wiki/Maildir}} - a
-otherwise, you need to get your mail there in some way.
+specific directory structure with one-file-per-message. If you are already
+using a maildirs, you are lucky; otherwise, you need to get your mail there in
+some way.
 
 If you are using an @abbr{IMAP} or @abbr{POP} server, you can use tools like
 @t{getmail}, @t{fetchmail}, @t{offlineimap} or @t{isync} to download your
-message into a maildir (@file{~/Maildir}, usually). If you are using a local
+messages into a maildir (@file{~/Maildir}, often). Because it is such a common
-mail-server (such as @emph{Postfix} or @t{qmail}), you can teach them to
+case, there is a full example of setting @t{mu4e} up with @t{offlineimap} and
-deliver into a maildir as well, maybe in combination with @t{procmail}. A bit
+Gmail; @pxref{Gmail configuration}.
-of googling should be able to provide you with the detail. Because it is a
+
-rather common case, there is a full example of setting @t{mu4e} up with
+If you are using a local mail-server (such as @emph{Postfix} or @t{qmail}),
-@t{offlineimap} and Gmail; @pxref{Gmail configuration}.
+you can teach them to deliver into a maildir as well, maybe in combination
+with @t{procmail}. A bit of googling should be able to provide you with the
+details.
 
 @node Indexing your messages
 @section Indexing your messages
 
 After you have succeeded in @ref{Getting mail}, we need to @emph{index} the
-messages. That is - we need to scan the Maildir and store the information
+messages. That is - we need to scan the message in the maildir and store the
-about the mails into a special database. We can do that from @code{mu4e} --
+information about the mails into a special database. We can do that from
-@ref{Main view}, but the first time, it is a good idea to run it from the
+@code{mu4e} -- @ref{Main view}, but the first time, it is a good idea to run
-command line, as it is easier to recognize potential problems.
+it from the command line, to make sure everything works correctly.
 
-Assuming that your Maildir is at @file{~/Maildir}, you should give the
+Assuming that your maildir is at @file{~/Maildir}, we give the following
-following command:
+command:
 @example
   $ mu index --maildir=~/Maildir
 @end example
 
 This should scan your @file{~/Maildir}@footnote{In most cases, you do not even
-need to provide the @t{--maildir=~/Maildir}; see the @t{mu-index} man-page for
+need to provide the @t{--maildir=~/Maildir} since it is the default; see the
-details} and fill the database, and give progress information while doing so.
+@t{mu-index} man-page for details} and fill the database, and give progress
+information while doing so.
 
 The indexing process may take a few minutes the first time you do it (for
-thousands of e-mails); afterwards it is much faster, since @t{mu} only has to
+thousands of e-mails); afterwards it is much faster, since @t{mu} only scans
-scan the differences. Indexing is discussed in more detail in the @t{mu-index}
+messages that are new or have changed. Indexing is discussed in full detail in
-man page.
+the @t{mu-index} man page.
 
 After the indexing process has finished, you can quickly test if everything
 worked, by trying some command line searches, for example
@@ -316,22 +321,22 @@ worked, by trying some command line searches, for example
 which should list all messages that match @t{hello}. For more examples of
 searches @xref{Queries}, or check the @t{mu-find} and @t{mu-easy} man pages.
 
-If all of this worked well, we are well on our way setting up @t{mu4e}; the
+If all of this worked well, we are well on our way setting up @t{mu}; the next
-next step is to do some basic configuration.
+step is to do some basic configuration for @t{mu4e}.
 
 @node Basic configuration
 @section Basic configuration
 
 The first thing we need to do before we can start using @t{mu4e} is to tell
-@t{emacs} to load @t{mu4e}, and tell @t{mu4e} where it can find specific
+@t{emacs} to load it, and tell @t{mu4e} where it can find specific maildir
-maildir folders.
+folders.
 
 So, add to your @file{~/.emacs} (or its moral equivalent, such as
 @file{~/.emacs.d/init.el}) something like:
 
-@example
+@lisp
 (require 'mu4e)
-@end example
+@end lisp
 
 @node Folders
 @section Folders
@@ -352,8 +357,9 @@ runtime. This allows for dynamically changing them depending on context. See
 @end lisp
 
 @code{mu4e-maildir} takes an actual filesystem-path, the other folder names
-are all relative to @code{mu4e-maildir}. The next step is telling @t{mu4e} how
+are all relative to @code{mu4e-maildir}. The ones above are also the defaults.
-we want to send mail.
+
+Now, let's see how we can get the messages into our system.
 
 @node Retrieval and indexing
 @section Retrieval and indexing
@@ -372,7 +378,7 @@ these updates. If set to @code{nil}, it won't update at all. If you make
 changes to @code{mu4e-update-interval}, @code{mu4e} must be restarted before
 the changes take effect.
 
-A simple setup may look something like:
+A simple setup could look something like:
 
 @lisp
 (setq 
@@ -384,15 +390,18 @@ It is possible to get notifications when the indexing process does any updates
 - for example when receiving new mail. See @code{mu4e-index-updated-hook} and
 the tips on its use in the @ref{FAQ - Frequently Anticipated Questions}.
 
+Now that we have setup 
+The next step is telling @t{mu4e} how we want to send mail.
+
 @node Sending mail
 @section Sending mail
 
-@t{mu4e} re-uses Gnu's @inforef{Top,,message} for writing mail and inherits
+@t{mu4e} re-uses Gnu's @t{message-mode} (@inforef{Top,,message}) for writing
-the setup for @emph{sending} mail from that.
+mail and inherits the setup for @emph{sending} mail as well.
 
-For sending mail using @abbr{SMTP}, @t{mu4e} uses
+For sending mail using @abbr{SMTP}, @t{mu4e} uses @t{smtpmail}
-@inforef{Top,,smtpmail}. This package support many different ways to send
+(@inforef{Top,,smtpmail}). This package support many different ways to send
-mail, please refer to its documentation for the details.
+mail; please refer to its documentation for the details.
 
 Here, we only provide some simple examples - for more, @ref{Example
 configuration}.
@@ -410,6 +419,8 @@ A very minimal setup could look something like:
 Since @t{mu4e} (re)uses the same @t{message mode} and @t{smtpmail} that Gnus
 uses, many settings for those also apply to @t{mu4e}.
 
+@subsection Dealing with sent messages
+
 By default, @t{mu4e} puts a copy of any messages you sent in the folder you
 set for @code{mu4e-sent-folder}.  some case, this may not be what you want -
 for example, when using Gmail-over-@abbr{IMAP} (but @emph{not} with
@@ -431,21 +442,22 @@ For Gmail-IMAP, you could add the following to your settings:
 (setq mu4e-sent-messages-behavior 'trash)
 @end verbatim
 
-And that's it! We should now be ready to go now.
+And that's it! We should now be ready to go.
 
 @node Running mu4e
 @section Running mu4e
 
-After the following the steps in this chapter, we now hopefully have a working
+After following the steps in this chapter, we should now have a working
-@t{mu4e} setup. @t{mu4e} consists of a number of views, and in the next
+@t{mu4e} setup. Great! 
-chapter we go through all of them:
 
-@menu
+In the next chapters, we walk through the various views in @t{mu4e}.
-* Main view:: This is where we start
+ 
-* Headers view:: Lists of message headers
+@c @menu
-* Message view:: Viewing specific messages
+@c * Main view:: This is where we start
-* Editor view:: Creating / editing messages
+@c * Headers view:: Lists of message headers
-@end menu
+@c * Message view:: Viewing specific messages
+@c * Editor view:: Creating / editing messages
+@c @end menu
 
 For your orientation, the diagram below shows how the views relate to each
 other, and the default key-bindings to get from one view to the next.
@@ -483,7 +495,7 @@ E: Edit       B: edit bookmark-search
 
 After you have installed @t{mu4e} (@pxref{Getting started}), you can start it
 with @code{M-x mu4e}. @t{mu4e} does some checks to ensure everything is set up
-correctly, and then show you the @t{mu4e} main view.
+correctly, and then show you the glorious @t{mu4e} main view.
 
 @menu
 * MV Overview::
@@ -499,7 +511,7 @@ The main view looks something like the following:
 
 @verbatim
 ----------------------------------------------------------------------------
-* mu4e - mu for emacs version x.x
+* mu4e - mu for emacs version x.x C
 
   Basics
 
@@ -1722,7 +1734,7 @@ messages. There are some more examples in the defaults for
     mu4e-refile-folder "/archive")   ;; saved messages
 @end lisp
 
-In some cases having such static folders may not suffice - you might want to
+In some cases, having such static folders may not suffice - you may want to
 change the folders depending on the context. For example, the folder for
 refiling could vary, based on the sender of the message.
 
@@ -1730,7 +1742,7 @@ For this, instead of setting the standard folders to a string, you can set
 them to be a @emph{function} that takes a message as parameter, and returns
 the desired folder name.
 
-In this chapter we show how to do that.
+This chapter shows how to do that.
 
 @menu
 * Smart refiling::
@@ -1771,14 +1783,14 @@ put something like the following in your setup:
 @end lisp
 
 This can be very powerful; you can mark (select) all the messages in the
-headers view, then press @key{r}, and have them all sent to their particular
+headers view, then press @key{r}, and have them all marked for refiling to
-refile folders.
+their particular folders.
 
 Some notes:
 @itemize
 @item we set @code{mu4e-refile-folder} to an anonymous (@t{lambda}) function. This
 function takes one argument, a message.  @file{mu4e-message.el} contains
-various convenience functions to deal which such messages
+various convenience functions to deal which such messages.
 @item In this function, we use a @t{cond} control structure; the function
 returns the first of the clauses that matches
 @item Especially useful are the function @file{mu4e-message.el}; here we use
@@ -1792,19 +1804,20 @@ matches the regular expression.
 
 Using the same mechanism, you can set special sent-, trash-, and draft-folders
 for messages. The message-parameter you receive for sent and draft folder is
-qthe @emph{original} message, that is, the message you reply to, or forward. If
+the @emph{original} message, that is, the message you reply to, forward. If
-there is no such message (for example when composing a new message) the
+there is no such message (for example when composing a brand new message) the
 message parameter is @t{nil}.
 
-Let's look at another example. Suppose you want a different trash folder for
+Let's look at an example of this. Suppose you want a different trash folder
-work-email. You can do so with something like the following:
+for work-email. You can do so with something like the following:
 
 @lisp
  (setq mu4e-sent-folder
     (lambda (msg)
-       (if (mu4e-message-contact-field-matches msg :to "me@@work.com")
+       ;; the 'and msg' is to handle the case where there msg is nil
+       (if (and msg (mu4e-message-contact-field-matches msg :to "me@@work.com"))
 	"/trash-work"
-        "/trash-private")))
+        "/trash")))
 @end lisp
 
 Good to remember:
@@ -1815,11 +1828,6 @@ forwarded. When re-editing a message, it refers to the message being
 edited. When you compose a totally new message, the @code{msg} parameter is
 @code{nil}.
 @item When re-editing messages, the value of @code{mu4e-drafts-folder} is ignored.
-@item When composing messages, @code{mu4e-sent-folder},
-@code{mu4e-drafts-folder} and @code{mu4e-trash-folder}@footnote{if you wonder
-why we would need @code{mu4e-trash-folder} when composing a message, see
-@code{mu4e-sent-messages-behavior}} evaluated only once, just before message
-composition starts. Afterwards, the value it got at that time is used.
 @end itemize