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

* mu4e: some doc improvements

Browse Source
This commit is contained in:
djcb
2012-10-07 16:54:24 +03:00
parent 1c6e882142
commit 3f6b8fb833
1 changed files with 73 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files

136
mu4e/mu4e.texi
View File

@ -1393,25 +1393,26 @@ You can also influence the sort order and whether threads are shown or not;
see @ref{Sort order and threading}. see @ref{Sort order and threading}.
@menu @menu
* Queries:: * Queries::Searching for messages
* Bookmarks:: * Bookmarks::Remembering queries
* Maildir searches:: * Maildir searches::Queries for maildirs
* Other search functionality:: * Other search functionality::Some more tricks
@end menu @end menu
@node Queries @node Queries
@section Queries @section Queries
The queries you can execute are the same ones that @code{mu find} @t{mu4e} queries are the same as the ones that @t{mu find}
understands@footnote{with the caveat that command-line queries are subject to understands@footnote{with the caveat that command-line queries are subject to
the shell's interpretation before @t{mu} sees them}. Please refer to the the shell's interpretation before @t{mu} sees them}. We give some examples
@code{mu-find} and @code{mu-easy} man pages for details and more examples. here, please refer to the @code{mu-find} and @code{mu-easy} man pages for
details and more examples.
@verbatim @verbatim
# get all messages about bananas # get all messages about bananas:
bananas bananas
# get all messages about bananas from john with an attachment # get all messages about bananas from John with an attachment:
from:john flag:attach bananas from:john flag:attach bananas
# get all messages with subject wombat in June 2009 # get all messages with subject wombat in June 2009
@ -1421,8 +1422,8 @@ subject:wombat date:20090601..20090630
maildir:/projects mime:application/pdf maildir:/projects mime:application/pdf
# get all messages about Rupert in the Sent Items folder # get all messages about Rupert in the Sent Items folder
# note that terms with spaces need quotes
maildir:"/Sent Items" rupert maildir:"/Sent Items" rupert
# note: terms with spaces need quoting
# get all important messages which are signed: # get all important messages which are signed:
flag:signed prio:high flag:signed prio:high
@ -1430,32 +1431,33 @@ flag:signed prio:high
# get all messages from Jim without an attachment: # get all messages from Jim without an attachment:
from:jim AND NOT flag:attach from:jim AND NOT flag:attach
# get all unread messages where the subject mentions Ångström: # get all unread messages where the subject mentions Angstrom:
# (search is case-insensitive and accent-insensitive)
subject:angstrom flag:unread subject:angstrom flag:unread
# get all unread messages between Mar-2002 and Aug-2003 about some bird # get all unread messages between Mar-2002 and Aug-2003 about some bird:
date:20020301..20030831 nightingale flag:unread date:20020301..20030831 nightingale flag:unread
# get today's messages # get today's messages:
date:today..now date:today..now
# get all messages we got in the last two weeks regarding emacs # get all messages we got in the last two weeks regarding emacs:
date:2w..now emacs date:2w..now emacs
# get mails with a subject soccer, Socrates, society... # get mails with a subject soccer, Socrates, society...:
# note: the '*' wildcard can only appear as the term's rightmost character
subject:soc* subject:soc*
# get all mails with attachment with filenames starting with 'pic'
# note: the '*' wildcard can only appear as the term's rightmost character # note: the '*' wildcard can only appear as the term's rightmost character
# get all mails with attachment with filenames starting with 'pic':
file:pic* file:pic*
# note: the '*' wildcard can only appear as the term's rightmost character
# get all messages with PDF attachments: # get all messages with PDF attachments:
mime:application/pdf mime:application/pdf
# get all messages with image attachments: # get all messages with image attachments:
# note: the '*' wildcard can only appear as the term's rightmost character
mime:image/* mime:image/*
# note: the '*' wildcard can only appear as the term's rightmost character
@end verbatim @end verbatim
@node Bookmarks @node Bookmarks
@ -1718,7 +1720,7 @@ Custom mark functions should be appended to the list
first character of this string determines its shortcut, so these should be first character of this string determines its shortcut, so these should be
unique. If necessary, simply prefix the name with a unique character. unique. If necessary, simply prefix the name with a unique character.
@item a predicate function taking two arguments @t{msg} and @t{param}. @t{msg} is the message @item a predicate function taking two arguments @t{msg} and @t{param}. @t{msg} is the message
plist (see @ref{The message s-expression} and @t{param} is a parameter plist (see @ref{Message functions} and @t{param} is a parameter
provided by the third of the marker elements (see the next item). The provided by the third of the marker elements (see the next item). The
predicate function should return non-nil if the message matches. predicate function should return non-nil if the message matches.
@item (optionally) a function that is evaluated once, and the result is passed as a @item (optionally) a function that is evaluated once, and the result is passed as a
@ -1726,7 +1728,7 @@ parameter to the predicate function. This is useful when user-input is needed.
@end itemize @end itemize
So, let's look at an example: suppose we want to match all messages that have So, let's look at an example: suppose we want to match all messages that have
more than @emph{n} recipients. We could do it like this: more than @emph{n} recipients -- we could do this with the following recipe:
@lisp @lisp
(add-to-list 'mu4e-headers-custom-markers (add-to-list 'mu4e-headers-custom-markers
@ -1738,24 +1740,26 @@ more than @emph{n} recipients. We could do it like this:
(read-number "Match messages with more recipients than: "))) t) (read-number "Match messages with more recipients than: "))) t)
@end lisp @end lisp
After evaluating this, pressing @key{&} lets you choose the custom marker After evaluating this expression, you can use it by pressing @key{&} in the
function, and ask you for the parameters. headers buffer to select a custom marker function, and then @key{M} to choose
this particular one (@t{M} because it is the first character of the
description).
As you can see, it's not very hard to define simple functions to match As you can see, it's not very hard to define simple functions to match
messages. There are some more examples in the defaults for messages. There are more examples in the defaults for
`mu4e-headers-custom-markers'; see @file{mu4e-headers.el}. @code{mu4e-headers-custom-markers}; see @file{mu4e-headers.el} and see
@ref{Extending mu4e} for general information about writing your own functions.
@node Dynamic folders @node Dynamic folders
@chapter Dynamic folders @chapter Dynamic folders
@ref{Folders} showed how to set the standard folders: @ref{Folders} explained how we can set @t{mu4e}'s special folders:
@lisp @lisp
(setq (setq
mu4e-sent-folder "/sent" ;; folder for sent messages mu4e-sent-folder "/sent" ;; sent messages
mu4e-drafts-folder "/drafts" ;; unfinished messages mu4e-drafts-folder "/drafts" ;; unfinished messages
mu4e-trash-folder "/trash" ;; trashed messages mu4e-trash-folder "/trash" ;; trashed messages
mu4e-refile-folder "/archive") ;; saved messages mu4e-refile-folder "/archive") ;; saved messages
@end lisp @end lisp
In some cases, having such static folders may not suffice - you may want to In some cases, having such static folders may not suffice - you may want to
@ -1766,22 +1770,23 @@ For this, instead of setting the standard folders to a string, you can set
them to be a @emph{function} that takes a message as parameter, and returns them to be a @emph{function} that takes a message as parameter, and returns
the desired folder name. the desired folder name.
This chapter shows how to do that. This chapter shows you how to do that. For a more general discussion of how to
extend @t{mu4e} and writing your own functions, see @ref{Extending mu4e}.
@menu @menu
* Smart refiling:: * Smart refiling:: Automatically choose the target folder
* Other dynamic folders:: * Other dynamic folders:: Flexible sent, trash, drafts
@end menu @end menu
@node Smart refiling @node Smart refiling
@section Smart refiling @section Smart refiling
It is sometimes convenient to move messages to some specific folder, based on It is sometimes convenient to move messages to a specific folder, based on
some of the message details -- @emph{refiling}(@key{r}). some of the message properties -- @emph{refiling}(@key{r}).
We can make this 'smart' with a dynamic refiling folder - each message We can make this 'smart' with a dynamic refiling folder, and a little bit of
automatically figures out the right folder to move to. For example, you could code to determine the target folder for each message. For example, you could
put something like the following in your setup: put something like the following in your setup:
@lisp @lisp
@ -1826,11 +1831,11 @@ matches the regular expression.
@node Other dynamic folders @node Other dynamic folders
@section 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
for messages. The message-parameter you receive for sent and draft folder is drafts-folders for messages. The message-parameter you receive for the sent
the @emph{original} message, that is, the message you reply to, forward. If and drafts folder is the @emph{original} message, that is, the message you
there is no such message (for example when composing a brand new message) the reply to, forward. If there is no such message (for example when composing a
message parameter is @t{nil}. brand new message) the message parameter is @t{nil}.
Let's look at an example of this. Suppose you want a different trash folder Let's look at an example of this. Suppose you want a different trash folder
for work-email. You can do so with something like the following: for work-email. You can do so with something like the following:
@ -1868,12 +1873,14 @@ You can invoke the actions with @key{a} for actions on messages, and @key{A}
for actions on attachments. In the following, we'll gives some examples of for actions on attachments. In the following, we'll gives some examples of
defining actions. defining actions.
For some general notes on extending @t{mu4e} and writing your own functions,
see @ref{Extending mu4e}.
@menu @menu
* Defining actions:: * Defining actions::
* Adding an action in the headers view:: * Adding an action in the headers view::
* Adding an action in the message view:: * Adding an action in the message view::
* Adding an attachment action:: * Adding an attachment action::
* What functions are available?::
* More example actions:: * More example actions::
@end menu @end menu
@ -1916,7 +1923,8 @@ Let's take a at some simple examples.
@section Adding an action in the headers view @section Adding an action in the headers view
Suppose we would like to inspect the number of recipients for a message in the Suppose we would like to inspect the number of recipients for a message in the
@ref{Headers view}. We could define the following function in our configuration: @ref{Headers view}. We could define the following function in our
configuration:
@lisp @lisp
(defun show-number-of-recipients (msg) (defun show-number-of-recipients (msg)
@ -1968,21 +1976,6 @@ The following counts the number of lines in an attachment, and define
'("ncount lines" . count-lines-in-attachment) t) '("ncount lines" . count-lines-in-attachment) t)
@end lisp @end lisp
@node What functions are available?
@section What functions are available?
@t{elisp} does not have a module-system, so it can be hard to see what
functions are internal, and which are usable for others as well.
To help a bit with this, all functions and variables in @t{mu4e} marked for
@emph{internal} use have the prefix @t{mu4e~}, while all the public ones use
@t{mu4e-}. The @t{~} was chosen because its ascii-code is after all the
letters, so they appear only at the end of completion buffers and the like.
Functions that start with @t{mu4e-view-} and @t{mu4e-headers-} should be
called only from that particular context (the message view and the headers
view, respectively).
@node More example actions @node More example actions
@section More example actions @section More example actions
@ -1991,9 +1984,6 @@ source distribution (see @key{C-h f mu4e-action-TAB}). For example, for
viewing messages in an external web browser, or listening to a message's viewing messages in an external web browser, or listening to a message's
body-text using text-to-speech. 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 @node Interaction with other tools
@appendix Interaction with other tools @appendix Interaction with other tools
@ -2696,9 +2686,18 @@ menu assumes the default key-bindings, as do the clicks-on-bookmarks.
@node Extending mu4e @node Extending mu4e
@appendix Extending mu4e @appendix Extending mu4e
@t{mu4e} is designed to be easily extendible - that is, write your own pieces @t{mu4e} is designed to be easily extendible - that is, write your own
of emacs-lisp to make @t{mu4e} is a specific way. Here, we provide some notes emacs-lisp to make @t{mu4e} behave ins a specific way. Here, we provide some
/ tips for doing so. guidelines / tips for doing so.
The typical places for extending @t{mu4e} are:
@itemize
@item writing your own mark functions: see @ref{Custom mark functions}
@item defining @emph{actions} for headers, messages and attachments: see
@ref{Actions}
@item setting up dynamic folders: see @ref{Dynamic folders}
@end itemize
@menu @menu
* What functions are available:: * What functions are available::
@ -2712,6 +2711,9 @@ of emacs-lisp to make @t{mu4e} is a specific way. Here, we provide some notes
@node What functions are available @node What functions are available
@section What functions are (not) available? @section What functions are (not) available?
@t{elisp} does not have a module-system, so it can be hard to see what
functions are internal, and which are usable for others as well.
The whole of @t{mu4e} consists of hundreds of elisp functions. However, many The whole of @t{mu4e} consists of hundreds of elisp functions. However, many
of those (more than 50%) are for @emph{internal} use; you can recognize them of those (more than 50%) are for @emph{internal} use; you can recognize them
easily, because they all start with @code{mu4e~}. They make all kinds of easily, because they all start with @code{mu4e~}. They make all kinds of