alx/mu4e
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

* improve documentation

Browse Source
This commit is contained in:
djcb
2012-04-24 22:37:50 +03:00
parent 5ce21d4e43
commit 35fd83ac59
1 changed files with 169 additions and 141 deletions
Download Patch File Download Diff File Expand all files Collapse all files

310
emacs/mu4e.texi
View File

@ -34,10 +34,17 @@ Documentation License.''
Welcome to @t{mu4e}! Welcome to @t{mu4e}!
@t{mu4e} (@emph{mu-for-emacs}) is an e-mail client for GNU Emacs (version 23 @t{mu4e} (mu-for-emacs) is an e-mail client for GNU-Emacs version 23 and
and later). It is built on top of the @t{mu} e-mail search engine. This manual later. It is built on top of the @t{mu} e-mail search engine, and it focuses
describes how to install and use @t{mu4e}. on quickly dealing with large amounts of e-mail.
This manual goes through the installation of @t{mu4e}, discusses the basic
configuration, and explains the daily use. It also shows how you can customize
@t{mu4e} for your needs.
At the end of the manual, there are a number of example configurations, which
should help you to get up to speed quickly.
This manual has been updated for @t{mu}/@t{mu4e} version This manual has been updated for @t{mu}/@t{mu4e} version
@emph{@value{mu4e-version}}. @emph{@value{mu4e-version}}.
@ -61,26 +68,26 @@ Appendices
@node Introduction @node Introduction
@chapter Introduction @chapter Introduction
In this chapter some prelimary thoughs about the how and why of @t{mu4e}. Let's get started!
@menu @menu
* Why another e-mail client?:: * Why another e-mail client?::
* Other mail clients:: * Other mail clients::
* What mu4e does and doesn't do:: * What mu4e does and does not do::
@end menu @end menu
@node Why another e-mail client? @node Why another e-mail client?
@section Why another e-mail client? @section Why another e-mail client?
Why would the world need another e-mail client? Well, I'm not sure the world Why does the world need another e-mail client? Well, I'm not sure the world
really @emph{needs} another one, but maybe @emph{I} do! I spend a @emph{lot} @emph{needs} another one, but maybe @emph{I} do! I spend a @emph{lot} of time,
of time, professionally and privately, dealing with e-mail -- having an professionally and privately, dealing with e-mail and therefore, having an
efficient e-mail client is essential for me. Since none of the existing ones efficient e-mail client is essential for me. Since none of the existing ones
worked they I wanted, I created my own. worked the way I wanted, I created my own.
Still, while having been created for such selfish motives, @t{mu4e} tries Even while having been created for such selfish motives, @t{mu4e} tries hard
hard to be as useful as possible for all its users - suggestions are very to be as useful as possible for all its users - suggestions are very welcome
welcome and are acted upon. and are acted upon.
@node Other mail clients @node Other mail clients
@section Other mail clients @section Other mail clients
@ -89,53 +96,55 @@ Under the hood, @t{mu4e} is fully search-based, similar to programs such as
@t{notmuch}@footnote{@url{http://notmuchmail.org}}, @t{notmuch}@footnote{@url{http://notmuchmail.org}},
@t{md}@footnote{@url{https://github.com/nicferrier/md}} and @t{md}@footnote{@url{https://github.com/nicferrier/md}} and
@t{sup}@footnote{@url{http://sup.rubyforge.org/}}. The user-interface is quite @t{sup}@footnote{@url{http://sup.rubyforge.org/}}. The user-interface is quite
different though. different.
@t{mu4e}'s mail handling (deleting, moving etc.) is inspired by @t{mu4e}'s mail handling (deleting, moving etc.) is inspired by
@emph{Wanderlust}@footnote{@url{http://www.gohome.org/wl/}} (another @emph{Wanderlust}@footnote{@url{http://www.gohome.org/wl/}} (another
emacs-based e-mail client), @t{mutt}@footnote{@url{http://www.mutt.org/}} and emacs-based e-mail client), @t{mutt}@footnote{@url{http://www.mutt.org/}} and
@t{dired}, while it takes some cues from @emph{GMail}. @t{dired}, while it takes some cues from @emph{GMail}.
@t{mu4e} tries to keep all the 'state' in your maildirs, so one can switch @t{mu4e} tries to keep all the 'state' in your maildirs, so you can easily
between clients, synchronize over @abbr{IMAP} or backup with @t{rsync} -- if switch between clients, synchronize over @abbr{IMAP} or backup with @t{rsync}
you delete the database, you won't lose any information. -- if you delete the database, you won't lose any information.
@node What mu4e does and doesn't do @node What mu4e does and does not do
@section What mu4e does and doesn't do @section What mu4e does and does not do
@t{mu}, and, by extension, @t{mu4e}, do @emph{not} deal with getting your @t{mu}, and, by extension, @t{mu4e}, do @emph{not} deal with getting your
e-mail messages from a mail server; instead, this task is delegated to other e-mail messages from a mail server. That task is delegated to other tools,
tools, such as @t{offlineimap}@footnote{@url{http://offlineimap.org/}}, such as @t{offlineimap}@footnote{@url{http://offlineimap.org/}},
@t{isync}@footnote{@url{http://isync.sourceforge.net/}} or @t{isync}@footnote{@url{http://isync.sourceforge.net/}} or
@t{fetchmail}@footnote{@url{http://www.fetchmail.info/}}. As long as the @t{fetchmail}@footnote{@url{http://www.fetchmail.info/}}. As long as the
messages end up in a Maildir, @t{mu4e}/@t{mu} are happy to deal with them. messages end up in a Maildir, @t{mu4e}/@t{mu} are happy to deal with them.
@t{mu4e} also does @emph{not} implement sending messages; instead, it depends @t{mu4e} also does @emph{not} implement sending of messages; instead, it
on the true-and-tested @emph{smtpmail}, which is part of @t{emacs}. In depends on the true-and-tested @emph{smtpmail}, which is part of @t{emacs}. In
addition, @t{mu4e} piggybacks on Gnus' message editor; @inforef{Top,Gnus addition, @t{mu4e} piggybacks on Gnus' message editor; @inforef{Top,Gnus
message editor,message}. message editor,message}.
Thus, many of the traditional things an e-mail client needs to do, are Thus, many of the traditional things an e-mail client needs to do, are
subcontracted to other tools. This leaves @t{mu4e} to concentrate on what it subcontracted to other tools. This leaves @t{mu4e} to concentrate on what it
does best: quick message searching, reading mails, replying them, moving does best: quickly getting you the mails you looking for, and handle them as
messages around and so on. efficiently as possible.
@node Getting started @node Getting started
@chapter Getting started @chapter Getting started
In this chapter, we go through installing @t{mu4e} and see how to set it In this chapter, we go through the installation of @t{mu4e} and show how you
up. After we have succeeded in @ref{Getting mail}, and @ref{Indexing your can set it up. After we have succeeded in @ref{Getting mail}, and
messages}, we discuss @ref{Basic configuration}. @ref{Indexing your messages}, we discuss @ref{Basic configuration}.
After going through these steps, @t{mu4e} should be ready for use. After these steps, @t{mu4e} should be ready to go.
@menu @menu
* Installation:: * Installation::
* Getting mail:: * Getting mail::
* Indexing your messages:: * Indexing your messages::
* Sending mail::
* Queuing mail::
* Basic configuration:: * Basic configuration::
* Folders::
* Sending mail::
@end menu @end menu
@node Installation @node Installation
@ -169,7 +178,9 @@ $ sudo make install
After this, @t{mu} and @t{mu4e} should be installed @footnote{there's a hard 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 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.}, and be available from the command line and emacs
(respectively). You may need to restart @t{emacs} so it can pick up @t{mu4e}. (respectively).
You may need to restart @t{emacs}.
@subsection mu4e and emacs customization @subsection mu4e and emacs customization
@ -177,7 +188,7 @@ There is @emph{experimental} support for using the @t{emacs} customization
system in @t{mu4e}, but for now we recommend setting the values system in @t{mu4e}, but for now we recommend setting the values
manually. Please refer to @ref{Example configuration} for a couple of examples manually. Please refer to @ref{Example configuration} for a couple of examples
of this. of this.
@node Getting mail @node Getting mail
@section Getting mail @section Getting mail
@ -186,24 +197,25 @@ e-mail messages stored in a Maildir. If you were already using Maildirs, you
are lucky; otherwise, you will need to get your mail there in some way. are lucky; otherwise, you will 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 some external @abbr{IMAP} or @abbr{POP} server, you can use
tools like @t{getmail}, @t{offlineimap} or @t{isync} to download your message tools like @t{getmail}, @t{fetchmail} @t{offlineimap} or @t{isync} to download
into a Maildir-directory (@file{~/Maildir}, usually). If you are using a local your message into a maildir-directory (@file{~/Maildir}, usually). If you are
mail-server (such as @emph{Postfix} or @t{qmail}), you can teach them to using a local mail-server (such as @emph{Postfix} or @t{qmail}), you can teach
deliver into a Maildir as well, maybe in combination with @t{procmail}. A bit them to deliver into a maildir as well, maybe in combination with
of googling should be able to provide you with the details; also there is full @t{procmail}. A bit of googling should be able to provide you with the
example of setting @t{mu4e} up with @t{offlineimap} and Gmail; @pxref{Gmail details; also there is full example of setting @t{mu4e} up with
configuration}. @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 do all of the mail retrieval @emph{outside} of @t{emacs}/@t{mu4e}, but
you can also do it from the @t{mu4e}. For that, set the variable you can also do it from within @t{mu4e}. For that, set the variable
@code{mu4e-get-mail-command} to the command you want to use for retrieving @code{mu4e-get-mail-command} to the program or shell command you want to use
mail, which you can then access from the @ref{Main view}. 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 You can also have this command run periodically in the background, by setting
setting the variable @code{mu4e-update-interval} to the number of seconds the variable @code{mu4e-update-interval} to the number of seconds between
between such updates. If set to @code{nil}, it will not update at all. Note these updates. If set to @code{nil}, it will not update at all. If you make
that if you make changes to @code{mu4e-update-interval}, @code{mu4e} must be changes to @code{mu4e-update-interval}, @code{mu4e} must be restarted before
restarted before the change will take effect. the change will take effect.
@node Indexing your messages @node Indexing your messages
@section Indexing your messages @section Indexing your messages
@ -211,8 +223,8 @@ restarted before the change will take effect.
After you have succeeded in @ref{Getting mail}, we need to @emph{index} the 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 Maildir and store the information
about the mails into a special database. We can do that from @code{mu4e} -- about the mails into a special database. We can do that from @code{mu4e} --
@ref{Main view}, but this first time, it's better to run it from the command @ref{Main view}, but the first time, it is better to run it from the command
line, as it may be easier to recognize problems. line, as it is easier to recognize any problems that might occur.
Assuming that your Maildir is at @file{~/Maildir}, you should give the Assuming that your Maildir is at @file{~/Maildir}, you should give the
following command: following command:
@ -223,32 +235,68 @@ following command:
This should scan your @file{~/Maildir}@footnote{In most cases, you do not even This should scan your @file{~/Maildir}@footnote{In most cases, you do not even
have to provide the @t{--maildir=~/Maildir}; see the @t{mu-index} man-page for have to provide the @t{--maildir=~/Maildir}; see the @t{mu-index} man-page for
details} and fill the database, and give progress information while doing details} and fill the database, and give progress information while doing
so. The first time you index your mail may take a few minutes (for thousands so.
of e-mails), afterwards it is much faster since it only has to scan the
differences.
Note that indexing is discussed at length in the @t{mu-index} man page. 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 it only has to scan
the differences. Indexing is discussed in more detail in 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
After the indexing is finished, you can quickly test if everything worked, by
trying some command line searches, for example
@example @example
$ mu find hello $ mu find hello
@end example @end example
which should list all messages that match @t{hello}. For some more examples of
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. searches @xref{Queries}, or check the @t{mu-find} and @t{mu-easy} man pages.
If all of this worked well, we are almost ready to start @t{mu4e}; we only If all of this worked well, we are well on our way setting up @t{mu4e}; the
need set up @ref{Sending mail}. next step is to do some basic configuration.
@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
maildir folders.
So, add to your @file{~/.emacs} (or equivalent) something like:
@example
(require 'mu4e)
@end example
@node Folders
@section Folders
The next step is to tell @t{mu4e} where it can find your Maildir, and some
special folders. So, for example:
@lisp
(setq
mu4e-maildir "~/Maildir" ;; top-level Maildir
mu4e-sent-folder "/sent" ;; where do i keep sent mail?
mu4e-drafts-folder "/drafts" ;; where do i keep half-written mail?
mu4e-trash-folder "/trash") ;; where do i move deleted mail?
@end lisp
@code{mu4e-maildir} take an actual filesystem-path, the other folder names are
all relative to @code{mu4e-maildir}. The next step is telling @t{mu4e} how we
want to send mail.
@node Sending mail @node Sending mail
@section Sending mail @section Sending mail
@t{mu4e} re-uses Gnu's @t{message mode} @inforef{message}, for writing
mail and inherits the setup for @emph{sending} mail from that.
For sending mail using @abbr{SMTP}, @t{mu4e} uses Emacs' standard @t{smtpmail} @t{mu4e} re-uses Gnu's @inforef{Top,,message}, for writing mail and inherits
package -- @inforef{smtpmail}. This package support many different ways to the setup for @emph{sending} mail from that.
send mail, please refer to its documentation for the details. Here we only
provide some simple examples - and @ref{Example configuration}. For sending mail using @abbr{SMTP}, @t{mu4e} uses
@inforef{Top,,smtpmail}. This package support many different ways to send
mail, please refer to its documentation for the details.
Here, we only provide some simple examples - for more, @ref{Example
configuration}.
A very minimal setup could look something like: A very minimal setup could look something like:
@ -260,91 +308,30 @@ A very minimal setup could look something like:
(setq smtpmail-smtp-server "smtp.example.org") (setq smtpmail-smtp-server "smtp.example.org")
@end lisp @end lisp
Note, since @t{mu4e} uses the same @t{message mode} and @t{smtpmail} Since @t{mu4e} uses the same @t{message mode} and @t{smtpmail} that Gnus uses,
that Gnus uses, any setting for those will also work for @t{mu4e}. many setting for those will also apply to @t{mu4e}.
By default, @t{mu4e} puts a copy of any messages you sent in the folder you 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}. In 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+@abbr{IMAP} (but @emph{not} with
GMail+@abbr{POP3}), this interferes with GMail's handling of the sent messages GMail+@abbr{POP3}), this interferes with GMail's handling of the sent messages
folder, and you may end up with duplicate messages. For this, since @t{mu4e} folder, and you may end up with duplicate messages.
0.9.8.3, there is the variable @code{mu4e-sent-messages-behavior}, which takes
a symbol. The default is @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 message is copied to the trash-folder
(@code{mu4e-trash-folder}), and @code{'delete} to simply discard the message
altogether.
Thus, for GMail-IMAP you can add the following to your settings: For this, since @t{mu4e} 0.9.8.3, there is the variable
@code{mu4e-sent-messages-behavior}, which takes a symbol. The default is
@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
message is copied to the trash-folder (@code{mu4e-trash-folder}), and
@code{'delete} to simply discard the message altogether.
For GMail-IMAP you could add the following to your settings:
@verbatim @verbatim
;; don't save message to Sent Messages, GMail/IMAP will take care of this ;; don't save message to Sent Messages, GMail/IMAP will take care of this
(setq mu4e-sent-messages-behavior 'trash) (setq mu4e-sent-messages-behavior 'trash)
@end verbatim @end verbatim
And that's it! We should be ready to go now.
@node Queuing mail
@section Queuing mail
If you cannot send mail directly, for example because you are currently
offline, you can @emph{queue} the mail, and send it when you have restored
your internet connection. You can control this from the @t{mu4e} @xref{Main
view}.
To allow for queuing, you need to tell @t{smtpmail} where you want to do
this. For example:
@lisp
(setq
smtpmail-queue-mail nil ;; start in non-queuing mode
smtpmail-queue-dir "~/Maildir/queue/cur")
@end lisp
For convenience, we locate the queue directory somewhere in our normal
Maildir. If you want to use queued mail, you should create this directory
before starting @t{mu4e}. The @command{mu mkdir} command can be handy here,
so for example:
@verbatim
$ mu mkdir ~/Maildir/queue
$ touch ~/Maildir/queue/.noindex
@end verbatim
The @command{touch} command tells @t{mu} to ignore this directory for
indexing, which makes sense since it contains @t{smtpmail} meta-data rather
than 'normal' messages.
Also, see the @t{mu-mkdir} and @t{mu-index} man pages.
@emph{Warning}: when you switch on queued-mode, your messages will not reach
their destination until you switch it off again; so, be careful not to do so
accidentally.
@node Basic configuration
@section Basic configuration
The last thing to do before running @t{mu4e} is setting up some basic
configuration. A good place to put this would be in your @file{~/.emacs} file.
First some more extensive configuration, @xref{Example configuration}.
First, we need to load @t{mu4e}:
@example
(require 'mu4e)
@end example
Then, we need to tell @t{mu4e} where it can find your Maildir, and some
special folders. So, for example:
@lisp
(setq
mu4e-maildir "~/Maildir" ;; top-level Maildir
mu4e-sent-folder "/sent" ;; where do i keep sent mail?
mu4e-drafts-folder "/drafts" ;; where do i keep half-written mail?
mu4e-trash-folder "/trash") ;; where do i move deleted mail?
@end lisp
@code{mu4e-maildir} take an actual filesystem-path, the other folder names are
all relative to @code{mu4e-maildir}.
@node Running mu4e @node Running mu4e
@ -466,7 +453,7 @@ database; @pxref{Indexing your messages}. See @ref{Getting mail} for details.
@item @t{toggle [m]ail sending mode (direct)} will toggle between sending @item @t{toggle [m]ail sending mode (direct)} will toggle between sending
mail directly, and queuing it first (for example, when you are offline), and mail directly, and queuing it first (for example, when you are offline), and
@t{[f]lush queued mail} will flush any queued mail. This item is visible only @t{[f]lush queued mail} will flush any queued mail. This item is visible only
if you have actually set up mail-queuing. @xref{Queuing mail}. if you have actually set up mail-queuing. @ref{Queuing mail}.
@item @t{[H]elp} will show help information for this view. @item @t{[H]elp} will show help information for this view.
@item Finally, @t{[q]uit mu4e} will quit @t{mu4e}. @item Finally, @t{[q]uit mu4e} will quit @t{mu4e}.
@end itemize @end itemize
@ -533,6 +520,8 @@ d mark for moving to the trash folder
DEL,D mark for immediate deletion DEL,D mark for immediate deletion
m mark for moving to another maildir folder m mark for moving to another maildir folder
u unmark message at point u unmark message at point
% mark based on a regular expression
R,F,C reply/forward/compose R,F,C reply/forward/compose
E edit (only allowed for draft messages) E edit (only allowed for draft messages)
@ -685,6 +674,8 @@ d mark for moving to the trash folder
DEL,D mark for immediate deletion DEL,D mark for immediate deletion
m mark for moving to another maildir folder m mark for moving to another maildir folder
u unmark message at point u unmark message at point
% mark based on a regular expression
R,F,C reply/forward/compose R,F,C reply/forward/compose
E edit (only allowed for draft messages) E edit (only allowed for draft messages)
@ -824,6 +815,43 @@ If you want use @t{mu4e} as the default program for sending mail, please see
other interesting topics: @ref{Citations with mu-cite} and @ref{Maintaining an other interesting topics: @ref{Citations with mu-cite} and @ref{Maintaining an
address-book with org-contacts}. address-book with org-contacts}.
@subsection Queuing mail
@anchor{Queuing mail}
If you cannot send mail directly, for example because you are currently
offline, you can @emph{queue} the mail, and send it when you have restored
your internet connection. You can control this from the @t{mu4e} @ref{Main
view}.
To allow for queuing, you need to tell @t{smtpmail} where you want to do
this. For example:
@lisp
(setq smtpmail-queue-mail nil ;; start in non-queuing mode
smtpmail-queue-dir "~/Maildir/queue/cur")
@end lisp
For convenience, we locate the queue directory somewhere in our normal
maildir. If you want to use queued mail, you should create this directory
before starting @t{mu4e}. The @command{mu mkdir} command may be useful here,
so for example:
@verbatim
$ mu mkdir ~/Maildir/queue
$ touch ~/Maildir/queue/.noindex
@end verbatim
The file created by the @command{touch} command tells @t{mu} to ignore this
directory for indexing, which makes sense since it contains @t{smtpmail}
meta-data rather than 'normal' messages; see the @t{mu-mkdir} and @t{mu-index}
man pages for details.
@emph{Warning}: when you switch on queued-mode, your messages will not reach
their destination until you switch it off again; so, be careful not to do this
accidentally.
@node Searching @node Searching
@chapter Searching @chapter Searching
@ -1162,7 +1190,7 @@ elsewhere - both are typically bound to @kbd{C-c C-o}.
To manage your addresses using @t{org-mode}, there is To manage your addresses using @t{org-mode}, there is
@t{org-contacts}@footnote{@url{http://julien.danjou.info/software/org-contacts.el}}. @t{org-contacts}@footnote{@url{http://julien.danjou.info/software/org-contacts.el}}.
@t{mu4e-actions} defines a useful action (@xref{Actions}) for this to add a @t{mu4e-actions} defines a useful action (@ref{Actions}) for this to add a
contact based on the @t{From:}-address in the current mail (current header or contact based on the @t{From:}-address in the current mail (current header or
view). To enable this, add to your configuration something like: view). To enable this, add to your configuration something like:
@ -1729,7 +1757,7 @@ using @code{M-x mu4e-show-log}.
@node The message s-expression @node The message s-expression
@section The message s-expression @section The message s-expression
A typical message s-expression could look something like the following: A typical message s-expression looks something like the following:
@lisp @lisp
(:docid 32461 (:docid 32461