* mu4e: documentation updates (WIP)

This commit is contained in:
djcb
2011-12-19 09:07:03 +02:00
parent 5307a8411b
commit b67a8e86a0

View File

@ -25,67 +25,85 @@ Texts.
@node Top @node Top
@top mu4e Manual @top mu4e Manual
@emph{Mu-For-Emacs} (or for short, @command{mu4e}), is an @command{emacs} based @emph{Mu-For-Emacs} (or for short, @samp{mu4e}), is an @samp{emacs} based
e-mail client, based on the @command{mu} e-mail search engine. @command{mu4e} e-mail client, based on the @samp{mu} e-mail search engine. @samp{mu4e}
supports GNU Emacs 23 and later. supports GNU Emacs 23 and later.
@menu @menu
* Introduction:: * Introduction::
* Getting started:: * Getting started::
* Running mu4e:: * Running mu4e::
@c * Getting mail:: * Searching mail::
@c * Searching mail::
@c * Reading mail::
@c * Processing mail::
@c * Sending mail::
* Example configuration:: * Example configuration::
* FAQ - Frequently Anticipated Questions::
* Known issues / missing features::
@end menu @end menu
@node Introduction @node Introduction
@chapter Introduction @chapter Introduction
@command{mu4e} is an e-mail program for GNU Emacs; it uses the @command{mu} @samp{mu4e} is an e-mail program for GNU Emacs; it uses the @samp{mu}
e-mail search engine as its backend, making @command{mu} fully search-based. e-mail search engine as its backend, making @samp{mu} fully search-based.
@command{mu4e} (and @command{mu}) does @emph{not} deal with getting your @menu
* Background::
* Acknowledgments::
@end menu
@node Background
@section Background
@samp{mu4e} (and @samp{mu}) does @emph{not} deal with getting your
e-mail messages from some e-mail server; instead, this task is delegated to e-mail messages from some e-mail server; instead, this task is delegated to
other tools, such as @command{offlineimap}. As long as the messages end up in other tools, such as @samp{offlineimap}. As long as the messages end up in
a Maildir, @command{mu4e}/@command{mu} are happy to deal with them. a Maildir, @samp{mu4e}/@samp{mu} are happy to deal with them.
@command{mu4e} does @emph{not} implement sending messages either; instead, it @samp{mu4e} does @emph{not} implement sending messages either; instead, it
depends on the true-and-tested @emph{smtpmail} which is part of emacs. In depends on the true-and-tested @emph{smtpmail} which is part of emacs. In
fact, @command{mu4e} piggybacks on @ref{Top, Gnus} for its message editor. fact, @samp{mu4e} piggybacks on Gnu's message editor; @inforef{Top,Gnus
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 @command{mu4e} to concentrate on subcontracted to other tools. This leaves @samp{mu4e} to concentrate on
what it does best: quick message searching, reading mails, replying them, what it does best: quick message searching, reading mails, replying them,
moving messages around and so on. moving messages around and so on.
It's important to note the @command{mu4e} requires your mail to be in It's important to note the @samp{mu4e} requires your mail to be in
Maildir-format, typically stored in @file{~/Maildir}. Maildir-format, typically stored in @file{~/Maildir}.
@c @section Acknowledgments @node Acknowledgments
@section Acknowledgments
@command{mu} has been helped tremendously by users who helped to isolate and fix @samp{mu} has been helped tremendously by users who helped to isolate and fix
bugs, and (maybe even more so) by providing suggestions. Thanks to all! bugs, and (maybe even more so) by providing suggestions. Thanks to all!
@command{mu4e} has taken inspiration from many places. First, there are @command{sup} @samp{mu4e} has taken inspiration from many places. First, there are @samp{sup}
and @command{notmuch} which showed that one can write a search-based e-mail and @samp{notmuch} which showed that one can write a search-based e-mail
client. Aspects of the Wanderlust e-mail client can be seen in the UI, as well client. Aspects of the Wanderlust e-mail client can be seen in the UI, as well
as the @command{dired} interaction model. as the @samp{dired} interaction model.
@node Getting started @node Getting started
@chapter Getting started @chapter Getting started
Getting started. In this chapter, we will see how you can install @samp{mu4e} and how you can
set it up. After we have succeeded in @xref{Getting mail}, and @xref{Indexing
your messages}, we discuss @xref{Basic configuration}. After going through
these steps, @samp{mu4e} should be ready for use.
@menu
* Installation::
* Getting mail::
* Indexing your messages::
* Basic configuration::
@end menu
@c @section Installation @node Installation
@section Installation
@command{mu4e} is part of @command{mu} - by installing the latter, the former will @samp{mu4e} is part of @samp{mu} - by installing the latter, the former will
be installed as well. be installed as well.
At the time of writing, there are no distribution packages for @command{mu4e} At the time of writing, there are no distribution packages for @samp{mu4e}
yet, so we are assuming installation from source packages. yet, so we are assuming installation from source packages.
Installation follows the normal sequence of: Installation follows the normal sequence of:
@ -96,36 +114,36 @@ $./configure && make
$ sudo make install $ sudo make install
@end example @end example
After this, @command{mu} and @command{mu4e} should be After this, @samp{mu} and @samp{mu4e} should be installed @footnote{there's a
installed @footnote{there's a hard dependency between versions of hard dependency between versions of @samp{mu4e} and @samp{mu} - you cannot
@command{mu4e} and @command{mu} - you cannot combine different versions.}, a combine different versions.}, a be available from the command line and emacs
be available from the command line and emacs (respectively). For emacs, you (respectively). For emacs, you may to restart it so it can pick up
may to restart it so it can pick up @command{mu4e}. @samp{mu4e}.
There is experimental support for using the @command{emacs} customization There is experimental support for using the @samp{emacs} customization
system in @command{mu4e}, but for now we recommend setting the values by system in @samp{mu4e}, but for now we recommend setting the values by
manually. Please @ref{Example configuration} for a working example of this. manually. Please @ref{Example configuration} for a working example of this.
@c @node Getting mail @node Getting mail
@c @section Getting mail @section Getting mail
In order for @command{mu} (and by extension, @command{mu4e}) to work, we need In order for @samp{mu} (and by extension, @samp{mu4e}) to work, we need
to have our e-mail stored in a Maildir. If you were already using Maildirs, to have our e-mail stored in a Maildir. If you were already using Maildirs,
your lucky, otherwise you will need to get your mail there in some other way. your lucky, otherwise you will need to get your mail there in some other way.
If you are using some external @acronym{IMAP} or @acronym{POP} server, you can If you are using some external @acronym{IMAP} or @acronym{POP} server, you can
use tools like @command{getmail} and @command{offlineimap} to download your use tools like @samp{getmail} and @samp{offlineimap} to download your
message into a Maildir-directory (@file{~/Maildir}, usually). If you are using message into a Maildir-directory (@file{~/Maildir}, usually). If you are using
a local mailserver (such as Postfix or @command{qmail}), you can teach them to a local mailserver (such as Postfix or @samp{qmail}), you can teach them to
deliver into a Maildir as well, maybe in combination with @command{qmail}. deliver into a Maildir as well, maybe in combination with @samp{qmail}.
For the exact details on how to do this, please consult the documentation of For the exact details on how to do this, please consult the documentation of
the products you are using. the products you are using.
@c @node Indexing your messages @node Indexing your messages
@c @section Indexing your messages @section Indexing your messages
@c @ref{Getting mail}
After you have succeeded in Getting mail, we need to @emph{index} After you have succeeded in @ref{Getting mail}, we need to @emph{index}
it. That is - we need to scan the Maildir and store the information about the it. 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}, but for now mails into a special database. We can do that from @code{mu4e}, but for now
it's better to do it from the command line, because it's easier to spot any it's better to do it from the command line, because it's easier to spot any
@ -142,32 +160,32 @@ progress information while doing so. The first time you index your mail might
take a few minutes (for thousands of e-mails), afterwards it is much faster take a few minutes (for thousands of e-mails), afterwards it is much faster
since it only has to scan the differences. since it only has to scan the differences.
Note that indexing is discussed at length in the @command{mu-index} man page. Note that indexing is discussed at length in the @samp{mu-index} man page.
After the indexing is finished, you can quickly test if everything worked, by After the indexing is finished, you can quickly test if everything worked, by
trying some command line searches, for example 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 "hello". The @command{mu-find} man which should list all messages that match "hello". The @samp{mu-find} man
page describes the various things you can do with @command{mu find}. page describes the various things you can do with @samp{mu find}.
If all of this worked well, we are almost ready to start @command{mu4e}. If all of this worked well, we are almost ready to start @samp{mu4e}.
@c @node Basic configuration @node Basic configuration
@c @section Basic configuration @section Basic configuration
The last thing to do before running @command{mu4e} is setting up some basic The last thing to do before running @samp{mu4e} is setting up some basic
configuration. A good place to put this would be in your @file{~/.emacs} file. configuration. A good place to put this would be in your @file{~/.emacs} file.
First, we need to load @command{mu4e}: First, we need to load @samp{mu4e}:
@example @example
(require 'mu4e) (require 'mu4e)
@end example @end example
Then, we need to tell @command{mu4e} where it can find your Maildir, and some Then, we need to tell @samp{mu4e} where it can find your Maildir, and some
special folders. So for example: special folders. So for example:
@example @example
(setq (setq
@ -179,9 +197,8 @@ special folders. So for example:
@end example @end example
The folder names are all relative to @code{mu4e-maildir}. The folder names are all relative to @code{mu4e-maildir}.
Without going into too much technical detail, here we describe the elements in Without going into too much technical detail, here we describe the elements in
a @command{mu4e}-setup, and how they work together. Using some ascii-art: a @samp{mu4e}-setup, and how they work together. Using some ascii-art:
@example @example
+---------+ +---------+
@ -205,49 +222,83 @@ So:
@itemize @itemize
@item Your e-mail messages are stored in a Maildir-directory (typically, @item Your e-mail messages are stored in a Maildir-directory (typically,
@file{~/Maildir}), and new mail comes in using tools like @command{fetchmail}, @file{~/Maildir}), and new mail comes in using tools like @samp{fetchmail},
@command{offlineimap} etc., or through a local mail servers (such as @samp{offlineimap} etc., or through a local mail servers (such as
@command{qmail} or @command{Postfix}). @samp{qmail} or @samp{Postfix}).
@item @command{mu} indexes these messages periodically, so you can quickly @item @samp{mu} indexes these messages periodically, so you can quickly
search for them. @command{mu} can run in a special @command{server}-mode, where it search for them. @samp{mu} can run in a special @samp{server}-mode, where it
provides services to client software. provides services to client software.
@item @command{mu4e}, which runs inside @command{emacs} is such a client; it @item @samp{mu4e}, which runs inside @samp{emacs} is such a client; it
communicates with @command{mu} to search for messages, and manipulate them. communicates with @samp{mu} to search for messages, and manipulate them.
@item @command{mu4e} uses the facilities offered by @command{emacs} (the @item @samp{mu4e} uses the facilities offered by @samp{emacs} (the
@command{Gnus} message editor and @command{smtpmail}) to send messages. @samp{Gnus} message editor and @samp{smtpmail}) to send messages.
@end itemize @end itemize
@example
+-----------+ +--------------+ +--------------+
| main view | <---> | headers view | <---> | message view |
+-----------+ +--------------+ +--------------+
|
+----------+
| raw view |
+----------+
@end example
@node Running mu4e @node Running mu4e
@chapter Running mu4e @chapter Running mu4e
After you've installed @command{mu4e} (@pxref{Getting started}), you can start it After the following the steps in @xref{Getting started}, we should now have a
working @samp{mu4e} setup. In this chapter, we'll give a tour of the
@samp{mu4e} programming, and show its use.
@samp{mu4e} consists of a number of views; the diagram shows how they relate
to eachother, and the default keybindings to from one view to the next. In the
next sections we will describe what these keys actually @emph{do}.
@menu
* Main view::
* Headers view::
* Message view::
* Editor view::
@end menu
@example
[C] +--------+ [RFCE]
--------> | editor | <--------
/ +--------+ \
/ [RFCE]^ \
/ | \
+-------+ [sjb] +---------+ [RET] +---------+
| main | <---> | headers | <----> | message |
+-------+ [q] +---------+ [qbjs] +---------+
[sbj] ^
[.] | [q]
V
+-----+
| raw |
+-----+
Default bindings
----------------
R: Reply s: search .: raw view
F: Forward j: jump-to-maildir
C: Compose b: bookmark-search
E: Edit q: quit
@end example
@node Main view
@section Main view
After you've installed @samp{mu4e} (@pxref{Getting started}), you can start it
with @code{M-x mu4e}. This will do some checks to ensure everything is set up with @code{M-x mu4e}. This will do some checks to ensure everything is set up
correctly, and then show the @command{mu4e} main view. correctly, and then show the @samp{mu4e} main view.
This looks something like the following:
@verbatim @verbatim
* mu4e - mu for emacs version 0.9.8pre * mu4e - mu for emacs version x.x
Basics Basics
* [j]ump to some maildir * [j]ump to some maildir
* enter a [s]earch query * enter a [s]earch query
* [c]ompose a new message * [C]ompose a new message
Bookmarks Bookmarks
@ -257,49 +308,191 @@ correctly, and then show the @command{mu4e} main view.
* [bp] Messages with images * [bp] Messages with images
Misc Misc
* [u]pdate email & database * [U]pdate email & database
* toggle [m]ail sending mode (direct) * toggle [m]ail sending mode (direct)
* [f]lush queued mail * [f]lush queued mail
* [q]uit mm * [H]elp
* [q]uit mu4e
@end verbatim @end verbatim
First, the @emph{Basics}: First, the @emph{Basics}:
@itemize @itemize
@item @code{[j]ump to some maildir} means that after pressing @key{j}, @item @samp{[j]ump to some maildir} means that after pressing @key{j},
@command{mu4e} will ask you for a maildir to jump to. @samp{mu4e} will ask you for a maildir to jump to. These are the maildirs you
set in @xref{Basic configuration}.
@item @samp{enter a [s]earch query} means that after pressing @key{s} you will
be asked for a search query, and after entering one, the results will be shown.
@item @samp{[C]ompose a new message} means that after pressing @key{C}, you
will be thrown you in a message-editing buffer, where you can write a new message.
@end itemize @end itemize
Next come the bookmarks. These are set in @code{mu4e-bookmarks}; what you see
in the above example are the @emph{default}, but you can add your own and/or
replace the default ones. See @xref{Bookmarks}.
Finally, there are some @emph{Misc} actions:
@itemize
@item @samp{[U]pdate email & database} will execute whatever is in
@code{mu4e-get-mail-command}, and afterwards update the @samp{mu}
database. This is a synchronous command.
@item @samp{toggle [m]ail sending mode (direct)} will toggle between sending
mail directly, and queuing it first (for example, when you are offline), and
@samp{[f]lush queued mail} will flush any queued mail.
@item @samp{[H]elp} will show help information for this view.
@item Finally, @samp{[q]uit mu4e} will quit @samp{mu4e}.
@end itemize
@node Headers view
@section Headers view
The headers view shows the results of search queries. There's one line for
each matching message, and each line shows a number of fields describing this
message.
@verbatim
* Date Flags From/To Subject
2011-12-16 18:38 uN To Edmund Dantès + Re: Extension security?
2011-12-16 21:44 uN Abbé Busoni + Re: Extension security?
2011-12-17 03:14 uN Pierre Morrel + Re: Extension security?
2011-12-17 04:04 uN Jacopo + Re: Extension security?
2011-12-17 14:36 uN Mercédès + Re: Extension security?
2011-12-18 06:05 uN Beachamp \ Re: Extension security?
2011-12-16 18:23 uN Eric Schulte + Re: [O] A presentation tool for org-mode
2011-12-17 01:53 usaN Gaspard Caderousse \ Re: [O] A presentation tool for org-mode
2011-12-16 16:31 uN Baron Danglars | [O] imaxima?
End of search results
@end verbatim
It should be fairly obvious what this means, but some notes:
@itemize
@item The fields shown in the headers view can be influenced by customizing
@samp{mu4e-headers-fields}
@item You can change the date format by customizing
@samp{mu4e-headers-date-format}
@item The letters in the 'Flags' field correspond to the following: D=draft,
F=flagged, N=new, P=passed (i.e.., forwarded), R=replied, S=seen, T=trashed,
a=has-attachment, x=encrypted, s=signed, u=unread.
@item The From/To field shows the sender of the message unless the sender
matches the regular expression in @samp{mu4e-user-mail-address-regexp}, in
which the header will show @samp{To} followed by the recipient.
@item The subject field displays the discussion threads according to the @emph{JWZ mail
threading algorithm}.
@end itemize
Using the default key bindings, you can do various things with these messages;
note that these actions are also listed in the @samp{Headers} menu in the
Emacs menu bar.
@itemize
@item @key{d} will mark the message at point with 'd' for moving to the @samp{thrash}-folder
@item @key{DEL} will mark the message at point with 'D' for immediate removal
@item @key{m} will mark the message at point with 'm' for moving to another maildir (@samp{mu4e}
will ask which)
@item @key{u} will unmark the message at point, while @key{U} will do so for
@emph{all} messages.
@item @key{x} will execute the actions various message have been marked for.
@item @key{RET} will open the message at point for viewing @xref{Message view}.
@item @key{R}, @key{F} @key{C} will, respectively, reply to the message at
point or forward it, or compose a new message; @xref{Editor view}.
@item @key{E} will edit the message at point, which is only allowed for draft messages.
@item @key{q} will leave the headers buffer @ref{Main view}
@end itemize
Note, all the mark/unmark commands support the current @emph{region} (i.e.,
selection) -- so, for example, if you the select a number of message and then
press @key{DEL}, all selected message will be marked for deletion.
Tne two-step mark-execute sequence is similar to what for example @samp{Dired}
does, and tries to be as fast as possible while still trying to protect the
user against accidents.
@node Message view
@section Message view
After selecting a message in the Headers view (@ref{Headers view}), the
message will be show in the message view. This might look something like the
following:
@verbatim
From: info@galatians.net
To: "Paul" paul@hotmail.com
Subject: Re: some thoughts
Flags: (seen attach)
Date: Mon 19 Jan 2004 09:39:42 AM EET
Maildir: /inbox
Attachments(2): [1]DSCN4961.JPG(1.3M), [2]DSCN4962.JPG(1.4M)
Hi Paul,
How are you? Sorry we didn't get back to you sooner and sorry for the
top-quoting. We're still debating your last message; anyway, here are some
recent pics.
All the best!
On Sun 21 Dec 2003 09:06:34 PM EET, Paul wrote:
[....]
@end verbatim
Some notes:
@itemize
@item You can customize which header fields are shown using
@samp{mu4e-view-fields}.
@end itemize
You can find most things you can do with this message in the @emph{View} menu,
or use the keyboard -- the default bindings are:
@itemize
@item @key{R}, @key{F} @key{C} will, respectively, reply to the message or forward it, or compose a new message; @xref{Editor view}.
@item @key{E} will edit the message (only allowed for draft messages).
@item @key{d} will mark the message for moving to the @samp{thrash}-folder
@item @key{DEL} will mark the message for immediate removal
@item @key{m} will mark the message for moving to another maildir (@samp{mu4e}
will ask which)
@item @key{u} will unmark the messages.
@item @key{q} will leave the message view and go back to the Headers view, @ref{Headers view}
@end itemize
Note that @key{x}, which means 'execute actions on marked messages' does not
function in this view; to reduce the risk of accidents, you have to go back to
the headers view to effectuate the actions.
@node Editor view
@section Editor view
@c @node Getting mail
@c @section Getting mail
@command{mu} works with whatever it finds in your Maildir, without caring much @node Searching mail
how the mail got there. Typical ways to do so are using @code{fetchmail} or @chapter Searching mail
@code{offlineimap}, but mail servers like @code{qmail} or @code{Postfix} can
deliver mail in a Maildir as well. Please refer to the documentation for these
tools.
@command{mu4e} checks the setting of the @env{MAILDIR} environment variable to @samp{mu4e} is fully search-based; this means that all the lists of messages
locate the Maildir; if that is not set, if falls back to @code{~/Maildir}. If
you want to use some other directory, you can customize @code{mu4e-mu-home}.
To invoke some mail-getting command from the @command{mu4e} main screen, you can
call @code{mu4e-retrieve-mail-update-db} (by default @kbd{u}); to use it, you
should set @code{mu4e-get-mail-command} to some shell command.
@c @node Searching mail
@c @section Searching mail
@command{mu4e} is full search-based; this means that all the lists of messages
you see, are the result of some query. Even if you 'jump to a folder', in fact you see, are the result of some query. Even if you 'jump to a folder', in fact
you are executing a search query for messages that have the property of being you are executing a search query for messages that have the property of being
in a certain folder. in a certain folder.
@menu
* Queries::
* Bookmarks::
* Maildir searches::
@end menu
@node Queries
@section Queries
@node Bookmarks
@section Bookmarks
@node Maildir searches
@section Maildir searches
@c @node Reading mail @c @node Reading mail
@c @section Reading mail @c @section Reading mail
@ -311,6 +504,23 @@ in a certain folder.
@c @node Sending mail @c @node Sending mail
@c @section Sending mail @c @section Sending mail
@c @node Updating the mail store
@c @section Updating the mail store
@c @samp{mu} works with whatever it finds in your Maildir, without caring much
@c how the mail got there. Typical ways to do so are using @code{fetchmail} or
@c @code{offlineimap}, but mail servers like @code{qmail} or @code{Postfix} can
@c deliver mail in a Maildir as well. Please refer to the documentation for these
@c tools.
@c @samp{mu4e} checks the setting of the @env{MAILDIR} environment variable to
@c locate the Maildir; if that is not set, if falls back to @code{~/Maildir}. If
@c you want to use some other directory, you can customize @code{mu4e-mu-home}.
@c To invoke some mail-getting command from the @samp{mu4e} main screen, you can
@c call @code{mu4e-retrieve-mail-update-db} (by default @kbd{u}); to use it, you
@c should set @code{mu4e-get-mail-command} to some shell command.
@node Example configuration @node Example configuration
@chapter Example configuration @chapter Example configuration
@ -369,4 +579,55 @@ in a certain folder.
@end example @end example
@node FAQ - Frequently Anticipated Questions
@chapter FAQ - Frequently Anticipated Questions
In this chapter we list a number of anticipated questions and their answers.
@itemize
@item @emph{How can I quickly delete/move/trash a lot of messages?} You can
select ('mark' in emacs-speak) the messages, and then press one of the keys to
mark them for some actions; by default @key{DEL} for delete, @key{m} for move
and @key{t} for trash.
@item @emph{mu4e only seems to return a subset of all matches - how can I get
all?}. Yes, for speed reasons (and because, if you are like the author, you
usually don't need thousands of matches), mu4e returns only up to
@code{m4ue-search-result-limit} matches. You can customize that variable, or
simply press the emacs prefix @samp{C-u} to get all matches. In other words,
when you press @samp{C-u s hello} you will get all matches, while @samp{s
hello} only gets you up-to-a-limited-number matches. Same for the other search
based commands, @code{mu4e-jump-to-maildir} (default: @key{j}) and
@code{mu4e-search-bookmark} (default: @key{b}).
@end itemize
@node Known issues / missing features
@chapter Known issues / missing features
In this chapter we list a number of known issue and/or missing features in
@samp{mu4e}. Thus, users won't have to search in vain for things that are not
there (yet), and the author can use it as a todo-list.
@itemize
@item @emph{Thread handling is incomplete.} While threads are calculated and are
visible in the headers buffer, there is no functionality to manipulate them
(e.g., collapse the thread, or delete a whole thread at once). But note that
you can manipulate a number of consequetive messages at once by selecting
them, and then using one of the manipulation commands, such as
@code{mu4e-mark-for-move} or @code{mu4e-mark-for-delete}.
@item @emph{Forwarding messaging does not forward attachments.} This is a
missing features, which will be added in some future version. Of course, you
can save attachments, and then re-attach them by hand.
@item @emph{No support for crypto when reading mail}. Currently, you cannot
conveniently read encrypted mail or check signatures (it should be possible
with e.g. EPA though, @inforef{Top, EasyPG Assistant, epa}.) For outgoing
messages, it should work though, using the built-in mechanisms.
@item @emph{Difficulties with attachments in messages with complex
MIME-hierarchy.} While dealing with attachments usually works fine, we have
found some problems with specific mails. This is an issue in @samp{mu}, and it
is under investigation.
@item @emph{mu4e is very much keyboard-driven}. It would be nice to add
support for mousing as well.
@end itemize
@bye @bye