emacs
/
mu
mirror of https://github.com/djcb/mu.git
1
0
Fork 0
Code Issues Releases Wiki Activity

update documentation

This commit is contained in:
Dirk-Jan C. Binnema 2022-05-06 22:13:18 +03:00
parent 8c3d1ae90a
commit ec500d3ed4
3 changed files with 235 additions and 229 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
NEWS.org
View File

@ -46,7 +46,7 @@
- the ~verify~ command for checking signatures has been updated, and is more - the ~verify~ command for checking signatures has been updated, and is more
informative informative
- new commands ~fields~ and ~flags~ give information about the message fields and - a new command ~mu fields~ provides information about the message fields and
flags for use in queries. The information is the same information that ~mu~ flags for use in queries. The information is the same information that ~mu~
uses and so stays up to date. uses and so stays up to date.
@ -88,12 +88,16 @@
- A new ~defcustom~, ~mu4e-view-open-program~ for starting the appropriate - A new ~defcustom~, ~mu4e-view-open-program~ for starting the appropriate
program for a give file (e.g., ~xdg-open~). There are some reasonable program for a give file (e.g., ~xdg-open~). There are some reasonable
defaults for various systems. defaults for various systems. This can also be set to a function.
- For performance testing, you can set the variable - For performance testing, you can set the variable
~mu4e-headers-report-render-time~ to ~t~ and ~mu4e~ will report the ~mu4e-headers-report-render-time~ to ~t~ and ~mu4e~ will report the
search/rendering speed of each query operation. search/rendering speed of each query operation.
- As an additional measure to limit the number of contacts that mu4e loads
for auto-completions, there's ~mu4e-compose-complete-max~, which by default
is set to *2000*, so you can auto-complete your 2000 closest friends.
- Removed ~make-mu4e-bookmark~ which was obsoleted in version 1.3.9. - Removed ~make-mu4e-bookmark~ which was obsoleted in version 1.3.9.
- undo is now supported across message-saves - undo is now supported across message-saves
@ -123,8 +127,8 @@
- =mu4e-proc.el= has been renamed =mu4e-server.el=. - =mu4e-proc.el= has been renamed =mu4e-server.el=.
- Between =mu= and =mu4e=, contact cells are now represented as a plist ~(:name - Between =mu= and =mu4e=, contact cells are now represented as a plist ~(:name
"Foo Bar" :email "foobar@example.com")~ rather than a cons-cell ~("Foo "Foo Bar" :email "foobar@example.com")~ rather than a cons-cell ~("Foo
Bar" . "foobar@example.com").~ Bar" . "foobar@example.com").~
- Because of all these changes, it is recommended you remove older version - Because of all these changes, it is recommended you remove older version

13
mu/mu-help-strings.txt
View File

@ -1,6 +1,6 @@
#-*-mode:org-*- #-*-mode:org-*-
# #
# Copyright (C) 2012-2020 Dirk-Jan C. Binnema <djcb@djcbsoftware.nl> # Copyright (C) 2012-2022 Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
# #
# This program is free software; you can redistribute it and/or modify # This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by # it under the terms of the GNU General Public License as published by
@ -62,6 +62,15 @@ mu extract is the mu command to display and save message parts
(attachments), and open them with other tools. (attachments), and open them with other tools.
#END #END
#BEGIN MU_CONFIG_CMD_FIELDS
#STRING
mu fields
#STRING
mu fields produces a table with all messages fields and flags. This
is useful for writing query expressions.
#END
#BEGIN MU_CONFIG_CMD_FIND #BEGIN MU_CONFIG_CMD_FIND
#STRING #STRING
mu find [options] <search expression> mu find [options] <search expression>
@ -91,6 +100,7 @@ is one of:
add - add message to database add - add message to database
cfind - find a contact cfind - find a contact
extract - extract parts/attachments from messages extract - extract parts/attachments from messages
fields - show table of all query fields and flags
find - query the message database find - query the message database
help - get help help - get help
index - index messages index - index messages
@ -170,7 +180,6 @@ Run the 'msgs-per-month' script, and pass it the '--textonly' parameter:
$ mu msgs-per-month --textonly $ mu msgs-per-month --textonly
#END #END
#BEGIN MU_CONFIG_CMD_VERIFY #BEGIN MU_CONFIG_CMD_VERIFY
#STRING #STRING
mu verify [options] <msgfile> mu verify [options] <msgfile>

439
mu4e/mu4e.texi
View File

@ -12,7 +12,7 @@
@c %**end of header @c %**end of header
@copying @copying
Copyright @copyright{} 2012-2020 Dirk-Jan C. Binnema Copyright @copyright{} 2012-2022 Dirk-Jan C. Binnema
@quotation @quotation
Permission is granted to copy, distribute and/or modify this document Permission is granted to copy, distribute and/or modify this document
@ -55,7 +55,7 @@ Documentation License.''
Welcome to @t{mu4e} @value{VERSION}. Welcome to @t{mu4e} @value{VERSION}.
@t{mu4e} (@t{mu}-for-emacs) is an e-mail client for GNU Emacs version @t{mu4e} (@t{mu}-for-emacs) is an e-mail client for GNU Emacs version
24.4 or higher, built on top of the 25.3 or newer, built on top of the
@t{mu}@footnote{@url{https://www.djcbsoftware.nl/code/mu}} e-mail search @t{mu}@footnote{@url{https://www.djcbsoftware.nl/code/mu}} e-mail search
engine. @t{mu4e} is optimized for quickly processing large amounts of engine. @t{mu4e} is optimized for quickly processing large amounts of
e-mail. e-mail.
@ -63,8 +63,8 @@ e-mail.
Some of its highlights: Some of its highlights:
@itemize @itemize
@item Fully search-based: there are no folders@footnote{that is, instead of @item Fully search-based: there are no folders@footnote{that is, instead of
folders, you use queries that match messages in a particular folder}, only folders, you use queries that match messages in a particular folder},
queries. only queries.
@item Fully documented, with example configurations @item Fully documented, with example configurations
@item User-interface optimized for speed, with quick key strokes for common actions @item User-interface optimized for speed, with quick key strokes for common actions
@item Support for non-English languages (so ``angstrom'' matches ``Ångström'') @item Support for non-English languages (so ``angstrom'' matches ``Ångström'')
@ -81,8 +81,8 @@ basic configuration and explain its daily use. We also show you how you
can customize @t{mu4e} for your special needs. can customize @t{mu4e} for your special needs.
At the end of the manual, there are some example configurations, to get At the end of the manual, there are some example configurations, to get
you up to speed quickly: @ref{Example configs}. There's also a you up to speed quickly: @ref{Example configs}. There's also a section
section with answers to frequently asked questions, @ref{FAQ}. with answers to frequently asked questions, @ref{FAQ}.
@menu @menu
* Introduction:: Where to begin * Introduction:: Where to begin
@ -167,9 +167,7 @@ delegated to other tools, such as
@t{fetchmail}@footnote{@url{http://www.fetchmail.info/}}; As long as @t{fetchmail}@footnote{@url{http://www.fetchmail.info/}}; As long as
the messages end up in a maildir, @t{mu4e} and @t{mu} are happy to the messages end up in a maildir, @t{mu4e} and @t{mu} are happy to
deal with them. deal with them.
@item @t{mu4e} also does @emph{not} implement sending of messages; instead, it @item @t{mu4e} also does @emph{not} implement sending of messages; instead, it depends on @t{smtpmail} (@inforef{Top,,smtpmail}), which is part of Emacs. In addition, @t{mu4e} piggybacks on Gnus' message editor;
depends on @t{smtpmail} (@inforef{Top,,smtpmail}), which is part of
Emacs. In addition, @t{mu4e} piggybacks on Gnus' message editor;
@inforef{Top,,message}. @inforef{Top,,message}.
@end itemize @end itemize
@ -218,6 +216,7 @@ After these steps, @t{mu4e} should be ready to go!
@menu @menu
* Requirements:: What is needed * Requirements:: What is needed
* Versions:: Available stable and development versions
* Installation:: How to install @t{mu} and @t{mu4e} * Installation:: How to install @t{mu} and @t{mu4e}
* Getting mail:: Getting mail from a server * Getting mail:: Getting mail from a server
* Initializing the message store:: Settings things up * Initializing the message store:: Settings things up
@ -234,10 +233,9 @@ After these steps, @t{mu4e} should be ready to go!
@section Requirements @section Requirements
@t{mu}/@t{mu4e} are known to work on a wide variety of Unix- and @t{mu}/@t{mu4e} are known to work on a wide variety of Unix- and
Unix-like systems, including many Linux distributions, OS X and Unix-like systems, including many Linux distributions, OS X and FreeBSD,
FreeBSD, and even on MS-Windows (with Cygwin). Emacs 24 or and even on MS-Windows (with Cygwin). Emacs 25.3 or higher is required,
higher is required, as well as as well as Xapian@footnote{@url{https://xapian.org/}} and
Xapian@footnote{@url{https://xapian.org/}} and
GMime@footnote{@url{http://spruce.sourceforge.net/gmime/}}. GMime@footnote{@url{http://spruce.sourceforge.net/gmime/}}.
@t{mu} has optional support for both versions 2.2 and 3.0 of the Guile @t{mu} has optional support for both versions 2.2 and 3.0 of the Guile
@ -245,17 +243,32 @@ GMime@footnote{@url{http://spruce.sourceforge.net/gmime/}}.
require GTK+ 3.x and Webkit. require GTK+ 3.x and Webkit.
If you intend to compile @t{mu} yourself, you need to have the typical If you intend to compile @t{mu} yourself, you need to have the typical
development tools, such as C and C++ compilers (both @command{gcc} and development tools, such as C and C++17 compilers (both @command{gcc} and
@command{clang} should work), GNU Autotools and @command{make}, and @command{clang} should work), @command{meson} and @command{make}, and
the development packages for GMime 3.x, GLib and Xapian. Optionally, the development packages for GMime 3.x, GLib and Xapian. Optionally, you
you also need the development packages for GTK+, Webkit and Guile. also need the development packages for GTK+, Webkit and Guile.
@node Versions
@section Versions
The stable (release) versions have even minor version numbers, while the
development versions have odd ones. So, for example, 1.6.10 is a stable
version, while the 1.7.15 is the development version.
The stable versions only receive bug fixes after being released, while
the development versions get new features, fixes, and, perhaps, bugs,
and are meant for people with a tolerance for that.
There is support for one release branch; so, when the 1.8 release is
available (and a new 1.9 development series start), no more changes are
expected for the 1.6 releases.
@node Installation @node Installation
@section Installation @section Installation
@t{mu4e} is part of @t{mu} --- by installing the latter, the former is @t{mu4e} is part of @t{mu} --- by installing the latter, the former is
installed as well. Some Linux distributions provide packaged versions installed as well. Some Linux distributions provide packaged versions of
of @t{mu}/@t{mu4e}; if you can use those, there is no need to compile @t{mu}/@t{mu4e}; if you can use those, there is no need to compile
anything yourself. However, if there are no packages for your anything yourself. However, if there are no packages for your
distribution, if they are outdated, or if you want to use the latest distribution, if they are outdated, or if you want to use the latest
development versions, you can follow the steps below. development versions, you can follow the steps below.
@ -281,34 +294,6 @@ $ sudo apt-get install libgmime-3.0-dev libxapian-dev emacs
$ sudo yum install gmime30-devel xapian-core-devel emacs $ sudo yum install gmime30-devel xapian-core-devel emacs
@end example @end example
@subsection Building on Msys2
@example
# 1) install makepkg tool
pacman -S base-devel msys-devel gcc git
# 2) clone packages repo
cd ~
git clone https://github.com/msys2-unofficial/MSYS2-packages.git --depth=1
# make and install dependencies
cd ~/MSYS2-packages/xapian-core
makepkg -s
pacman -U xapian-core-1.4.15-1-x86_64.pkg.tar.xz
cd ~/MSYS2-packages/gmime3
makepkg -s
pacman -U gmime3-devel-3.2.6-1-x86_64.pkg.tar.xz
# 4) make and install mu from git (changes versions as needed)
cd ~/MSYS2-packages/mu
makepkg -sfp PKGBUILD-git
pacman -U mu-git-2020-03-01-r4854.17f38dc4-1-x86_64.pkg.tar.xz
@end example
@subsection Building from a release tarball @subsection Building from a release tarball
@anchor{Building from a release tarball} @anchor{Building from a release tarball}
@ -339,16 +324,15 @@ $ git clone git://github.com/djcb/mu.git
$ cd mu $ cd mu
$ ./autogen.sh $ ./autogen.sh
$ make $ make
$ make install install $ make install
# ^^^ perhaps with 'sudo'
@end example @end example
After that, @t{make} (which is just @t{ninja -C build} under the After that, @t{make} (which is just @t{ninja -C build} under the covers)
covers) should be enough for rebuilding. should be enough for rebuilding.
Alternatively, you can also use the (deprecated) @t{autotools} build setup, Alternatively, you can also use the (now deprecated) @t{autotools} build
assuming you have autotools (@t{autoconf}, @t{automake}, @t{libtool}, setup, assuming you have autotools (@t{autoconf}, @t{automake},
@t{texinfo}) installed: @t{libtool}, @t{texinfo}) installed:
@example @example
# get from git (alternatively, use a github tarball) # get from git (alternatively, use a github tarball)
@ -362,16 +346,16 @@ $ sudo make install
(Xapian, GMime and their dependencies must be installed). (Xapian, GMime and their dependencies must be installed).
After this, @t{mu} and @t{mu4e} should be installed @footnote{there's After this, @t{mu} and @t{mu4e} should be installed @footnote{there's a
a hard dependency between versions of @t{mu4e} and @t{mu} --- you hard dependency between versions of @t{mu4e} and @t{mu} --- you cannot
cannot combine different versions} on your system, and be available combine different versions} on your system, and be available from the
from the command line and in Emacs. command line and in Emacs.
You may need to restart Emacs, so it can find @t{mu4e} in its You may need to restart Emacs, so it can find @t{mu4e} in its
@code{load-path}. If, even after restarting, Emacs cannot find @code{load-path}. If, even after restarting, Emacs cannot find @t{mu4e},
@t{mu4e}, you may need to add it to your @code{load-path} explicitly; you may need to add it to your @code{load-path} explicitly; check where
check where @t{mu4e} is installed, and add something like the @t{mu4e} is installed, and add something like the following to your
following to your configuration before trying again: configuration before trying again:
@lisp @lisp
;; the exact path may differ --- check it ;; the exact path may differ --- check it
(add-to-list 'load-path "/usr/local/share/emacs/site-lisp/mu4e") (add-to-list 'load-path "/usr/local/share/emacs/site-lisp/mu4e")
@ -404,14 +388,14 @@ is required:
into a maildir (@file{~/Maildir}, often). Because it is such a common into a maildir (@file{~/Maildir}, often). Because it is such a common
case, there is a full example of setting @t{mu4e} up with case, there is a full example of setting @t{mu4e} up with
@t{offlineimap} and Gmail; @pxref{Gmail configuration}. @t{offlineimap} and Gmail; @pxref{Gmail configuration}.
@item @emph{Using a local mail server} --- if you are using a local mail-server @item @emph{Using a local mail server} --- if you are using a local mail- server
(such as @t{postfix} or @t{qmail}), you can teach them to deliver into (such as @t{postfix} or @t{qmail}), you can teach them to deliver into
a maildir as well, maybe in combination with @t{procmail}. A bit of a maildir as well, maybe in combination with @t{procmail}. A bit of
googling should be able to provide you with the details. googling should be able to provide you with the details.
@end itemize @end itemize
The maildir must be on a single file-system; and symbolic links are While a @t{mu} only supports a single Maildir, it can be spread across
not supported. different file-systems; and symbolic links are supported.
@node Initializing the message store @node Initializing the message store
@section Initializing the message store @section Initializing the message store
@ -437,7 +421,7 @@ You can add some e-mail addresses, so @t{mu} recognizes them as yours:
indexing messages. If you want to change them, you need to @t{init} indexing messages. If you want to change them, you need to @t{init}
once again. once again.
The addresses can also be basic POSIX regular expressions, wrapped in The addresses may also be basic POSIX regular expressions, wrapped in
slashes, for example: slashes, for example:
@example @example
@ -458,8 +442,8 @@ We can do that from @t{mu4e} --- @ref{Main view}, but the first time,
it is a good idea to run it from the command line, which makes it it is a good idea to run it from the command line, which makes it
easier to verify that everything works correctly. easier to verify that everything works correctly.
Assuming that your maildir is at @file{~/Maildir}, we issue the following Assuming that your maildir is at @file{~/Maildir}, we issue the
command: following command:
@example @example
$ mu index $ mu index
@end example @end example
@ -472,16 +456,16 @@ The indexing process may take a few minutes the first time you do it
only scans messages that are new or have changed. Indexing is discussed only scans messages that are new or have changed. Indexing is discussed
in full detail in the @t{mu-index} man-page. in full detail in the @t{mu-index} man-page.
After the indexing process has finished, you can quickly test if everything After the indexing process has finished, you can quickly test if
worked, by trying some command-line searches, for example everything worked, by trying some command-line searches, for example
@example @example
$ mu find hello $ mu find hello
@end example @end example
which lists all messages that match @t{hello}. For more examples of searches, which lists all messages that match @t{hello}. For more examples of
see @ref{Queries}, or check the @t{mu-find} and @t{mu-easy} man pages. If all searches, see @ref{Queries}, or check the @t{mu-find} and @t{mu-easy}
of this worked well, we are well on our way setting things up; the next step man pages. If all of this worked well, we are well on our way setting
is to do some basic configuration for @t{mu4e}. things up; the next step is to do some basic configuration for @t{mu4e}.
@node Basic configuration @node Basic configuration
@section Basic configuration @section Basic configuration
@ -495,8 +479,8 @@ it. So, add to your @file{~/.emacs} (or its moral equivalent, such as
@end lisp @end lisp
If Emacs complains that it cannot find @t{mu4e}, check your If Emacs complains that it cannot find @t{mu4e}, check your
@code{load-path} and make sure that @t{mu4e}'s installation directory is part @code{load-path} and make sure that @t{mu4e}'s installation directory is
of it. If not, you can add it: part of it. If not, you can add it:
@lisp @lisp
(add-to-list 'load-path MU4E-PATH) (add-to-list 'load-path MU4E-PATH)
@ -524,10 +508,10 @@ situation. See @ref{Dynamic folders} for details.}:
mu4e-refile-folder "/archive") ;; saved messages mu4e-refile-folder "/archive") ;; saved messages
@end lisp @end lisp
Note, the folder names are all relative to the root-maildir (see the The folder (maildir) names are all relative to the root-maildir (see the
output of @command{mu info}). If you use @t{mu4e-context}, see output of @command{mu info}). If you use @t{mu4e-context}, see
@ref{Contexts and special folders} for what that means for these @ref{Contexts and special folders} for what that means for these special
special folders. folders.
@node Retrieval and indexing @node Retrieval and indexing
@section Retrieval and indexing with mu4e @section Retrieval and indexing with mu4e
@ -657,25 +641,27 @@ A very minimal setup:
(setq smtpmail-smtp-server "smtp.example.org") (setq smtpmail-smtp-server "smtp.example.org")
@end lisp @end lisp
Since @t{mu4e} (re)uses the same @t{message mode} and @t{smtpmail} that Gnus Since @t{mu4e} (re)uses the same @t{message mode} and @t{smtpmail} that
uses, many settings for those also apply to @t{mu4e}. Gnus uses, many settings for those also apply to @t{mu4e}.
@subsection Dealing with sent messages @subsection Dealing with sent messages
By default, @t{mu4e} puts a copy of messages you sent in the folder determined By default, @t{mu4e} puts a copy of messages you sent in the folder
by @code{mu4e-sent-folder}. In some cases, this may not be what you want - determined by @code{mu4e-sent-folder}. In some cases, this may not be
for example, when using Gmail-over-@abbr{IMAP}, this interferes with Gmail's what you want - for example, when using Gmail-over-@abbr{IMAP}, this
handling of the sent messages folder, and you may end up with duplicate interferes with Gmail's handling of the sent messages folder, and you
messages. may end up with duplicate messages.
You can use the variable @code{mu4e-sent-messages-behavior} to customize what You can use the variable @code{mu4e-sent-messages-behavior} to customize
happens with sent messages. The default is the symbol @code{sent} which, as what happens with sent messages. The default is the symbol @code{sent}
mentioned, causes the message to be copied to your sent-messages folder. Other which, as mentioned, causes the message to be copied to your
possible values are the symbols @code{trash} (the sent message is moved to the sent-messages folder. Other possible values are the symbols @code{trash}
trash-folder (@code{mu4e-trash-folder}), and @code{delete} to simply discard (the sent message is moved to the trash-folder
the sent message altogether (so Gmail can deal with it). (@code{mu4e-trash-folder}), and @code{delete} to simply discard the sent
message altogether (so Gmail can deal with it).
For Gmail-over-@abbr{IMAP}, you could add the following to your settings: For Gmail-over-@abbr{IMAP}, you could add the following to your
settings:
@verbatim @verbatim
;; don't save messages to Sent Messages, Gmail/IMAP takes care of this ;; don't save messages to Sent Messages, Gmail/IMAP takes care of this
(setq mu4e-sent-messages-behavior 'delete) (setq mu4e-sent-messages-behavior 'delete)
@ -822,8 +808,9 @@ bookmarked query first before invoking it, use @key{B}.
Next to each bookmark there is the number of (unread/all) messages Next to each bookmark there is the number of (unread/all) messages
that match. that match.
Bookmarks are stored in the variable @code{mu4e-bookmarks}; you can add your Bookmarks are stored in the variable @code{mu4e-bookmarks}; you can add
own and/or replace the default ones; @xref{Bookmarks}. For instance: your own and/or replace the default ones; @xref{Bookmarks}. For
instance:
@lisp @lisp
(add-to-list 'mu4e-bookmarks (add-to-list 'mu4e-bookmarks
;; add bookmark for recent messages on the Mu mailing list. ;; add bookmark for recent messages on the Mu mailing list.
@ -846,12 +833,14 @@ which would be disruptive in this case.
Finally, there are some @emph{Misc} (miscellaneous) actions: Finally, there are some @emph{Misc} (miscellaneous) actions:
@itemize @itemize
@item @t{[U]pdate email & database} executes the shell-command in the variable @item @t{[U]pdate email & database} executes the shell-command in the variable
@code{mu4e-get-mail-command}, and afterwards updates the @t{mu} database; @code{mu4e-get-mail-command}, and afterwards updates the @t{mu}
see @ref{Indexing your messages} and @ref{Getting mail} for details. database; see @ref{Indexing your messages} and @ref{Getting mail} for
details.
@item @t{toggle [m]ail sending mode (direct)} toggles between sending @item @t{toggle [m]ail sending mode (direct)} toggles between sending
mail directly, and queuing it first (for example, when you are offline), and mail directly, and queuing it first (for example, when you are offline),
@t{[f]lush queued mail} flushes any queued mail. This item is visible only and @t{[f]lush queued mail} flushes any queued mail. This item is
if you have actually set up mail-queuing. @ref{Queuing mail} visible only if you have actually set up mail-queuing. @ref{Queuing
mail}
@item @t{[A]bout mu4e} provides general information about the program @item @t{[A]bout mu4e} provides general information about the program
@item @t{[H]elp} shows help information for this view @item @t{[H]elp} shows help information for this view
@item Finally, @t{[q]uit mu4e} quits your @t{mu4e}-session @item Finally, @t{[q]uit mu4e} quits your @t{mu4e}-session
@ -900,14 +889,14 @@ Some notes to explain what you see in the example:
@itemize @itemize
@item The fields shown in the headers view can be influenced by customizing @item The fields shown in the headers view can be influenced by customizing
the variable @code{mu4e-headers-fields}; see @code{mu4e-header-info} for the the variable @code{mu4e-headers-fields}; see @code{mu4e-header-info} for
list of built-in fields. Apart from the built-in fields, you can also create the list of built-in fields. Apart from the built-in fields, you can
custom fields using @code{mu4e-header-info-custom}; see @ref{HV Custom also create custom fields using @code{mu4e-header-info-custom}; see
headers} for details. @ref{HV Custom headers} for details.
@item By default, the date is shown with the @t{:human-date} field, which @item By default, the date is shown with the @t{:human-date} field, which
shows the @emph{time} for today's messages, and the @emph{date} for older shows the @emph{time} for today's messages, and the @emph{date} for
messages. If you do not want to distinguish between `today' and `older', you can use older messages. If you do not want to distinguish between `today' and
the @t{:date} field instead. `older', you can use the @t{:date} field instead.
@item You can customize the date and time formats with the variable @item You can customize the date and time formats with the variable
@code{mu4e-headers-date-format} and @code{mu4e-headers-time-format}, @code{mu4e-headers-date-format} and @code{mu4e-headers-time-format},
respectively. In the example, we use @code{:human-date}, which shows the respectively. In the example, we use @code{:human-date}, which shows the
@ -924,10 +913,11 @@ mouse click, or @key{O}. Not all fields allow sorting.
@item Instead of showing the @t{From:} and @t{To:} fields separately, you @item Instead of showing the @t{From:} and @t{To:} fields separately, you
can use From/To (@t{:from-or-to} in @code{mu4e-headers-fields} as a more can use From/To (@t{:from-or-to} in @code{mu4e-headers-fields} as a more
compact way to convey the most important information: it shows @t{From:} compact way to convey the most important information: it shows @t{From:}
@emph{except} when the e-mail was sent by the user (i.e., you) --- in that case @emph{except} when the e-mail was sent by the user (i.e., you) --- in
it shows @t{To:} (prefixed by @t{To}@footnote{You can customize this by that case it shows @t{To:} (prefixed by @t{To}@footnote{You can
changing the variable @code{mu4e-headers-from-or-to-prefix} (a cons cell)}, as customize this by changing the variable
in the example above). @code{mu4e-headers-from-or-to-prefix} (a cons cell)}, as in the example
above).
@item The `List' field shows the mailing-list a message is sent to; @item The `List' field shows the mailing-list a message is sent to;
@code{mu4e} tries to create a convenient shortcut for the mailing-list @code{mu4e} tries to create a convenient shortcut for the mailing-list
name; the variable @code{mu4e-user-mailing-lists} can be used to add name; the variable @code{mu4e-user-mailing-lists} can be used to add
@ -960,9 +950,9 @@ headers-view.
@node Keybindings @node Keybindings
@section Keybindings @section Keybindings
Using the below key bindings, you can do various things with these messages; Using the below key bindings, you can do various things with these
these actions are also listed in the @t{Mu4e} menu in the Emacs messages; these actions are also listed in the @t{Mu4e} menu in the
menu bar. Emacs menu bar.
@verbatim @verbatim
key description key description
@ -1040,18 +1030,19 @@ move. After one or more messages are marked, you can then execute
mark-execute sequence is similar to what e.g. @t{dired} does. It is how mark-execute sequence is similar to what e.g. @t{dired} does. It is how
@t{mu4e} tries to be as quick as possible, while avoiding accidents. @t{mu4e} tries to be as quick as possible, while avoiding accidents.
The mark/unmark commands support the @emph{region} (i.e., ``selection'') --- The mark/unmark commands support the @emph{region} (i.e., ``selection'')
so, for example, if you select some messages and press @key{DEL}, all messages --- so, for example, if you select some messages and press @key{DEL},
in the region are marked for deletion. all messages in the region are marked for deletion.
You can mark all messages that match a certain pattern with @key{%}. In 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 addition, you can mark all messages in the current thread (@key{T}) or
sub-thread (@key{t}). sub-thread (@key{t}).
When you do a new search or refresh the headers buffer while you still have When you do a new search or refresh the headers buffer while you still
marked messages, you are asked what to do with those marks --- whether to have marked messages, you are asked what to do with those marks ---
@emph{apply} them before leaving, or @emph{ignore} them. This behavior can be whether to @emph{apply} them before leaving, or @emph{ignore} them. This
influenced with the variable @code{mu4e-headers-leave-behavior}. behavior can be influenced with the variable
@code{mu4e-headers-leave-behavior}.
For more information about marking, see @ref{Marking}. For more information about marking, see @ref{Marking}.
@ -1066,17 +1057,18 @@ the top-level messages are sorted by the date of the @emph{newest}
message in the thread. message in the thread.
The header field used for sorting is indicated by ``@t{V}'' or The header field used for sorting is indicated by ``@t{V}'' or
``@t{^}''@footnote{or you can use little graphical triangles; see variable ``@t{^}''@footnote{or you can use little graphical triangles; see
@code{mu4e-use-fancy-chars}}, indicating the sort order (descending or variable @code{mu4e-use-fancy-chars}}, indicating the sort order
ascending, respectively). (descending or ascending, respectively).
You can change the sort order by clicking the corresponding column with the You can change the sort order by clicking the corresponding column with
mouse, or with @kbd{M-x mu4e-headers-change-sorting} (@key{O}); note that not the mouse, or with @kbd{M-x mu4e-headers-change-sorting} (@key{O}); note
all fields can be used for sorting. You can toggle threading on/off using that not all fields can be used for sorting. You can toggle threading
@kbd{M-x mu4e-headers-toggle-threading} or @key{P}. For both of these functions, on/off using @kbd{M-x mu4e-headers-toggle-threading} or @key{P}. For
unless you provide a prefix argument (@key{C-u}), the current search is both of these functions, unless you provide a prefix argument
updated immediately using the new parameters. You can toggle full-search (@key{C-u}), the current search is updated immediately using the new
(@ref{Searching}) using @kbd{M-x mu4e-headers-toggle-full-search} or @key{Q}. parameters. You can toggle full-search (@ref{Searching}) using @kbd{M-x
mu4e-headers-toggle-full-search} or @key{Q}.
Note that with threading enabled, the sorting is exclusively by date, Note that with threading enabled, the sorting is exclusively by date,
regardless of the column clicked. regardless of the column clicked.
@ -1090,9 +1082,9 @@ search results.
@node HV Custom headers @node HV Custom headers
@section Custom headers @section Custom headers
Sometimes the normal headers that @t{mu4e} offers (Date, From, To, Subject, Sometimes the normal headers that @t{mu4e} offers (Date, From, To,
etc.)@: may not be enough. For these cases, @t{mu4e} offers @emph{custom Subject, etc.)@: may not be enough. For these cases, @t{mu4e} offers
headers} in both the headers-view and the message-view. @emph{custom headers} in both the headers-view and the message-view.
You can do so by adding a description of your custom header to You can do so by adding a description of your custom header to
@code{mu4e-header-info-custom}, which is a list of custom headers. @code{mu4e-header-info-custom}, which is a list of custom headers.
@ -1154,21 +1146,22 @@ actions.
Using the @emph{Split view}, we can see the @ref{Headers view} and the Using the @emph{Split view}, we can see the @ref{Headers view} and the
@ref{Message view} next to each other, with the message selected in the @ref{Message view} next to each other, with the message selected in the
former, visible in the latter. You can influence the way the splitting is done former, visible in the latter. You can influence the way the splitting
by customizing the variable @code{mu4e-split-view}. Possible values are: is done by customizing the variable @code{mu4e-split-view}. Possible
values are:
@itemize @itemize
@item @t{horizontal} (this is the default): display the message view below the @item @t{horizontal} (this is the default): display the message view below the
header view. Use @code{mu4e-headers-visible-lines} the set the number of lines header view. Use @code{mu4e-headers-visible-lines} the set the number of
shown (default: 8). lines shown (default: 8).
@item @t{vertical}: display the message view on the @item @t{vertical}: display the message view on the
right side of the header view. Use @code{mu4e-headers-visible-columns} to set right side of the header view. Use @code{mu4e-headers-visible-columns} to set
the number of visible columns (default: 30). the number of visible columns (default: 30).
@item @t{single-window}: single window mode. Single-window mode tries to @item @t{single-window}: single window mode. Single-window mode tries to
minimize mu4e window operations (opening, killing, resizing, etc) and buffer minimize mu4e window operations (opening, killing, resizing, etc) and
changes, while still retaining the view and headers buffers. In addition, it buffer changes, while still retaining the view and headers buffers. In
replaces mu4e main view with a minibuffer prompt containing the same addition, it replaces mu4e main view with a minibuffer prompt containing
information. the same information.
@item anything else: don't do any splitting @item anything else: don't do any splitting
@end itemize @end itemize
@ -1234,20 +1227,21 @@ An example message view:
Some notes: Some notes:
@itemize @itemize
@item The variable @code{mu4e-view-fields} determines the header fields to be @item The variable @code{mu4e-view-fields} determines the header fields to be
shown; see @code{mu4e-header-info} for a list of built-in fields. Apart from shown; see @code{mu4e-header-info} for a list of built-in fields. Apart
the built-in fields, you can also create custom fields using from the built-in fields, you can also create custom fields using
@code{mu4e-header-info-custom}; see @ref{MSGV Custom headers}. @code{mu4e-header-info-custom}; see @ref{MSGV Custom headers}.
@item For search-related operations, see @ref{Searching}. @item For search-related operations, see @ref{Searching}.
@item You can scroll down the message using @key{SPC}; if you do this at the @item You can scroll down the message using @key{SPC}; if you do this at the
end of a message,it automatically takes you to the next one. If you want to end of a message,it automatically takes you to the next one. If you want
prevent this behavior, set @code{mu4e-view-scroll-to-next} to @code{nil}. to prevent this behavior, set @code{mu4e-view-scroll-to-next} to
@code{nil}.
@end itemize @end itemize
@node MSGV Keybindings @node MSGV Keybindings
@section Keybindings @section Keybindings
You can find most things you can do with this message in the @emph{Mu4e} menu, You can find most things you can do with this message in the @emph{Mu4e}
or by using the keyboard; the default bindings are: menu, or by using the keyboard; the default bindings are:
@verbatim @verbatim
key description key description
@ -3742,11 +3736,10 @@ answers.
@node General @node General
@section General @section General
@subsection Results from @command{mu} and @t{mu4e} differ - why? @subsection Results from @t {mu} and @t{mu4e} differ - why?
@anchor{mu-mu4e-differ} @anchor{mu-mu4e-differ} In general, the same queries for @command{mu}
In general, the same queries for @command{mu} and @t{mu4e} should and @t{mu4e} should yield the same results. If they differ, this is
yield the same results. If they differ, this is usually because one of usually because one of the following reasons:
the following reasons:
@itemize @itemize
@item different options: @item different options:
@t{mu4e} defaults to having @t{mu4e-headers-include-related}, and @t{mu4e} defaults to having @t{mu4e-headers-include-related}, and
@ -3916,15 +3909,20 @@ However, if you experience slowdowns, here are some things to consider:
@item opening messages while indexing: @item opening messages while indexing:
@t{mu4e} corresponds with the @t{mu} server synchronously; this means @t{mu4e} corresponds with the @t{mu} server synchronously; this means
that you can do only one thing at a time. The one operation that that you can do only one thing at a time. The one operation that
potentially does take a bit of time is indexing of mail, during which potentially does take a bit of time is indexing of mail. Since the 1.7.x
you have to wait for messages to open. For some strategies to reduce series you don't have to wait for the indexing to complete, but it can
that time, see the next question. be still be a bit slower because @t{mu} is very busy at that time.
For some strategies to reduce that time, see the next question.
@item getting contact information can take some time: @item getting contact information can take some time:
especially when opening @t{mu4e} the first time and you have a especially when opening @t{mu4e} the first time and you have a
@emph{lot} of contacts, it can take a few seconds to process those. @emph{lot} of contacts, it can take a few seconds to process those. Note
Note that @t{mu4e} 1.3 and higher only get @emph{changed} contacts in that @t{mu4e} 1.3 and higher only get @emph{changed} contacts in
subsequent updates (after and indexing operation), so this should be subsequent updates (after and indexing operation), so this should be
less of a concern. less of a concern. And you can tweak what contacts you get using
@var{mu4e-compose-complete-only-personal},
@var{mu4e-compose-complete-only-after} and
@var{mu4e-compose-complete-max}.
@item decryption / sign verification: @item decryption / sign verification:
encrypted / signed messages sometimes require network access, and this encrypted / signed messages sometimes require network access, and this
may take a while; certainly if the needed servers cannot be found. may take a while; certainly if the needed servers cannot be found.
@ -4009,9 +4007,8 @@ See @ref{(emacs) Mail Aliases}.
See @ref{Compose hooks}. See @ref{Compose hooks}.
@subsection How can I influence the way the original message looks when replying/forwarding? @subsection How can I influence the way the original message looks when replying/forwarding?
Since @code{mu4e-compose-mode} derives from @code{message-mode}, you Since @code{mu4e-compose-mode} derives from @code{message-mode}, you can
can re-use many of its facilities. @inforef{Insertion re-use many of its facilities. @inforef{Insertion Variables,,message}.
Variables,,message}.
@subsection How can I easily include attachments in the messages I write? @subsection How can I easily include attachments in the messages I write?
You can drag-and-drop from your desktop; alternatively, you can use You can drag-and-drop from your desktop; alternatively, you can use
@ -4048,10 +4045,15 @@ and encrypting}.
@subsection Address auto-completion does not work? @subsection Address auto-completion does not work?
If you have set @code{mu4e-compose-complete-only-personal} to non-nil, If you have set @code{mu4e-compose-complete-only-personal} to non-nil,
@t{mu4e} only completes 'personal' addresses - so you tell it about @t{mu4e} only completes 'personal' addresses - so you tell it about your
your e-mail addresses when setting up the database (@t{mu init}); e-mail addresses when setting up the database (@t{mu init});
@ref{Initializing the message store}. @ref{Initializing the message store}.
If you cannot find specific addresses you'd expect to find, inspect the
values of @var{mu4e-compose-complete-only-personal},
@var{mu4e-compose-complete-only-after} and
@var{mu4e-compose-complete-max}.
@subsection Can I use @t{BBDB} with @t{mu4e}? @subsection Can I use @t{BBDB} with @t{mu4e}?
Yes, with releases of BBDB after 3.1.2. @ref{BBDB}. Yes, with releases of BBDB after 3.1.2. @ref{BBDB}.
@ -4063,8 +4065,8 @@ Yes, with releases of BBDB after 3.1.2. @ref{BBDB}.
@subsection Sending big messages is slow and blocks emacs --- what can I do about it? @subsection Sending big messages is slow and blocks emacs --- what can I do about it?
For this, there's @url{https://github.com/jwiegley/emacs-async} (also For this, there's @url{https://github.com/jwiegley/emacs-async} (also
available from the Emacs package repository); add the following available from the Emacs package repository); add the following snippet
snippet to your configuration: to your configuration:
@lisp @lisp
(require 'smtpmail-async) (require 'smtpmail-async)
(setq (setq
@ -4074,9 +4076,9 @@ snippet to your configuration:
With this, messages are sent using a background Emacs instance. With this, messages are sent using a background Emacs instance.
A word of warning though, this tends to not be as reliable as sending A word of warning though, this tends to not be as reliable as sending
the message in the normal, synchronous fashion, and people have the message in the normal, synchronous fashion, and people have reported
reported silent failures, where mail sending fails for some reason silent failures, where mail sending fails for some reason without any
without any indication of that. indication of that.
You can check the progress of the background by checking the You can check the progress of the background by checking the
@t{*Messages*}-buffer, which should show something like: @t{*Messages*}-buffer, which should show something like:
@ -4116,11 +4118,11 @@ setting
@noindent @noindent
in your Emacs init file (@file{~/.emacs} or @file{~/.emacs.d/init.el}). in your Emacs init file (@file{~/.emacs} or @file{~/.emacs.d/init.el}).
The transformation of your message into the proper format is The transformation of your message into the proper format is done at the
done at the time of sending. For this to happen properly, you should time of sending. For this to happen properly, you should write each
write each paragraph of your message of as a long line (i.e. without paragraph of your message of as a long line (i.e. without carriage
carriage return). If you introduce unwanted newlines in your paragraph, return). If you introduce unwanted newlines in your paragraph, use
use @kbd{M-q} to reformat it as a single line. @kbd{M-q} to reformat it as a single line.
If you want to send the message with paragraphs on single lines but If you want to send the message with paragraphs on single lines but
without @t{format=flowed} (because, say, the receiver does not without @t{format=flowed} (because, say, the receiver does not
@ -4145,18 +4147,18 @@ User Marcin Borkowski has a solution:
@subsection How can I avoid Outlook display issues? @subsection How can I avoid Outlook display issues?
Limited testing shows that certain Outlook clients do not work well Limited testing shows that certain Outlook clients do not work well with
with inline replies, and the entire message including-and-below the inline replies, and the entire message including-and-below the first
first quoted section is collapsed. This means recipients may not even quoted section is collapsed. This means recipients may not even notice
notice important inline text, especially if there is some top-posted important inline text, especially if there is some top-posted content.
content. This has been observed on OS X, Windows, and Web-based This has been observed on OS X, Windows, and Web-based Outlook clients
Outlook clients accessing Office 365. accessing Office 365.
It appears the bug is triggered by the standard reply regex "On ... It appears the bug is triggered by the standard reply regex "On ...
wrote:". Changing "On", or removing the trailing ":" appears to fix wrote:". Changing "On", or removing the trailing ":" appears to fix the
the bug (in limited testing). Therefore, a simple work-around is to bug (in limited testing). Therefore, a simple work-around is to set
set `message-citation-line-format` to something slightly non-standard, `message-citation-line-format` to something slightly non-standard, such
such as: as:
@lisp @lisp
(setq message-citation-line-format "On %Y-%m-%d at %R %Z, %f wrote...") (setq message-citation-line-format "On %Y-%m-%d at %R %Z, %f wrote...")
@end lisp @end lisp
@ -4313,12 +4315,13 @@ another variable:
@node Saving outgoing messages @node Saving outgoing messages
@section Saving outgoing messages @section Saving outgoing messages
Like @code{mu4e-refile-folder}, the variable @code{mu4e-sent-folder} can also Like @code{mu4e-refile-folder}, the variable @code{mu4e-sent-folder} can
be set to a function, in order to dynamically determine the save folder. One also be set to a function, in order to dynamically determine the save
might, for example, wish to automatically put messages going to mailing lists folder. One might, for example, wish to automatically put messages going
into the trash (because you'll receive them back from the list anyway). If you to mailing lists into the trash (because you'll receive them back from
have set up the variable @code{my-mu4e-mailing-lists} as mentioned, you can the list anyway). If you have set up the variable
use the following function to determine a save folder: @code{my-mu4e-mailing-lists} as mentioned, you can use the following
function to determine a 'sent'-folder:
@lisp @lisp
(defun my-mu4e-sent-folder-function (msg) (defun my-mu4e-sent-folder-function (msg)
@ -4511,13 +4514,17 @@ log using @kbd{M-x mu4e-show-log} (@key{$}).
@node The message s-expression @node The message s-expression
@section The message s-expression @section The message s-expression
As a word of warning, the details of the s-expression are internal to
the mu4e - mu communications, and are subject to change between
versions.
A typical message s-expression looks something like the following: A typical message s-expression looks something like the following:
@lisp @lisp
(:docid 32461 (:docid 32461
:from (("Nikola Tesla" . "niko@@example.com")) :from ((:name "Nikola Tesla" :email "niko@@example.com"))
:to (("Thomas Edison" . "tom@@example.com")) :to ((:name "Thomas Edison" :email "tom@@example.com"))
:cc (("Rupert The Monkey" . "rupert@@example.com")) :cc ((:name "Rupert The Monkey" :email "rupert@@example.com"))
:subject "RE: what about the 50K?" :subject "RE: what about the 50K?"
:date (20369 17624 0) :date (20369 17624 0)
:size 4337 :size 4337
@ -4525,42 +4532,27 @@ A typical message s-expression looks something like the following:
:path "/home/tom/Maildir/INBOX/cur/133443243973_1.10027.atlas:2,S" :path "/home/tom/Maildir/INBOX/cur/133443243973_1.10027.atlas:2,S"
:maildir "/INBOX" :maildir "/INBOX"
:priority normal :priority normal
:flags (seen) :flags (seen attach)
: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 3 :name "book.pdf" :mime-type "application/pdf"
:size 192220 :attachment t))
:references ("C8384574032D81EE81AF0114E4E74@@123213.mail.example.com"
"38203498230942D81EE81AF0114E4E74@@123213.mail.example.com")
:in-reply-to "38203498230942D81EE81AF0114E4E74@@123213.mail.example.com"
:body-txt "Hi Tom,
.... ....
") ")
@end lisp @end lisp
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
from it using @t{plist-get}; for example @code{(plist-get msg :subject)} would values from it using @t{plist-get}; for example @code{(plist-get msg
get you the message subject. However, it's better to use the function :subject)} would get you the message subject. However, it's better to
@code{mu4e-message-field} to shield you from some of the implementation use the function @code{mu4e-message-field} to shield you from some of
details that are subject to change; and see the other convenience functions in the implementation details that are subject to change; and see the other
@file{mu4e-message.el}. convenience functions in @file{mu4e-message.el}.
Some notes on the format: Some notes on the format:
@itemize @itemize
@item The address fields are @emph{lists} of pairs @code{(name . email)}, @item The address fields are @emph{lists} of @t{plists} of the form @code{(:name <name> :email <email>)},
where @t{name} can be @t{nil}. where @t{name} can be @t{nil}.
@item The date is in format Emacs uses (for example in @item The date is in format Emacs uses (for example in
@code{current-time}).@footnote{Emacs 32-bit integers have only 29 bits @code{current-time}).@footnote{Emacs 32-bit integers have only 29 bits
available for the actual number; the other bits are use by available for the actual number; the other bits are use by Emacs for
Emacs for internal purposes. Therefore, we need to split internal purposes. Therefore, we need to split @t{time_t} in two
@t{time_t} in two numbers.} numbers.}
@item Attachments are a list of elements with fields @t{:index} (the number of
the MIME-part), @t{:name} (the file name, if any), @t{:mime-type} (the
MIME-type, if any) and @t{:size} (the size in bytes, if any).
@item Messages in the @ref{Headers view} come from the database and do not have
@t{:attachments}. @t{:body-txt} or @t{:body-html} fields. Message in the
@ref{Message view} use the actual message file, and do include these fields.
@end itemize @end itemize
@subsection Example: ping-pong @subsection Example: ping-pong
@ -4573,8 +4565,8 @@ to provide this information (this is implemented in
@file{mu-cmd-server.c}). @file{mu-cmd-server.c}).
We start this sequence when @t{mu4e} is invoked (when the program is We start this sequence when @t{mu4e} is invoked (when the program is
started). It calls @t{mu4e-server-ping}, and registers a (lambda) function for started). It calls @t{mu4e-server-ping}, and registers a (lambda)
@t{mu4e-server-pong-func}, to handle the response. function for @t{mu4e-server-pong-func}, to handle the response.
@verbatim @verbatim
-> (ping) -> (ping)
@ -4589,8 +4581,9 @@ they differ.
@node Debugging @node Debugging
@appendix Debugging @appendix Debugging
As explained in @ref{How it works}, @t{mu4e} communicates with its backend As explained in @ref{How it works}, @t{mu4e} communicates with its
(@t{mu server}) by sending commands and receiving responses (s-expressions). backend (@t{mu server}) by sending commands and receiving responses
(s-expressions).
For debugging purposes, it can be very useful to see this data. For For debugging purposes, it can be very useful to see this data. For
this reason, @t{mu4e} can log all these messages. Note that the this reason, @t{mu4e} can log all these messages. Note that the