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

* mu4e: update documentation

Browse Source
This commit is contained in:
djcb
2012-09-28 17:12:09 +03:00
parent e11e83e2a4
commit 8412c73628
1 changed files with 116 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files

193
mu4e/mu4e.texi
View File

@ -6,17 +6,9 @@
@c %**end of header @c %**end of header
@include version.texi @include version.texi
@titlepage
@title @t{mu4e} - an e-mail client for emacs
@author{Dirk-Jan C. Binnema}
@end titlepage
@dircategory Emacs
@direntry
* mu4e: (mu4e). An email client for emacs based on mu.
@end direntry
@copying @copying
This manual is for @t{mu4e} version @value{mu4e-version}.
Copyright @copyright{} 2012 Dirk-Jan C. Binnema Copyright @copyright{} 2012 Dirk-Jan C. Binnema
@quotation @quotation
@ -29,23 +21,41 @@ Documentation License.''
@end quotation @end quotation
@end copying @end copying
@titlepage
@title @t{mu4e} - an e-mail client for emacs
@subtitle{version @value{mu4e-version}}
@author by Dirk-Jan C. Binnema
@end titlepage
@dircategory Emacs
@direntry
* mu4e: (mu4e). An email client for emacs.
@end direntry
@insertcopying
@contents
@node Top @node Top
@top mu4e Manual @top Welcome to mu4e
Welcome to @t{mu4e}! Welcome to @t{mu4e}!
@t{mu4e} (mu-for-emacs) is an e-mail client for GNU-Emacs, version 23 and @t{mu4e} (mu-for-emacs) is an e-mail client for GNU-Emacs version 23 and
later, built on top of the @t{mu} e-mail search engine. @t{mu4e} is optimized later, built on top of the
for fast handling of large amounts of e-mail. @t{mu}@footnote{@url{http://www.djcbsoftware.nl/code/mu}} e-mail search
engine. @t{mu4e} is optimized for fast handling of large amounts of e-mail.
Some of the features include: Some of its features include:
@itemize @itemize
@item Fully search-based: there are no folders, only queries @item Fully search-based: there are no folders, only queries
@item Fully documented, with example configurations @item Fully documented, with example configurations
@item UI optimized for speed with quick key strokes for common actions @item UI optimized for speed with quick key strokes for common actions
@item Asynchronous: heavy actions never block @t{emacs} @item Asynchronous: heavy actions never block @t{emacs}
@item Rich-text e-mails using @t{org-mode} (experimental) @item Support for crypto
@item Writing rich-text e-mails using @t{org-mode} (experimental)
@item Address auto-completion based on your messages @item Address auto-completion based on your messages
@item Extendable using your own custom actions @item Extendable using your own custom actions
@end itemize @end itemize
@ -56,7 +66,8 @@ configuration, and explains its daily use. It also shows how you can customize
configurations, which should help you to get up to speed quickly. configurations, which should help you to get up to speed quickly.
Also note the @xref{FAQ - Frequently Anticipated Questions}, and the section Also note the @xref{FAQ - Frequently Anticipated Questions}, and the section
on @xref{Known issues / missing features}, which may save you some time. on @xref{Known issues / missing features}, which may save you some time, and
the appendices that try the shed some light on @t{mu4e}'s internals.
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}}.
@ -86,8 +97,6 @@ Appendices
@node Introduction @node Introduction
@chapter Introduction @chapter Introduction
Welcome to @t{mu4e}!
@menu @menu
* Why another e-mail client?:: * Why another e-mail client?::
* Other mail clients:: * Other mail clients::
@ -99,18 +108,18 @@ Welcome to @t{mu4e}!
Fair question. Fair question.
I'm not sure the world @emph{needs} yet another e-mail client, but perhaps I'm not sure the world needs yet another e-mail client, but perhaps @emph{I}
@emph{I} do! I (the author) spend a @emph{lot} of time, professionally and do! I (the author) spend a @emph{lot} of time dealing with e-mail, both
privately, dealing with e-mail messdae and therefore, having an efficient professionally and privately. Having an efficient e-mail client is essential
e-mail client is essential for me. Since none of the existing ones worked the for me. Since none of the existing ones worked the way I wanted, I created my
way I wanted, I created my own. own.
As @t{emacs} is such an integral part of my workflow, it made a lot of sense As @t{emacs} is such an integral part of my workflow, it made a lot of sense
to integrate my e-mail client with it. And as I already had written an e-mail to use it for e-mail as well. And as I already had written an e-mail search
search engine (@t{mu}), it seemed only logical to use that as a basis. engine (@t{mu}), it seemed only logical to use that as a basis.
Even though I created @t{mu4e} for such selfish reasons, @t{mu4e} tries hard Even though I created @t{mu4e} for such selfish reasons, @t{mu4e} tries hard
to be as useful as possible for @emph{all} its users - suggestions are very to be as useful as possible for all its users - suggestions are very
welcome and many have already made it to @t{mu4e}. welcome and many have already made it to @t{mu4e}.
@node Other mail clients @node Other mail clients
@ -326,10 +335,10 @@ details.}:
@lisp @lisp
(setq (setq
mu4e-maildir "~/Maildir" ;; top-level Maildir mu4e-maildir "~/Maildir" ;; top-level Maildir
mu4e-sent-folder "/sent" ;; where do I keep sent mail? mu4e-sent-folder "/sent" ;; folder for sent messages
mu4e-drafts-folder "/drafts" ;; where do I keep half-written mail? mu4e-drafts-folder "/drafts" ;; unfinished messages
mu4e-trash-folder "/trash" ;; where do I move deleted mail? mu4e-trash-folder "/trash" ;; trashed messages
mu4e-refile-folder "/archive") ;; where do I move message after completion? mu4e-refile-folder "/archive") ;; saved messages
@end lisp @end lisp
@code{mu4e-maildir} takes an actual filesystem-path, the other folder names @code{mu4e-maildir} takes an actual filesystem-path, the other folder names
@ -402,7 +411,7 @@ For your orientation, the diagram below shows how the views relate to each
other, and the default key-bindings to get from one view to the next. other, and the default key-bindings to get from one view to the next.
@example @example
---------------------------------------------------------------------------- -----------------------------------------------------------
[C] +--------+ [RFCE] [C] +--------+ [RFCE]
--------> | editor | <-------- --------> | editor | <--------
@ -426,7 +435,7 @@ F: Forward j: jump-to-maildir q: quit
C: Compose b: bookmark-search C: Compose b: bookmark-search
E: Edit B: edit bookmark-search E: Edit B: edit bookmark-search
---------------------------------------------------------------------------- -----------------------------------------------------------
@end example @end example
@node Main view @node Main view
@ -522,19 +531,19 @@ matching message, showing information about it. It looks something like the
following: following:
@verbatim @verbatim
---------------------------------------------------------------------------------- ------------------------------------------------------------------------------
Date Flgs From/To Subject Date Flgs From/To Subject
2011-12-16 18:38 S To Edmund Dantès + Re: Extension security? 2011-12-16 18:38 S To Edmund Dantès + Re: Extensions?
2011-12-16 21:44 S Abbé Busoni + Re: Extension security? 2011-12-16 21:44 S Abbé Busoni + Re: Extensions?
2011-12-17 03:14 SR Pierre Morrel + Re: Extension security? 2011-12-17 03:14 SR Pierre Morrel + Re: Extensions?
2011-12-17 04:04 uN Jacopo + Re: Extension security? 2011-12-17 04:04 uN Jacopo + Re: Extensions?
2011-12-17 14:36 uN Mercédès + Re: Extension security? 2011-12-17 14:36 uN Mercédès + Re: Extensions?
2011-12-18 06:05 uN Beachamp \ Re: Extension security? 2011-12-18 06:05 uN Beachamp \ Re: Extensions?
2011-12-16 18:23 Ss Albert de Moncerf + Re: [O] A presentation tool 2011-12-16 18:23 Ss Albert de Moncerf + Re: [O] A cool tool
2011-12-17 01:53 Sa Gaspard Caderousse \ Re: [O] A presentation tool 2011-12-17 01:53 Sa Gaspard Caderousse \ Re: [O] A cool tool
2011-12-16 16:31 uN Baron Danglars | [O] imaxima? 2011-12-16 16:31 uN Baron Danglars | [O] imaxima?
End of search results End of search results
---------------------------------------------------------------------------------- ------------------------------------------------------------------------------
@end verbatim @end verbatim
@subsection Some notes @subsection Some notes
@ -599,7 +608,7 @@ DEL,D mark for complete deletion
m mark for moving to another maildir folder m mark for moving to another maildir folder
r mark for refiling r mark for refiling
+,- mark for flagging/unflagging +,- mark for flagging/unflagging
o,s mark message as unread, read (seen) ?,! mark message as unread, read
u unmark message at point u unmark message at point
U unmark *all* messages U unmark *all* messages
@ -1122,7 +1131,7 @@ you can define a @emph{hook function}. @t{mu4e} offers two hooks:
starts; if you are composing a @emph{reply}, @emph{forward} a message, or starts; if you are composing a @emph{reply}, @emph{forward} a message, or
@emph{edit} an existing message, the variable @emph{edit} an existing message, the variable
@code{mu4e-compose-parent-message} points to the message being replied to, @code{mu4e-compose-parent-message} points to the message being replied to,
forwarded or edit, and you can use @code{mu4e-msg-field} to get the value of forwarded or edit, and you can use @code{mu4e-message-field} to get the value of
various properties (and see @ref{The message s-expression}). various properties (and see @ref{The message s-expression}).
@item @code{mu4e-compose-mode-hook}: this hook is run just before composition @item @code{mu4e-compose-mode-hook}: this hook is run just before composition
starts, when the whole buffer has already been set up. This is a good place starts, when the whole buffer has already been set up. This is a good place
@ -1141,7 +1150,7 @@ on the receiver of the original:
(add-hook 'mu4e-compose-pre-hook (add-hook 'mu4e-compose-pre-hook
(defun my-set-from-address () (defun my-set-from-address ()
"Set the From address based on the To address of the original." "Set the From address based on the To address of the original."
(let ((orig-to (cdar (mu4e-msg-field mu4e-compose-parent-message :to)))) (let ((orig-to (cdar (mu4e-message-field mu4e-compose-parent-message :to))))
(setq user-mail-address (setq user-mail-address
(cond (cond
((string= "me@@foo.com" orig-to) "me@@foo.com") ((string= "me@@foo.com" orig-to) "me@@foo.com")
@ -1489,19 +1498,19 @@ respectively
apply to messages: apply to messages:
@verbatim @verbatim
| mark for | keybinding | description | | mark for/as | keybinding | description |
|--------------+-------------+--------------------------| |--------------+-------------+--------------------------|
| deferred | * | mark now, decide later | | deferred | * | mark now, decide later |
| delete | D, <delete> | delete | | delete | D, <delete> | delete |
| flag | + | mark as 'flagged' | | flag | + | mark as 'flagged' |
| move | m | move to some maildir | | move | m | move to some maildir |
| read | s | mark as read (seen) | | read | ! | mark as read |
| refile | r | mark for refiling | | refile | r | mark for refiling |
| trash | d | move to the trash folder | | trash | d | move to the trash folder |
| unflag | - | remove 'flagged' mark | | unflag | - | remove 'flagged' mark |
| unmark | u | remove mark at point | | unmark | u | remove mark at point |
| unmark all | U | remove all marks | | unmark all | U | remove all marks |
| unread | o | marks as unread | | unread | ? | marks as unread |
@end verbatim @end verbatim
After marking a header for something, the left-most columns shows a character After marking a header for something, the left-most columns shows a character
@ -1560,8 +1569,8 @@ more than @emph{n} recipients. We could do it like this:
@lisp @lisp
(add-to-list 'mu4e-headers-custom-markers (add-to-list 'mu4e-headers-custom-markers
'("More than n recipients" '("More than n recipients"
(lambda (msg n) (> (+ (length (mu4e-msg-field msg :to)) (lambda (msg n) (> (+ (length (mu4e-message-field msg :to))
(length (mu4e-msg-field msg :cc))) n)) (length (mu4e-message-field msg :cc))) n))
(lambda () (read-number "Match messages with more recipients than: "))) t) (lambda () (read-number "Match messages with more recipients than: "))) t)
@end lisp @end lisp
@ -1586,49 +1595,65 @@ press @key{% + s hello RET}. Note, the menu system helps you here; all you
need to remember is @key{%} for @code{mu4e-headers-mark-pattern}. need to remember is @key{%} for @code{mu4e-headers-mark-pattern}.
@end itemize @end itemize
@node Dynamic folders @node Dynamic folders
@chapter Dynamic folders @chapter Dynamic folders
In @ref{Folders} we gave an example of setting the standard folders: In @ref{Folders} we gave an example of setting the standard folders:
@lisp @lisp
(setq (setq
mu4e-sent-folder "/sent" ;; where do I keep sent mail? mu4e-sent-folder "/sent" ;; folder for sent messages
mu4e-drafts-folder "/drafts" ;; where do I keep half-written mail? mu4e-drafts-folder "/drafts" ;; unfinished messages
mu4e-trash-folder "/trash" ;; where do I move deleted mail? mu4e-trash-folder "/trash" ;; trashed messages
mu4e-refile-folder "/archive") ;; where do I move message after completion? mu4e-refile-folder "/archive") ;; saved messages
@end lisp @end lisp
In some case, these static folders may not suffice, and you might want to In some case, these static folders may not suffice, and you might want to
change the folders depending on the context; for example, we may have change the folders depending on the context. For example, we may have
different folders for refiling, based on the sender of the message. different folders for refiling, based on the sender of the message.
To enable this, instead of setting the standard folders to constant strings, To enable this, instead of setting the standard folders to constant strings,
you can set them to be a @emph{function} that takes a message as parameter, you can set them to be a @emph{function} that takes a message as parameter,
and returns the desired folder name. and returns the desired folder name.
For example, for the refile folder you could put something like the following @menu
in your setup: * Smart refiling::
* Other dynamic folders::
@end menu
@node Smart refiling
@section Smart refiling
It is sometimes convenient to move messages to some specific folder, based on
some of the message details -- @emph{refiling}(@key{r}).
We can make this 'smart' with a dynamic refiling folder - each message
automatically figures out the right folder to move to. For example, you could
put something like the following in your setup:
@lisp @lisp
(setq mu4e-refile-folder (setq mu4e-refile-folder
(lambda (msg) (lambda (msg)
(cond (cond
;; messages to the mu mailing list go to the /mu folder ;; messages to the mu mailing list go to the /mu folder
((mu4e-message-contact-field-matches msg :to "mu-discuss@@googlegroups.com") ((mu4e-message-contact-field-matches msg :to
"mu-discuss@@googlegroups.com")
"/mu") "/mu")
;; messages sent directly to me go to /archive ;; messages sent directly to me go to /archive
;; also `mu4e-user-mail-address-regexp' can be used ;; also `mu4e-user-mail-address-regexp' can be used
((mu4e-message-contact-field-matches msg :to "me@@example.com") ((mu4e-message-contact-field-matches msg :to
"me@@example.com")
"/private") "/private")
;; message with football or soccer in the subject go to /football ;; messages with football or soccer in the subject go to /football
((string-match "football\\|soccer" (mu4e-message-field msg :subject)) ((string-match "football\\|soccer"
"/football) (mu4e-message-field msg :subject))
"/football")
;; everything else goes to /archive ;; everything else goes to /archive
(t ;; important to have a catch-all at the end!
"/archive")))) (t "/archive"))))
@end lisp @end lisp
Let's look at this example a bit: Some notes:
@itemize @itemize
@item we set @code{mu4e-refile-folder} to an anonymous (@t{lambda}) function. This @item we set @code{mu4e-refile-folder} to an anonymous (@t{lambda}) function. This
function takes one argument, a message. @file{mu4e-message.el} contains function takes one argument, a message. @file{mu4e-message.el} contains
@ -1637,13 +1662,18 @@ various convenience functions to deal which such messages
returns the first of the clauses that matches returns the first of the clauses that matches
@item Especially useful are the function @file{mu4e-message.el}; here we use @item Especially useful are the function @file{mu4e-message.el}; here we use
the convenience function @code{mu4e-message-contact-field-matches}, which the convenience function @code{mu4e-message-contact-field-matches}, which
evaluates to @code{t} if any of the names or e-mail addresses in the @t{To:}
matches the regular expression.
@end itemize @end itemize
@node Other dynamic folders
@section Other dynamic folders
Using the same mechanism, you can set special sent-, trash-, and draft-folders Using the same mechanism, you can set special sent-, trash-, and draft-folders
for messages. Note that the message-parameter you receive for sent and draft for messages. The message-parameter you receive for sent and draft folder is
folder is the @emph{original} message, that is, the message you reply to or the @emph{original} message, that is, the message you reply to or forward. If
forward. If there is not such message (for example when composing a new there is not such message (for example when composing a new message) the
message) the message parameter will be @t{nil}. message parameter will be @t{nil}.
@node Actions @node Actions
@chapter Actions @chapter Actions
@ -1701,7 +1731,8 @@ Suppose we would like to inspect the number of recipients for a message in the
(defun show-number-of-recipients (msg) (defun show-number-of-recipients (msg)
"Display the number of recipients for this message." "Display the number of recipients for this message."
(message "Number of recipients: %d" (message "Number of recipients: %d"
(+ (length (mu4e-msg-field msg :to)) (length (mu4e-msg-field msg :cc))))) (+ (length (mu4e-message-field msg :to))
(length (mu4e-message-field msg :cc)))))
;; define 'N' (the first letter of the description) as the shortcut ;; define 'N' (the first letter of the description) as the shortcut
(add-to-list 'mu4e-headers-actions (add-to-list 'mu4e-headers-actions
@ -1719,7 +1750,8 @@ of this message.
@lisp @lisp
(defun search-for-sender (msg) (defun search-for-sender (msg)
"Search for messages sent by the sender of the current one." "Search for messages sent by the sender of the current one."
(mu4e-headers-search (concat "from:" (cdar (mu4e-msg-field msg :from))))) (mu4e-headers-search
(concat "from:" (cdar (mu4e-message-field msg :from)))))
;; define 'x' as the shortcut ;; define 'x' as the shortcut
(add-to-list 'mu4e-view-actions (add-to-list 'mu4e-view-actions
@ -1769,10 +1801,6 @@ If you have come up with any interesting actions that may be useful for
others, you are invited to contribute those. others, you are invited to contribute those.
@node Interaction with other tools @node Interaction with other tools
@chapter Interaction with other tools @chapter Interaction with other tools
@ -2564,8 +2592,10 @@ A typical message s-expression looks something like the following:
:priority normal :priority normal
:flags (seen) :flags (seen)
:parts ( (:index 1 :mime-type "text/plain" :size 12345 :attachment nil) :parts ( (:index 1 :mime-type "text/plain" :size 12345 :attachment nil)
(:index 2 :name "photo.jpg" :mime-type "image/jpeg" :size 147331 :attachment t) (:index 2 :name "photo.jpg" :mime-type "image/jpeg"
(:index 3 :name "book.pdf" :mime-type "application/pdf" :size 192220 :attachment t)) :size 147331 :attachment t)
(:index 3 :name "book.pdf" :mime-type "application/pdf"
:size 192220 :attachment t))
:references ("6BDC23465F79238C8384574032D81EE81AF0114E4E74@@123213.mail.example.com" :references ("6BDC23465F79238C8384574032D81EE81AF0114E4E74@@123213.mail.example.com"
"6BDC23465F79238203498230942D81EE81AF0114E4E74@@123213.mail.example.com") "6BDC23465F79238203498230942D81EE81AF0114E4E74@@123213.mail.example.com")
:in-reply-to "6BDC23465F79238203498230942D81EE81AF0114E4E74@@123213.mail.example.com" :in-reply-to "6BDC23465F79238203498230942D81EE81AF0114E4E74@@123213.mail.example.com"
@ -2577,8 +2607,9 @@ A typical message s-expression looks something like the following:
This s-expression forms a property list (@t{plist}), and we can get values This s-expression forms a property list (@t{plist}), and we can get values
from it using @t{plist-get}; for example @code{(plist-get msg :subject)} would from it using @t{plist-get}; for example @code{(plist-get msg :subject)} would
get you the message subject. However, it's better to use the function get you the message subject. However, it's better to use the function
@code{mu4e-msg-field} to shield you from some of the implementation details @code{mu4e-message-field} to shield you from some of the implementation
that are subject to change. details that are subject to change; and see the other convenience functions in
@file{mu4e-message.el}.
Some notes on the format: Some notes on the format:
@itemize @itemize