emacs
/
mu
mirror of https://github.com/djcb/mu.git
1
0
Fork 0
Code Issues Releases Wiki Activity

* mu4e: documentation updates (WIP)

This commit is contained in:
djcb 2011-12-19 09:07:03 +02:00
parent 5307a8411b
commit b67a8e86a0
1 changed files with 368 additions and 107 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

475
emacs/mu4e.texi
View File

@ -25,107 +25,125 @@ Texts.
@node Top
@top mu4e Manual
@emph{Mu-For-Emacs} (or for short, @command{mu4e}), is an @command{emacs} based
e-mail client, based on the @command{mu} e-mail search engine. @command{mu4e}
@emph{Mu-For-Emacs} (or for short, @samp{mu4e}), is an @samp{emacs} based
e-mail client, based on the @samp{mu} e-mail search engine. @samp{mu4e}
supports GNU Emacs 23 and later.
@menu
* Introduction::
* Getting started::
* Running mu4e::
@c * Getting mail::
@c * Searching mail::
@c * Reading mail::
@c * Processing mail::
@c * Sending mail::
* Searching mail::
* Example configuration::
* FAQ - Frequently Anticipated Questions::
* Known issues / missing features::
@end menu
@node Introduction
@chapter Introduction
@command{mu4e} is an e-mail program for GNU Emacs; it uses the @command{mu}
e-mail search engine as its backend, making @command{mu} fully search-based.
@samp{mu4e} is an e-mail program for GNU Emacs; it uses the @samp{mu}
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
other tools, such as @command{offlineimap}. As long as the messages end up in
a Maildir, @command{mu4e}/@command{mu} are happy to deal with them.
other tools, such as @samp{offlineimap}. As long as the messages end up in
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
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
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,
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}.
@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!
@command{mu4e} has taken inspiration from many places. First, there are @command{sup}
and @command{notmuch} which showed that one can write a search-based e-mail
@samp{mu4e} has taken inspiration from many places. First, there are @samp{sup}
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
as the @command{dired} interaction model.
as the @samp{dired} interaction model.
@node 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.
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.
Installation follows the normal sequence of:
@example
$ tar xvfz mu-<version>.tar.gz # use the specific version
$ cd mu-<version>
$ cd mu-<version>
$./configure && make
$ sudo make install
@end example
After this, @command{mu} and @command{mu4e} should be
installed @footnote{there's a hard dependency between versions of
@command{mu4e} and @command{mu} - you cannot combine different versions.}, a
be available from the command line and emacs (respectively). For emacs, you
may to restart it so it can pick up @command{mu4e}.
After this, @samp{mu} and @samp{mu4e} should be installed @footnote{there's a
hard dependency between versions of @samp{mu4e} and @samp{mu} - you cannot
combine different versions.}, a be available from the command line and emacs
(respectively). For emacs, you may to restart it so it can pick up
@samp{mu4e}.
There is experimental support for using the @command{emacs} customization
system in @command{mu4e}, but for now we recommend setting the values by
There is experimental support for using the @samp{emacs} customization
system in @samp{mu4e}, but for now we recommend setting the values by
manually. Please @ref{Example configuration} for a working example of this.
@c @node Getting mail
@c @section Getting mail
@node 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,
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
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
a local mailserver (such as Postfix or @command{qmail}), you can teach them to
deliver into a Maildir as well, maybe in combination with @command{qmail}.
a local mailserver (such as Postfix or @samp{qmail}), you can teach them to
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
the products you are using.
@c @node Indexing your messages
@c @section Indexing your messages
@c @ref{Getting mail}
After you have succeeded in Getting mail, we need to @emph{index}
@node Indexing your messages
@section Indexing your messages
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
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
@ -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
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
trying some command line searches, for example
@example
$ mu find hello
@end example
which should list all messages that match "hello". The @command{mu-find} man
page describes the various things you can do with @command{mu find}.
which should list all messages that match "hello". The @samp{mu-find} man
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
@c @section Basic configuration
@node 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.
First, we need to load @command{mu4e}:
First, we need to load @samp{mu4e}:
@example
(require 'mu4e)
@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:
@example
(setq
@ -179,9 +197,8 @@ special folders. So for example:
@end example
The folder names are all relative to @code{mu4e-maildir}.
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
+---------+
@ -197,7 +214,7 @@ a @command{mu4e}-setup, and how they work together. Using some ascii-art:
| A
V |
+---------+
| Maildir | <--- receive mail (fetchmail,
| Maildir | <--- receive mail (fetchmail,
+---------+ offlineimap, ...)
@end example
@ -205,49 +222,83 @@ So:
@itemize
@item Your e-mail messages are stored in a Maildir-directory (typically,
@file{~/Maildir}), and new mail comes in using tools like @command{fetchmail},
@command{offlineimap} etc., or through a local mail servers (such as
@command{qmail} or @command{Postfix}).
@file{~/Maildir}), and new mail comes in using tools like @samp{fetchmail},
@samp{offlineimap} etc., or through a local mail servers (such as
@samp{qmail} or @samp{Postfix}).
@item @command{mu} indexes these messages periodically, so you can quickly
search for them. @command{mu} can run in a special @command{server}-mode, where it
@item @samp{mu} indexes these messages periodically, so you can quickly
search for them. @samp{mu} can run in a special @samp{server}-mode, where it
provides services to client software.
@item @command{mu4e}, which runs inside @command{emacs} is such a client; it
communicates with @command{mu} to search for messages, and manipulate them.
@item @samp{mu4e}, which runs inside @samp{emacs} is such a client; it
communicates with @samp{mu} to search for messages, and manipulate them.
@item @samp{mu4e} uses the facilities offered by @samp{emacs} (the
@samp{Gnus} message editor and @samp{smtpmail}) to send messages.
@item @command{mu4e} uses the facilities offered by @command{emacs} (the
@command{Gnus} message editor and @command{smtpmail}) to send messages.
@end itemize
@example
+-----------+ +--------------+ +--------------+
| main view | <---> | headers view | <---> | message view |
+-----------+ +--------------+ +--------------+
|
+----------+
| raw view |
+----------+
@end example
@node 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
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
* mu4e - mu for emacs version 0.9.8pre
* mu4e - mu for emacs version x.x
Basics
* [j]ump to some maildir
* enter a [s]earch query
* [c]ompose a new message
* [C]ompose a new message
Bookmarks
@ -257,49 +308,191 @@ correctly, and then show the @command{mu4e} main view.
* [bp] Messages with images
Misc
* [u]pdate email & database
* [U]pdate email & database
* toggle [m]ail sending mode (direct)
* [f]lush queued mail
* [q]uit mm
* [H]elp
* [q]uit mu4e
@end verbatim
First, the @emph{Basics}:
@itemize
@item @code{[j]ump to some maildir} means that after pressing @key{j},
@command{mu4e} will ask you for a maildir to jump to.
@item @samp{[j]ump to some maildir} means that after pressing @key{j},
@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
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
how the mail got there. Typical ways to do so are using @code{fetchmail} or
@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.
@node Searching mail
@chapter Searching mail
@command{mu4e} checks the setting of the @env{MAILDIR} environment variable to
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
@samp{mu4e} is fully 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 are executing a search query for messages that have the property of being
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 @section Reading mail
@ -311,6 +504,23 @@ in a certain folder.
@c @node 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
@chapter Example configuration
@ -324,7 +534,7 @@ in a certain folder.
(setq
;; a regular expression that matches all email address uses by the user;
;; this allows us to correctly determine if user is the sender of some message
;; this allows us to correctly determine if user is the sender of some message
mu4e-user-mail-address-regexp
"foo@bar\.com\\|cuux@example\.com"
@ -357,7 +567,7 @@ in a certain folder.
"http://www.example.com\n")
;; smtp mail setting
message-send-mail-function 'smtpmail-send-it
message-send-mail-function 'smtpmail-send-it
smtpmail-default-smtp-server "smtpa.example.com"
smtpmail-smtp-server ""smtpa.example.com"
smtpmail-local-domain "example.com"
@ -369,4 +579,55 @@ in a certain folder.
@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