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

* mu4e: document dynamic folders, some refactoring

Browse Source
This commit is contained in:
djcb
2012-09-27 17:21:45 +03:00
parent 40c5ddbb70
commit da51bf9f9c
1 changed files with 124 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

173
mu4e/mu4e.texi
View File

@ -64,9 +64,13 @@ This manual has been updated for @t{mu}/@t{mu4e} version
@menu
* Introduction:: How it all began
* Getting started:: Setting things up
* Running mu4e:: Daily use
* Main view:: Where we go when starting @t{mu4e}
* Headers view:: Lists of message headers
* Message view:: Viewing specific messages
* Editor view:: Creating / editing messages
* Searching:: Some more background on searching/queries
* Marking:: Marking messages and performing actions
* Dynamic folders:: Folders that depend on the context
* Actions:: Defining and using custom actions
* Interaction with other tools:: mu4e and the rest of the world
* Example configuration:: Some examples to set you up quickly
@ -157,12 +161,13 @@ can set it up. After we have succeeded in @ref{Getting mail}, and
After these steps, @t{mu4e} should be ready to go.
@menu
* Installation::
* Getting mail::
* Indexing your messages::
* Basic configuration::
* Folders::
* Sending mail::
* Installation:: How to install @t{mu} and @t{mu4e}
* Getting mail:: Getting mail from a server
* Indexing your messages:: Creating and maintaining the index
* Basic configuration:: Settings for @t{mu4e}
* Folders:: Setting up standard folders
* Sending mail:: How to send mail
* Running mu4e:: Overview of the @t{mu4e} views
@end menu
@ -301,7 +306,8 @@ The first thing we need to do before we can start using @t{mu4e} is to tell
@t{emacs} to load @t{mu4e}, and tell @t{mu4e} where it can find specific
maildir folders.
So, add to your @file{~/.emacs} (or its moral equivalent) something like:
So, add to your @file{~/.emacs} (or its moral equivalent, such as
@file{~/.emacs.d/init.el}) something like:
@example
(require 'mu4e)
@ -311,18 +317,24 @@ So, add to your @file{~/.emacs} (or its moral equivalent) something like:
@section Folders
The next step is to tell @t{mu4e} where it can find your Maildir, and some
special folders. So, for example:
special folders. So, for example@footnote{Note that the folders
(@t{mu4e-sent-folder}, @t{mu4e-drafts-folder}, @t{mu4e-trash-folder} and
@t{mu4e-refile-folder}), instead of simple strings like the example above, can
actually be @emph{functions}, that can be evaluated a runtime. This allows for
dynamically changing them depending on context. See @ref{Dynamic folders} for
details.}:
@lisp
(setq
mu4e-maildir "~/Maildir" ;; top-level Maildir
mu4e-sent-folder "/sent" ;; where do i keep sent mail?
mu4e-drafts-folder "/drafts" ;; where do i keep half-written mail?
mu4e-trash-folder "/trash") ;; where do i move deleted mail?
mu4e-sent-folder "/sent" ;; where do I keep sent mail?
mu4e-drafts-folder "/drafts" ;; where do I keep half-written mail?
mu4e-trash-folder "/trash" ;; where do I move deleted mail?
mu4e-refile-folder "/archive") ;; where do I move message after completion?
@end lisp
@code{mu4e-maildir} takes an actual filesystem-path, the other folder names are
all relative to @code{mu4e-maildir}. The next step is telling @t{mu4e} how we
want to send mail.
@code{mu4e-maildir} takes an actual filesystem-path, the other folder names
are all relative to @code{mu4e-maildir}. The next step is telling @t{mu4e} how
we want to send mail.
@node Sending mail
@section Sending mail
@ -363,7 +375,7 @@ sent-messages folder. Other possible values are @code{'trash} (so the sent
message is copied to the trash-folder (@code{mu4e-trash-folder}), and
@code{'delete} to simply discard the message altogether.
For Gmail-IMAP you could add the following to your settings:
For Gmail-IMAP, you could add the following to your settings:
@verbatim
;; don't save messages to Sent Messages, Gmail/IMAP will take care of this
@ -373,15 +385,11 @@ For Gmail-IMAP you could add the following to your settings:
And that's it! We should be ready to go now.
@node Running mu4e
@chapter Running mu4e
@section Running mu4e
After the following the steps in @ref{Getting started}, we should now have a
working @t{mu4e} setup. In this chapter, we'll give a tour of the @t{mu4e}
program, and show its use.
@t{mu4e} consists of a number of views; the diagram shows how they relate to
each other, and the default key-bindings to get from one view to the next. In
the next sections we will describe what these keys actually @emph{do}.
After the following the steps in this chapter, we now hopefully have a working
@t{mu4e} setup. @t{mu4e} consists of a number of views, and in the next
chapter we go through all of them:
@menu
* Main view:: This is where we start
@ -390,6 +398,8 @@ the next sections we will describe what these keys actually @emph{do}.
* Editor view:: Creating / editing messages
@end menu
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.
@example
----------------------------------------------------------------------------
@ -420,7 +430,7 @@ E: Edit B: edit bookmark-search
@end example
@node Main view
@section Main view
@chapter Main view
After you have installed @t{mu4e} (@pxref{Getting started}), you can start it
with @code{M-x mu4e}. @t{mu4e} wil do some checks to ensure everything is set
@ -505,7 +515,7 @@ if you have actually set up mail-queuing. @ref{Queuing mail}.
@end itemize
@node Headers view
@section Headers view
@chapter Headers view
The headers view shows the results of a search query. There is a line for each
matching message, showing information about it. It looks something like the
@ -585,10 +595,11 @@ Q toggle full-search
marking
-------
d mark for moving to the trash folder
DEL,D mark for immediate deletion
DEL,D mark for complete deletion
m mark for moving to another maildir folder
r mark for refiling
+,- mark for flagging/unflagging
o,r mark message as unread, read
o,s mark message as unread, read (seen)
u unmark message at point
U unmark *all* messages
@ -619,15 +630,18 @@ q,z leave the headers buffer
@subsection Marking messages
@anchor{Marking messages}
When working with messages, usually the first step is @emph{marking} them for
a certain action, such as deleting them or moving them. Then, after one or
more marks are set, you execute (@key{x}) these marks. The two-step
mark-execute sequence is similar to what @t{dired} and som other emacs-based
programs do. This way, @t{mu4e} tries to be as quick as possible while
avoiding accidents.
The mark/unmark commands support the current @emph{region} (i.e., selection)
-- so, for example, if you the select ('mark' in emacs lingo) a number of
message (like you would select text in a buffer) and then press @key{DEL}, all
selected message will be marked for deletion.
The two-step mark-execute sequence is similar to what @t{dired} and som other
emacs-based programs do. This way, @t{mu4e} tries to be as quick as possible
while avoiding accidents.
You can mark all messages that match a certain pattern with @key{%}. In
addition, you can mark all messages in the current thread (@key{T}) or
sub-thread (@key{t}).
@ -718,7 +732,7 @@ You can change the selected window from the headers-view to the message-view
and vice-versa with @code{mu4e-select-other-view}, bound to @key{y}.
@node Message view
@section Message view
@chapter Message view
After selecting a message in the @ref{Headers view}, it will be shown in the
message view, for example:
@ -801,10 +815,10 @@ M-right next query
marking
-------
d mark for moving to the trash folder
DEL,D mark for immediate deletion
DEL,D mark for complete deletion
m mark for moving to another maildir folder
r mark for refiling
+,- mark for flagging/unflagging
o,r mark message as unread, read
u unmark message at point
U unmark *all* messages
@ -999,7 +1013,7 @@ details of the signatures found and whether they could be verified or not.
For more information, please see the @t{mu-verify} manual page.
@node Editor view
@section Editor view
@chapter Editor view
For its editor, @t{mu4e} re-uses Gnu's @t{message-mode}. For example, when
replying to a message, the editor view looks something like the following:
@ -1207,7 +1221,6 @@ man pages for details.
their destination until you switch it off again; so, be careful not to do this
accidentally.
@node Searching
@chapter Searching
@ -1478,16 +1491,17 @@ apply to messages:
@verbatim
| mark for | keybinding | description |
|--------------+-------------+--------------------------|
| trash | d | move to the trash folder |
| delete | D, <delete> | delete |
| move | m | move to some maildir |
| flag | + | mark as 'flagged' |
| unflag | - | remove 'flagged' mark |
| read | r | mark as read |
| unread | o | marks as unread |
| deferred | * | mark now, decide later |
| delete | D, <delete> | delete |
| flag | + | mark as 'flagged' |
| move | m | move to some maildir |
| read | s | mark as read (seen) |
| refile | r | mark for refiling |
| trash | d | move to the trash folder |
| unflag | - | remove 'flagged' mark |
| unmark | u | remove mark at point |
| unmark all | U | remove all marks |
| unread | o | marks as unread |
@end verbatim
After marking a header for something, the left-most columns shows a character
@ -1573,6 +1587,64 @@ need to remember is @key{%} for @code{mu4e-headers-mark-pattern}.
@end itemize
@node Dynamic folders
@chapter Dynamic folders
In @ref{Folders} we gave an example of setting the standard folders:
@lisp
(setq
mu4e-sent-folder "/sent" ;; where do I keep sent mail?
mu4e-drafts-folder "/drafts" ;; where do I keep half-written mail?
mu4e-trash-folder "/trash" ;; where do I move deleted mail?
mu4e-refile-folder "/archive") ;; where do I move message after completion?
@end lisp
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
different folders for refiling, based on the sender of the message.
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,
and returns the desired folder name.
For example, for the refile folder you could put something like the following
in your setup:
@lisp
(setq mu4e-refile-folder
(lambda (msg)
(cond
;; messages to the mu mailing list go to the /mu folder
((mu4e-message-contact-field-matches msg :to "mu-discuss@@googlegroups.com")
"/mu")
;; messages sent directly to me go to /archive
;; also `mu4e-user-mail-address-regexp' can be used
((mu4e-message-contact-field-matches msg :to "me@@example.com")
"/private")
;; message with football or soccer in the subject go to /football
((string-match "football\\|soccer" (mu4e-message-field msg :subject))
"/football)
;; everything else goes to /archive
(t
"/archive"))))
@end lisp
Let's look at this example a bit:
@itemize
@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
various convenience functions to deal which such messages
@item In this function, we use a @t{cond} control structure; the function
returns the first of the clauses that matches
@item Especially useful are the function @file{mu4e-message.el}; here we use
the convenience function @code{mu4e-message-contact-field-matches}, which
@end itemize
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
folder is the @emph{original} message, that is, the message you reply to or
forward. If there is not such message (for example when composing a new
message) the message parameter will be @t{nil}.
@node Actions
@chapter Actions
@ -1696,6 +1768,11 @@ body-text using text-to-speech.
If you have come up with any interesting actions that may be useful for
others, you are invited to contribute those.
@node Interaction with other tools
@chapter Interaction with other tools
@ -2304,11 +2381,9 @@ address management with @t{BBDB}; instead, we recommend using @t{mu4e}'s
built-in @ref{Address autocompletion}.
@item @emph{How can I automatically set the @t{From:} address for a
reply-message, based on some field in the original?} See @ref{Compose hooks}.
@item @emph{And what about customizable folders for sent messages, based on e.g.
the @t{From:} header?} Again, see @ref{Compose hooks}; alternatively, you can
periodically move messages from the main sent-folder to the specific
sent-folders. You can easily find those messages with a query like
@t{maildir:/sent from:myaddress@@example.com}.
@item @emph{And what about customizable folders for draft messages, sent
messages, trashed messages, based on e.g. the @t{From:} header?} See
@ref{Dynamic folders}.
@item @emph{How can I automatically add some header to an outgoing message?}
Once more, see @ref{Compose hooks}.
@item @emph{How can I easily include attachments in the messages I write?}