From b67a8e86a06c74c8c5d1f1db48514e478a480376 Mon Sep 17 00:00:00 2001 From: djcb Date: Mon, 19 Dec 2011 09:07:03 +0200 Subject: [PATCH] * mu4e: documentation updates (WIP) --- emacs/mu4e.texi | 475 +++++++++++++++++++++++++++++++++++++----------- 1 file changed, 368 insertions(+), 107 deletions(-) diff --git a/emacs/mu4e.texi b/emacs/mu4e.texi index 98f2f1e4..ece6fd7e 100644 --- a/emacs/mu4e.texi +++ b/emacs/mu4e.texi @@ -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-.tar.gz # use the specific version -$ cd mu- +$ cd mu- $./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