* mu4e: documentation

mu4e/mu4e-vars.el

@@ -211,36 +211,56 @@ regexp."
 
 (defcustom mu4e-drafts-folder "/drafts"
   "Your folder for draft messages, relative to `mu4e-maildir',
-  e.g. \"/drafts\". Instead of a string, may also be a function
+e.g. \"/drafts\". Instead of a string, may also be a function that
-  that takes a msg (see `mu4e-message-get-field'), and returns a
+takes a message (a msg plist, see `mu4e-message-get-field'), and
-  folder."
+returns a folder.
+Note, the message parameter refers to the
+original message being replied to / being forwarded / re-edited and is nil
+otherwise.
+`mu4e-drafts-folder' is evaluated once when composing the message,
+and the value is used throughout the message composition. When re-editing messages,
+the value of `mu4e-drafts-folder' is ignored."
   :type 'string
   :safe 'stringp
   :group 'mu4e-folders)
 
 (defcustom mu4e-refile-folder "/archive"
   "Your folder for refiling messages, relative to `mu4e-maildir',
-  e.g. \"/Archive\". Instead of a string, may also be a function
+e.g. \"/Archive\". Instead of a string, may also be a function that
-  that takes a msg (see `mu4e-message-get-field'), and returns a
+takes a message (a msg plist, see `mu4e-message-get-field'), and
-  folder."
+returns a folder.
+Note, the message parameter refers to the message-at-point."
   :type 'string
   :safe 'stringp
   :group 'mu4e-folders)
 
 (defcustom mu4e-sent-folder "/sent"
   "Your folder for sent messages, relative to `mu4e-maildir',
-  e.g. \"/Sent Items\". Instead of a string, may also be a function
+e.g. \"/Sent Items\". Instead of a string, may also be a function
-  that takes a msg (see `mu4e-message-get-field'), and returns a
+that takes a message (a msg plist, see `mu4e-message-get-field'),
-  folder."
+and returns a folder.
+Note, the message parameter refers to the
+original message being replied to / being forwarded / re-edited, and is nil
+otherwise.
+`mu4e-sent-folder' is evaluated once when composing the message,
+and the value is used throughout the message composition."
   :type 'string
   :safe 'stringp
   :group 'mu4e-folders)
 
 (defcustom mu4e-trash-folder "/trash"
   "Your folder for trashed messages, relative to `mu4e-maildir',
-  e.g. \"/trash\". Instead of a string, may also be a function that
+e.g. \"/trash\". Instead of a string, may also be a function that
-  takes a msg (see `mu4e-message-get-field'), and returns a
+takes a message (a msg plist, see `mu4e-message-get-field'), and
-  folder."
+returns a folder.  When using `mu4e-trash-folder' in the headers
+view (when marking messages for trash).
+Note, the message parameter
+refers to the message-at-point. When using it when composing a
+message (see `mu4e-sent-messages-behavior'), this refers to the
+original message being replied to / being forwarded / re-edited, and is nil
+otherwise.
+`mu4e-trash-folder' is evaluated once when composing the message,
+and the value is used throughout the message composition."
   :type 'string
   :safe 'stringp
   :group 'mu4e-folders)

mu4e/mu4e.texi

@@ -62,13 +62,15 @@ later, built on top of the
 @t{mu}@footnote{@url{http://www.djcbsoftware.nl/code/mu}} e-mail search
 engine. @t{mu4e} is optimized for fast handling of large amounts of e-mail.
 
-Some of its features include:
+Some of its key characteristics include:
 
 @itemize
-@item Fully search-based: there are no folders, only queries
+@item Fully search-based there are no folders@footnote{that is, instead of
+folders, you can use queries that match all messages in a folder}, only
+queries
 @item Fully documented, with example configurations
 @item User-interface optimized for speed with quick key strokes for common actions
-@item Asynchronous: heavy actions don't block @t{emacs}@footnote{currently,
+@item Asynchronous; heavy actions don't block @t{emacs}@footnote{currently,
 the only exception to this is @emph{sending mail}}
 @item Support for crypto
 @item Writing rich-text e-mails using @t{org-mode}
@@ -83,9 +85,9 @@ customize @t{mu4e} for your needs.
 At the end of the manual, there are some example configurations, which should
 help you to get up to speed quickly.
 
-Then there's the @xref{FAQ - Frequently Anticipated Questions}, and the
+Also of note is the @xref{FAQ - Frequently Anticipated Questions}, which may
-section on @xref{Known issues}, which may save you some time, and the
+save you some time, and the appendices that try to shed some light on
-appendices that try the shed some light on @t{mu4e}'s internals.
+@t{mu4e}'s internals.
 
 This manual has been updated for @t{mu}/@t{mu4e} version
 @emph{@value{mu4e-version}}.
@@ -127,17 +129,16 @@ Fair question.
 
 I'm not sure the world needs yet another e-mail client, but perhaps @emph{I}
 do! I (the author) spend a @emph{lot} of time dealing with e-mail, both
-professionally and privately. Having an efficient e-mail client is essential
+professionally and privately. Having an efficient e-mail client is essential.
-for me. Since none of the existing ones worked the way I wanted, I created my
+Since none of the existing ones worked the way I wanted, I created my own.
-own.
 
 As @t{emacs} is an integral part of my workflow, it made a lot of sense to use
 it for e-mail as well. And as I already had written an e-mail search engine
 (@t{mu}), it seemed only logical to use that as a basis.
 
-Even though I created @t{mu4e} for such selfish reasons, @t{mu4e} tries hard
+Even though I created it for such selfish reasons, @t{mu4e} tries hard to be
-to be as useful as possible for all its users - suggestions are very
+as useful as possible for all its users - suggestions are very welcome and
-welcome and many have already made it to @t{mu4e}.
+many have already made it to @t{mu4e}.
 
 @node Other mail clients
 @section Other mail clients
@@ -146,12 +147,12 @@ Under the hood, @t{mu4e} is fully search-based, similar to programs like
 @t{notmuch}@footnote{@url{http://notmuchmail.org}},
 @t{md}@footnote{@url{https://github.com/nicferrier/md}} and
 @t{sup}@footnote{@url{http://sup.rubyforge.org/}}. However, @t{mu4e}'s
-user-interface is quite different from those programs.
+user-interface is rather different from those programs.
 
 @t{mu4e}'s mail handling (deleting, moving etc.) is inspired by
 @emph{Wanderlust}@footnote{@url{http://www.gohome.org/wl/}} (another
 emacs-based e-mail client), @t{mutt}@footnote{@url{http://www.mutt.org/}} and
-@t{dired}, while it also takes some cues from @emph{Gmail}.
+@t{dired}, while it also takes some ideas from @emph{Gmail}.
 
 @t{mu4e} tries to keep all the 'state' in your maildirs, so you can easily
 switch between clients, synchronize over @abbr{IMAP}, backup with @t{rsync}
@@ -180,11 +181,11 @@ efficiently as possible.
 @node Getting started
 @chapter Getting started
 
-In this chapter, we go through the installation of @t{mu4e} and show how you
+In this chapter, we go through the installation of @t{mu4e} and its basic
-can set it up. After we have succeeded in @ref{Getting mail}, and
+setup. After we have succeeded in @ref{Getting mail}, and @ref{Indexing your
-@ref{Indexing your messages}, we discuss @ref{Basic configuration}.
+messages}, we discuss @ref{Basic configuration}.
 
-After these steps, @t{mu4e} should be ready to go.
+After these steps, @t{mu4e} should be ready to go!
 
 @menu
 * Installation:: How to install @t{mu} and @t{mu4e}
@@ -192,6 +193,7 @@ After these steps, @t{mu4e} should be ready to go.
 * Indexing your messages:: Creating and maintaining the index
 * Basic configuration:: Settings for @t{mu4e}
 * Folders::  Setting up standard folders
+* Retrieval and indexing:: Doing it from mu4e
 * Sending mail:: How to send mail
 * Running mu4e:: Overview of the @t{mu4e} views
 
@@ -201,8 +203,8 @@ After these steps, @t{mu4e} should be ready to go.
 @section Installation
 
 @t{mu4e} is part of @t{mu} - by installing the latter, the former is installed
-as well. Note, some distributions provide packaged versions of
+as well. Some Linux distributions provide packaged versions of
-@t{mu}/@t{mu4e}; if you can use those, there's no need to compile anything
+@t{mu}/@t{mu4e}; if you can use those, there is no need to compile anything
 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.
 
@@ -210,13 +212,17 @@ First, you need make sure you have the necessary dependencies. On a Debian or
 Ubuntu system, you can get these with:
 
 @example
-sudo apt-get install libgmime-2.4-dev libxapian-dev
+sudo apt-get install libgmime-2.6-dev libxapian-dev
-# emacs if you don't have it yet, mu4e works with GNU-Emacs 23 and 24
+# 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
+
 # optional
 sudo apt-get install guile-2.0-dev html2text xdg-utils
-# optional: only needed for msg2pdf
+
+# optional: only needed for msg2pdf and mug (toy gtk+ frontend)
 sudo apt-get install libwebkit-dev
 @end example
 
@@ -231,12 +237,14 @@ $./configure && make
 $ sudo make install
 @end example
 
-Alternatively, if you build from the git repository, or use a tarball like the
+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
 require you to have @t{autotools} installed):
 
 @example
 # get from git, or from a github tarball
+# git clone git://github.com/djcb/mu.git 
+
 $ cd mu-<version>
 $ autoreconf -i && ./configure && make
 $ sudo make install
@@ -244,50 +252,36 @@ $ sudo make install
 
 After this, @t{mu} and @t{mu4e} should be installed @footnote{there's a hard
 dependency between versions of @t{mu4e} and @t{mu} - you cannot combine
-different versions}, and be available from the command line and emacs
+different versions} on your system, and be available from the command line and
-(respectively).
+emacs.
 
-You may need to restart @t{emacs}.
+You may need to restart @t{emacs}, so it can find @t{mu4e} in its
+@code{load-path}.
 
 @subsection mu4e and emacs customization
 
 There is @emph{experimental} support for using the @t{emacs} customization
 system in @t{mu4e}, but for now, we recommend setting the values
-manually. Please refer to @ref{Example configuration} for a couple of
+manually. Please refer to @ref{Example configuration} for a couple of examples
-examples of this.
+of this.
 
 @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. If you are already using Maildirs,
+your e-mail messages stored in a Maildir - a specific directory structure with
-you are lucky; otherwise, you need to get your mail there in some way.
+one-file-per-message. If you are already using Maildirs, you are lucky;
+otherwise, you need to get your mail there in some way.
 
-If you are using some external @abbr{IMAP} or @abbr{POP} server, you can use
+If you are using an @abbr{IMAP} or @abbr{POP} server, you can use tools like
-tools like @t{getmail}, @t{fetchmail} @t{offlineimap} or @t{isync} to download
+@t{getmail}, @t{fetchmail}, @t{offlineimap} or @t{isync} to download your
-your message into a maildir-directory (@file{~/Maildir}, usually). If you are
+message into a maildir (@file{~/Maildir}, usually). If you are using a local
-using a local mail-server (such as @emph{Postfix} or @t{qmail}), you can teach
+mail-server (such as @emph{Postfix} or @t{qmail}), you can teach them to
-them to deliver into a maildir as well, maybe in combination with
+deliver into a maildir as well, maybe in combination with @t{procmail}. A bit
-@t{procmail}. A bit of googling should be able to provide you with the
+of googling should be able to provide you with the detail. Because it is a
-details; also there is full example of setting @t{mu4e} up with
+rather common case, there is a full example of setting @t{mu4e} up with
 @t{offlineimap} and Gmail; @pxref{Gmail configuration}.
 
-You can do all of the mail retrieval @emph{outside} of @t{emacs}/@t{mu4e}, but
-you can also do it from within @t{mu4e}. For that, set the variable
-@code{mu4e-get-mail-command} to the program or shell command you want to use
-for retrieving mail. You can then retrieve your e-mail from the @ref{Main
-view}.
-
-You can also have this command run periodically in the background, by setting
-the variable @code{mu4e-update-interval} to the number of seconds between
-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.
-
-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}.
-
 @node Indexing your messages
 @section Indexing your messages
 
@@ -361,6 +355,35 @@ runtime. This allows for dynamically changing them depending on context. See
 are all relative to @code{mu4e-maildir}. The next step is telling @t{mu4e} how
 we want to send mail.
 
+@node Retrieval and indexing
+@section Retrieval and indexing
+
+As we have seen, we can do all of the mail retrieval @emph{outside} of
+@t{emacs}/@t{mu4e}. However, you can also do it from within @t{mu4e}. For
+that, set the variable @code{mu4e-get-mail-command} to the program or shell
+command you want to use for retrieving mail. You can then retrieve your e-mail
+from the @ref{Main view}. You can also set the shell command to @t{"true"}, in
+which case @t{mu4e} won't try to get new mail, but still re-index your
+messages.
+
+You can also have this command run periodically in the background, by setting
+the variable @code{mu4e-update-interval} to the number of seconds between
+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:
+
+@lisp
+(setq 
+   mu4e-get-mail-command "offlineimap"   ;; or fetchmail, or ...
+   mu4e-update-interval 300)             ;; update every 5 minutes
+@end lisp
+
+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}.
+
 @node Sending mail
 @section Sending mail
 
@@ -388,17 +411,18 @@ 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}.
 
 By default, @t{mu4e} puts a copy of any messages you sent in the folder you
-set for @code{mu4e-sent-folder}. In some case, this may not be what you want -
+set for @code{mu4e-sent-folder}.  some case, this may not be what you want -
-for example, when using Gmail+@abbr{IMAP} (but @emph{not} with
+for example, when using Gmail-over-@abbr{IMAP} (but @emph{not} with
-Gmail+@abbr{POP3}), this interferes with Gmail's handling of the sent messages
+Gmail-overo-@abbr{POP3}), this interferes with Gmail's handling of the sent
-folder, and you may end up with duplicate messages.
+messages folder, and you may end up with duplicate messages.
 
-Since @t{mu4e} 0.9.8.3, there is the variable
+You can use the the variable @code{mu4e-sent-messages-behavior} (which takes a
-@code{mu4e-sent-messages-behavior} for, which takes a symbol. The default is
+symbol) to customize what happens with sent messages. The default is
-@code{'sent} which, as mentioned, causes the message to be copied to your
+@code{sent} which, as mentioned, causes the message to be copied to your
-sent-messages folder. Other possible values are @code{'trash} (so the sent
+sent-messages folder. Other possible values are @code{'trash} (the sent
-message is copied to the trash-folder (@code{mu4e-trash-folder}), and
+message is moved to the trash-folder (@code{mu4e-trash-folder}), and
-@code{'delete} to simply discard the message altogether.
+@code{'delete} to simply discard the sent message altogether (so GMail can
+deal with it).
 
 For Gmail-IMAP, you could add the following to your settings:
 
@@ -407,7 +431,7 @@ 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 be ready to go now.
+And that's it! We should now be ready to go now.
 
 @node Running mu4e
 @section Running mu4e
@@ -1746,6 +1770,10 @@ put something like the following in your setup:
       (t  "/archive"))))
 @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
+refile folders.
+
 Some notes:
 @itemize
 @item we set @code{mu4e-refile-folder} to an anonymous (@t{lambda}) function. This
@@ -1764,7 +1792,7 @@ 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
-the @emph{original} message, that is, the message you reply to, or forward. If
+qthe @emph{original} message, that is, the message you reply to, or forward. If
 there is no such message (for example when composing a new message) the
 message parameter is @t{nil}.
 
@@ -1779,6 +1807,21 @@ work-email. You can do so with something like the following:
         "/trash-private")))
 @end lisp
 
+Good to remember:
+@itemize
+@item The @code{msg} parameter you receive in the function refers to the
+@emph{original message}, that is, the message being replied to or
+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
+
 
 @node Actions
 @chapter Actions