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

* some modest beginnings of documentation (info pages) for mu4e

Browse Source
This commit is contained in:
djcb
2011-12-14 09:11:40 +02:00
parent b9805567ed
commit f55affe45e
2 changed files with 705 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

254
emacs/mu4e.texi Normal file
View File

@ -0,0 +1,254 @@
\input texinfo.tex @c -*-texinfo-*-
@c %**start of header
@setfilename mu4e.info
@settitle mu4e user manual
@documentencoding utf-8
@c %**end of header
@dircategory Emacs
@direntry
* mu4e mail client: (mu4e). An email client for emacs based on mu.
@end direntry
@copying
Copyright @copyright{} 2011 Dirk-Jan C. Binnema
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.
@end quotation
@end copying
@node Top
@top mu4e User Manual
@emph{Mu-For-Emacs} (or for short, @code{mu4e}), is an @code{emacs} based
e-mail client, based on the @code{mu} e-mail search engine. @code{mu4e}
supports GNU Emacs 23 and later, and may work with other versions as well.
@menu
* Introduction::
* Overview::
* Installation::
* Getting mail::
* Searching mail::
* Reading mail::
* Processing mail::
* Sending mail::
* Example configuration::
@end menu
@node Introduction
@chapter Introduction
@code{mu4e} is an e-mail program for GNU Emacs; it uses the @code{mu} e-mail
search engine as its backend, making @code{mu} fully search-based.
@code{mu4e} (and @code{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 @code{fetchmail} and @code{offlineimap}. As long as the messages
end up in a Maildir, @code{mu4e}/@code{mu} are happy to deal with them.
@code{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, @code{mu4e} piggybacks on @ref{Top, Gnus} for its message editor.
Thus, many of the traditional things an e-mail client needs to do, are
subcontracted to other tools. This leaves @code{mu4e} to concentrate on what it
does best: quick message searching, reading mails, replying them, moving
messages around and so on.
@subsection Acknowledgments
@code{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!
@code{mu4e} has taken inspiration from many places. First, there are @code{sup}
and @code{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 @code{dired} interaction model.
@node Installation
@chapter Installation
@code{mu4e} is part of @code{mu} - by installing the latter, the former will
be installed as well.
At the time of writing, there are no distribution packages for @code{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>
$./configure && make
$ sudo make install
@end example
After this, but @code{mu} and @code{mu4e} should be installed.
Note, there's a hard dependency between versions of @code{mu4e} and @code{mu}
- you cannot combine different versions.
There is experimental support for the @code{emacs} customization system in
@code{mu4e}, but for now we recommend setting the values by - please
@xref{Example configuration} for an example of this.
@node Overview
@chapter Overview
@section Elements
Without going into too much technical detail, here we describe the elements in
a @code{mu4e}-setup, and how they work together. Using some ascii-art:
@example
+---------+
| emacs |
| +------+
+----| mu4e | --> send mail (smtpmail)
+------+
| A
V |
+---------+
| mu |
+---------+
| A
V |
+---------+
| Maildir | <--- receive mail (fetchmail,
+---------+ offlineimap, ...)
@end example
So:
@itemize
@item Your e-mail messages are stored in a Maildir-directory (typically,
@code{~/Maildir}), and new mail comes in using tools like @code{fetchmail},
@code{offlineimap} etc., or through a local mail servers (such as
@code{qmail} or @code{Postfix}).
@item @code{mu} indexes these messages periodically, so you can quickly
search for them. @code{mu} can run in a special @code{server}-mode, where it
provides services to client software.
@item @code{mu4e}, which runs inside @code{emacs} is such a client; it
communicates with @code{mu} to search for messages, and manipulate them.
@item @code{mu4e} uses the facilities offered by @code{emacs} (the
@code{Gnus} message editor and @code{smtpmail}) to send messages.
@end itemize
@section User interface
@example
+-----------+ +--------------+ +--------------+
| main view | <---> | headers view | <---> | message view |
+-----------+ +--------------+ +--------------+
|
+----------+
| raw view |
+----------+
@end example
@node Getting mail
@chapter Getting mail
@code{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.
@code{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 @code{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.
@node Searching mail
@chapter Searching mail
@section Everything is search
@code{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 are executing a search query for messages that have the property of being
in a certain folder.
@node Reading mail
@chapter Reading mail
@node Processing mail
@chapter Processing mail
Processing mail is the act of moving mails around (in folders), viewing them
@node Sending mail
@chapter Sending mail
@node Example configuration
@chapter Example configuration
@example
@verbatim
;; example configuration for mu-for-emacs (mu4e)
(require 'mu4e)
(load-library "smtpmail")
(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
mu4e-user-mail-address-regexp
"foo@bar\.com\\|cuux@example\.com"
mu4e-maildir "/home/user/Maildir"
;; the next are relative to `mu4e-maildir'
mu4e-outbox-folder "/outbox"
mu4e-sent-folder "/sent"
mu4e-drafts-folder "/drafts"
mu4e-trash-folder "/trash"
;; the maildirs you use frequently; access them with 'j' ('jump')
mu4e-maildir-shortcuts
'( ("/archive" . ?a)
("/inbox" . ?i)
("/work" . ?w)
("/sent" . ?s))
;; program to get mail
mu4e-get-mail-command "fetchmail"
;; general emacs mail settings
mail-reply-to "foo@bar.com"
user-mail-address "foo@bar.com"
user-full-name "Foo. X Bar"
;; include in message with C-c C-w
message-signature
(concat
"Foo X. Bar\n"
"http://www.example.com\n")
;; smtp mail setting
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"
;; for offline mode
smtpmail-queue-mail nil
smtpmail-queue-dir "/home/user/Maildir/queue/cur")
@end verbatim
@end example
@bye