mu4e: update documentation

2 files changed, 298 insertions, 280 deletions

diff --git a/mu4e/mu4e-vars.el b/mu4e/mu4e-vars.el
index 5c98f4e..f388e63 100644
--- a/mu4e/mu4e-vars.el
+++ b/mu4e/mu4e-vars.el
@@ -190,8 +190,6 @@ If the string exceeds this limit, it will be truncated to fit."
   "Create a mu4e proplist with the following elements:
 - `name': the user-visible name of the bookmark
 - `key': a single key to search for this bookmark
-- `show-unread' whether to show an indicator for read/unread messages. Specifying
-this for too many bookmarks may incur slowdowns in  showing the mu4e main page.
 - `query': the query for this bookmark. Either a literal string or a function
    that evaluates to a string."
   `(:name ,name :query ,query :key ,key))
@@ -215,15 +213,15 @@ are plists" "1.3.7")
   "List of pre-defined queries that are shown on the main screen.
 
 Each of the list elements is a plist with at least:
-:name  - the name of the query
-:query - the query expression or function
-:key   - the shortcut key.
+`:name'  - the name of the query
+`:query' - the query expression or function
+`:key'   - the shortcut key.
 
 Note that the :query parameter can be a function/lambda.
 
 Optionally, you can add the following:
-:hide  - if t, bookmark is hdden from the main-view and speedbar.
-:hide-unread - do not show the counts of unread/total number
+`:hide'  - if t, bookmark is hdden from the main-view and speedbar.
+`:hide-unread' - do not show the counts of unread/total number
  of matches for the query in the main-view. This can be useful
 if a bookmark uses  a very slow query. :hide-unread
 is implied from :hide. Furthermore, it is implied from the query
diff --git a/mu4e/mu4e.texi b/mu4e/mu4e.texi
index 2aed71b..9fe7b55 100644
--- a/mu4e/mu4e.texi
+++ b/mu4e/mu4e.texi
@@ -91,7 +91,7 @@ section with answers to frequenly asked questions, @ref{FAQ}.
 * Headers view:: Lists of message headers
 * Message view:: Viewing specific messages
 * Editor view:: Creating / editing messages
-* Searching:: Some more background on searching/queries
+* Searching:: Some more background on searching/queries`
 * Marking:: Marking messages and performing actions
 * Contexts:: Defining contexts and switching between them
 * Dynamic folders:: Folders that change based on circumstances
@@ -129,7 +129,7 @@ professionally and privately. Having an efficient e-mail client is
 essential. Since none of the existing ones worked the way I wanted, I
 thought about creating my own.
 
-@command{emacs} is an integral part of my workflow, so it made a lot of
+Emacs is an integral part of my workflow, so it made a lot of
 sense to use it for e-mail as well. And as I had already written an
 e-mail search engine (@t{mu}), it seemed only logical to use that as a
 basis.
@@ -166,7 +166,7 @@ messages end up in a maildir, @t{mu4e} and @t{mu} are happy to deal with
 them.
 @item @t{mu4e} also does @emph{not} implement sending of messages; instead, it
 depends on @t{smtpmail} (@inforef{Top,,smtpmail}), which is part of
-@command{emacs}. In addition, @t{mu4e} piggybacks on Gnus' message editor;
+Emacs. In addition, @t{mu4e} piggybacks on Gnus' message editor;
 @inforef{Top,,message}.
 @end itemize
 
@@ -232,7 +232,7 @@ After these steps, @t{mu4e} should be ready to go!
 
 @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
-FreeBSD, and even on MS-Windows (with Cygwin). @command{emacs} 24 or
+FreeBSD, and even on MS-Windows (with Cygwin). Emacs 24 or
 higher is required, as well as
 Xapian@footnote{@url{https://xapian.org/}} and
 GMime@footnote{@url{http://spruce.sourceforge.net/gmime/}}.
@@ -326,20 +326,20 @@ different, and require you to have autotools (@t{autoconf},
 $ git clone git://github.com/djcb/mu.git
 
 $ cd mu
-$ ./autogen.sh && ./configure && make
+$ ./autogen.sh && make
 # On the BSDs: use gmake instead of make
 $ sudo make install
 @end example
 
 (Xapian, GMime and their dependencies must be installed).
 
-After this, @t{mu} and @t{mu4e} should be installed @footnote{there's a hard
-dependency between versions of @t{mu4e} and @t{mu} --- you cannot combine
-different versions} on your system, and be available from the command line
-in @command{emacs}.
+After this, @t{mu} and @t{mu4e} should be installed @footnote{there's
+a hard dependency between versions of @t{mu4e} and @t{mu} --- you
+cannot combine different versions} on your system, and be available
+from the command line and in  Emacs.
 
-You may need to restart @command{emacs}, so it can find @t{mu4e} in its
-@code{load-path}. If, even after restarting, @command{emacs} cannot find
+You may need to restart Emacs, so it can find @t{mu4e} in its
+@code{load-path}. If, even after restarting, Emacs cannot find
 @t{mu4e}, you may need to add it to your @code{load-path} explicitly; check
 where @t{mu4e} is installed, and add something like the following to your
 configuration before trying again:
@@ -350,7 +350,7 @@ configuration before trying again:
 
 @subsection mu4e and emacs customization
 
-There is some support for using the @command{emacs} customization system in
+There is some support for using the Emacs customization system in
 @t{mu4e}, but for now, we recommend setting the values manually. Please refer
 to @ref{Example configs} for a couple of examples of this; here we go
 through things step-by-step.
@@ -382,7 +382,7 @@ googling should be able to provide you with the details.
 @node Initializing the message store
 @section Initializing the message store
 
-The first time your run @t{mu}, you need to initialize its store
+The first time you run @t{mu}, you need to initialize its store
 (database). The default location for that is @t{~/.cache/mu/xapian},
 but you can change this using the @t{--muhome} option, and remember to
 pass that to the other commands as well.
@@ -404,7 +404,7 @@ them as yours:
 indexing messages. If you want to change them, you need to @t{init}
 once again.
 
-If you want to see the current values, you can use @t{mu info}.
+If you want to see the current values, you can use @command{mu info}.
 
 @node Indexing your messages
 @section Indexing your messages
@@ -446,7 +446,7 @@ is to do some basic configuration for @t{mu4e}.
 @node Basic configuration
 @section Basic configuration
 
-Before we can start using @t{mu4e}, we need to tell @command{emacs} to load
+Before we can start using @t{mu4e}, we need to tell Emacs to load
 it. So, add to your @file{~/.emacs} (or its moral equivalent, such as
 @file{~/.emacs.d/init.el}) something like:
 
@@ -454,7 +454,7 @@ it. So, add to your @file{~/.emacs} (or its moral equivalent, such as
 (require 'mu4e)
 @end lisp
 
-If @command{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
 of it. If not, you can add it:
 
@@ -485,14 +485,15 @@ situation. See @ref{Dynamic folders} for details.}:
 @end lisp
 
 Note, the folder names are all relative to the root-maildir (see the
-output of @t{mu info}). If you use @t{mu4e-context}, see @ref{Contexts
-and special folders} for what that means for these special folders.
+output of @command{mu info}). If you use @t{mu4e-context}, see
+@ref{Contexts and special folders} for what that means for these
+special folders.
 
 @node Retrieval and indexing
 @section Retrieval and indexing with mu4e
 
 As we have seen, we can do all of the mail retrieval @emph{outside} of
-@command{emacs}/@t{mu4e}. However, you can also do it from within
+Emacs/@t{mu4e}. However, you can also do it from within
 @t{mu4e}.
 
 @subsection Basics
@@ -763,7 +764,19 @@ Next to each bookmark there is the number of (unread/all) messages
 that match.
 
 Bookmarks are stored in the variable @code{mu4e-bookmarks}; you can add your
-own and/or replace the default ones; @xref{Bookmarks}.
+own and/or replace the default ones; @xref{Bookmarks}. For instance:
+@lisp
+(add-to-list 'mu4e-bookmarks
+  ;; add bookmark for recent messages on the Mu mailing list.
+  '( :name "Mu7Days"
+     :key  ?m
+     :query "list:mu-discuss.googlegroups.com AND date:7d..now"))
+@end lisp
+
+There are optional keys @t{:hide} to hide the bookmark from the main
+memu, but still have it available (using @key{b})) and
+@t{:hide-unread} to avoid generating the unread-number; that can be
+useful if you have bookmarks for slow queries.
 
 @node Miscellaneous
 @section Miscellaneous
@@ -888,7 +901,7 @@ headers-view.
 @section Keybindings
 
 Using the below key bindings, you can do various things with these messages;
-these actions are also listed in the @t{Headers} menu in the @command{emacs}
+these actions are also listed in the @t{Headers} menu in the Emacs
 menu bar.
 
 @verbatim
@@ -1319,10 +1332,10 @@ extract (for example, @kbd{1 3-6 8}). The range "@samp{a}" is a shortcut for
 @section Viewing images inline
 
 It is possible to show images inline in the message view buffer if you run
-@command{emacs} in GUI-mode. You can enable this by setting the variable
-@code{mu4e-view-show-images} to @t{t}. Since @command{emacs} does not always
+Emacs in GUI-mode. You can enable this by setting the variable
+@code{mu4e-view-show-images} to @t{t}. Since Emacs does not always
 handle images correctly, this is not enabled by default. If you are using
-@command{emacs} 24 with
+Emacs 24 with
 @emph{ImageMagick}@footnote{@url{http://www.imagemagick.org/}} support, make
 sure you call @code{imagemagick-register-types} in your configuration, so it
 is used for images.
@@ -1458,7 +1471,7 @@ Currently, only PGP/MIME is supported; PGP-inline and S/MIME are not.
 
 For all of this to work, @command{gpg-agent} must be running, and it
 must set the environment variable @t{GPG_AGENT_INFO}. You can check from
-@command{emacs} with @key{M-x getenv GPG_AGENT_INFO}.
+Emacs with @key{M-x getenv GPG_AGENT_INFO}.
 
 In many mainstream Linux/Unix desktop environments, everything works
 out-of-the-box, but if your environment does not automatically start
@@ -1554,8 +1567,8 @@ Gimp}
 see the results. Suppose you receive a patch file, and would like to get an
 overview of the changes, using the @t{diffstat} program. You can use something
 like: @kbd{A | 1 RET diffstat -b RET}.
-@item @command{emacs} (@key{e}): open the attachment in your running @command{emacs}. For
-example, if you receive some text file you'd like to open in @command{emacs}:
+@item Emacs (@key{e}): open the attachment in your running Emacs. For
+example, if you receive some text file you'd like to open in Emacs:
 @kbd{A e 1 RET}.
 @end itemize
 
@@ -1623,7 +1636,7 @@ C-S-u        update mail & reindex
 @node Address autocompletion
 @section Address autocompletion
 
-@t{mu4e} supports@footnote{@command{emacs} 23.2 or higher is required}
+@t{mu4e} supports@footnote{GNU Emacs 24.4 or higher is required}
 autocompleting addresses when composing e-mail messages. @t{mu4e} uses the
 e-mail addresses from the messages you sent or received as the source for
 this. Address auto-completion is enabled by default; if you want to disable it
@@ -1814,7 +1827,7 @@ then still include the signature manually, using the function
 @section Other settings
 
 @itemize
-@item If you want use @t{mu4e} as @command{emacs}' default program for sending mail,
+@item If you want use @t{mu4e} as Emacs' default program for sending mail,
 see @ref{Emacs default}.
 @item Normally, @t{mu4e} @emph{buries} the message buffer after sending; if you want
 to kill the buffer instead, add something like the following to your
@@ -2254,7 +2267,7 @@ action       | a           | apply some action
 After marking a message, the left-most columns in the headers view indicate
 the kind of mark. This is informative, but if you mark many (say, thousands)
 messages, this slows things down significantly@footnote{this uses an
-@command{emacs} feature called @emph{overlays}, which are slow when used a lot
+Emacs feature called @emph{overlays}, which are slow when used a lot
 in a buffer}. For this reason, you can disable this by setting
 @code{mu4e-headers-show-target} to @code{nil}.
 
@@ -2742,10 +2755,10 @@ In @ref{Folders}, we explained how you can set up @t{mu4e}'s special
 folders:
 @lisp
 (setq
-  mu4e-sent-folder   "/sent"	   ;; sent messages
-  mu4e-drafts-folder "/drafts"	   ;; unfinished messages
-  mu4e-trash-folder  "/trash"	   ;; trashed messages
-  mu4e-refile-folder "/archive")   ;; saved messages01
+  mu4e-sent-folder   "/sent"       ;; sent messages
+  mu4e-drafts-folder "/drafts"     ;; unfinished messages
+  mu4e-trash-folder  "/trash"      ;; trashed messages
+  mu4e-refile-folder "/archive")   ;; saved messages
 @end lisp
 
 In some cases, having such static folders may not suffice --- perhaps you want
@@ -3210,7 +3223,7 @@ one of the user's e-mail addresses (as per @code{mu4e-user-mail-address-list}).
 see @code{mu4e-toggle-logging}.
 @item @code{mu4e-message}, @code{mu4e-warning}, @code{mu4e-error} are the
 @t{mu4e} equivalents of the normal elisp @code{message},
-@code{user-error}@footnote{@code{user-error} only appears in @command{emacs}
+@code{user-error}@footnote{@code{user-error} only appears in Emacs
 24.2 and later; in older versions it falls back to @code{error}} and
 @code{error} functions.
 @end itemize
@@ -3229,7 +3242,6 @@ with other tools.
 * BBDB::Hooking up with the Insidious Big Brother Database
 * Sauron::Getting new mail notifications with Sauron
 * Speedbar::A special frame with your folders
-* Mu-cite:: Fancy citation engine
 * Dired:: Attaching files using @t{dired}
 * Hydra:: Custom shortcut menus
 @end menu
@@ -3237,7 +3249,7 @@ with other tools.
 @node Emacs default
 @section Emacs default
 
-@command{emacs} allows you to select an e-mail program as the default
+Emacs allows you to select an e-mail program as the default
 program it uses when you press @key{C-x m} (@code{compose-mail}), call
 @code{report-emacs-bug} and so on. If you want to use @t{mu4e} for this,
 you can do so by adding the following to your configuration:
@@ -3356,7 +3368,7 @@ After this, you should be able to:
 @node Sauron
 @section Sauron
 
-The @command{emacs} package @t{sauron}@footnote{Sauron can be found at
+The Emacs package @t{sauron}@footnote{Sauron can be found at
 @url{https://github.com/djcb/sauron}, or in the Marmalade package repository
 at @url{https://marmalade-repo.org/}} (by the same author) can be used
 to get notifications about new mails. If you run something like the below
@@ -3412,8 +3424,8 @@ running outside its session.
 @node Speedbar
 @section Speedbar
 
-@code{speedbar} is an @command{emacs}-extension that shows navigational information for
-an @command{emacs} buffer in a separate frame. Using @code{mu4e-speedbar}, @t{mu4e}
+@code{speedbar} is an Emacs-extension that shows navigational information for
+an Emacs buffer in a separate frame. Using @code{mu4e-speedbar}, @t{mu4e}
 lists your bookmarks and maildir folders and allows for one-click access to
 them.
 
@@ -3427,25 +3439,6 @@ list, such as auto-completion when jumping to a maildir.
 
 @code{mu4e-speedbar} was contributed by @emph{Antono Vasiljev}.
 
-@node Mu-cite
-@section Mu-cite
-
-@t{mu-cite}@footnote{Note, despite its name, @t{mu-cite} is a project
-unconnected to @t{mu}/@t{mu4e}} is a package to control the way message
-citations look like (i.e., the message you responded to when you reply to them
-or forward them), with its latest version available at
-@url{https://www.jpl.org/elips/mu/}.
-
-After installing @t{mu-cite}, you can use something like the following to make
-it work with @t{mu4e}:
-
-@lisp
-(require 'mu-cite)
-(setq mu4e-compose-cite-function 'mu-cite-original)
-(setq mu-cite-top-format '("On " date ", " from " wrote:\n\n"))
-(setq mu-cite-prefix-format '(" > "))
-@end lisp
-
 @node Dired
 @section Dired
 
@@ -3797,7 +3790,7 @@ Next step: let's make a @t{mu4e} configuration for this:
 @end lisp
 
 And that's it --- put the above in your @file{~/.emacs}, change @t{USERNAME}
-etc. to your own, and restart @command{emacs}, and run @kbd{M-x mu4e}.
+etc. to your own, and restart Emacs, and run @kbd{M-x mu4e}.
 
 @node CONF Other settings
 @section Other settings
@@ -3833,100 +3826,117 @@ answers.
 @node General
 @section General
 
-@enumerate
-@item @emph{Does @t{mu4e} provide context-sensitive help information?} Yes --- pressing @key{H}
-should take you to the right section in this manual.
-@item @emph{How can I quickly delete/move/trash a lot of messages?} You can
-select ('mark' in @command{emacs}-speak) the messages like you would select
-text in a buffer; the actions you then take (e.g., @key{DEL} for delete,
-@key{m} for move and @key{t} for trash) apply to all selected messages. You
-can also use functions like @code{mu4e-headers-mark-thread} (@key{T}),
-@code{mu4e-headers-mark-subthread} (@key{t}) to mark whole threads at the same
-time, and @code{mu4e-headers-mark-pattern} (@key{%}) to mark all messages
-matching a certain regular expression.
-@item @emph{@t{mu4e} seems to return a subset of all matches --- how can I
-get them all?} For speed reasons, @t{mu4e} returns only up to the value
-of the variable @code{mu4e-search-result-limit} (default: 500)
-matches. To show @emph{all}, use @kbd{M-x
-mu4e-headers-toggle-full-search} (@key{Q}), or customize the variable
-@code{mu4e-headers-full-search}. This applies to all search commands.
-@item @emph{Can I automatically apply the marks on messages when
-leaving the headers buffer?} Yes you can --- see the documentation for the
-variable @t{mu4e-headers-leave-behavior}.
-@item @emph{How can I set @t{mu4e} as the default e-mail client in @command{emacs}?}
+@subsection Results from @command{mu} and @t{mu4e} differ - why?
+In general, the same queries for @command{mu} and @t{mu4e} should
+yield the same results. If they differ, this is usually because one
+of the following reasons:
+@itemize
+@item different default options:
+mu4e defaults to having @t{mu4e-headers-include-related} and
+@t{mu4e-headers-skip-duplicates} enabled and
+@t{mu4e-headers-results-limit} set to 500. However, the command-line
+@command{mu find}'s corresponding @t{--include-related} and
+@t{--skip-dups} are false, and there's no limit (@t{--maxnum}).
+@item reverse sorting:
+The results amy be different when only one @t{mu4e} and @command{mu
+find} do not both sort their results in the same direction.
+@item shell quoting issues:
+Depending on the shell, various shell metacharacters in search query
+(such as @t{*}) may be expanded by the shell before @command{mu} ever
+sees them, and the query may not be what you think it is. Quoting is
+necessary.
+@end itemize
+
+@subsection How can I quickly delete/move/trash a lot of messages?
+You can select ('mark' in Emacs-speak) the messages like you
+would select text in a buffer; the actions you then take (e.g.,
+@key{DEL} for delete, @key{m} for move and @key{t} for trash) apply to
+all selected messages. You can also use functions like
+@code{mu4e-headers-mark-thread} (@key{T}),
+@code{mu4e-headers-mark-subthread} (@key{t}) to mark whole threads at
+the same time, and @code{mu4e-headers-mark-pattern} (@key{%}) to mark
+all messages matching a certain regular expression.
+
+@subsection Can I automatically apply the marks on messages when leaving the headers buffer?
+Yes you can --- see the documentation for the variable
+@t{mu4e-headers-leave-behavior}.
+
+@subsection How can I set @t{mu4e} as the default e-mail client in Emacs?
 See @ref{Emacs default}.
-@item @emph{Can @t{mu4e} use some fancy Unicode characters instead of these
-boring plain-ASCII ones?} Glad you asked! Yes, if you set
-@code{mu4e-use-fancy-chars} to @t{t}, @t{mu4e} uses such fancy
-characters in a number of places. Since not all fonts include all
-characters, you may want to install the @t{unifont} and/or @t{symbola}
-fonts on your system.
-@item @emph{Can I start @t{mu4e} in the background?} Yes --- if you provide a
-prefix-argument (@key{C-u}), @t{mu4e} starts, but does not show the
-main-window.
-@item @emph{Does @t{mu4e} support searching for CJK (Chinese-Japanese-Korean) characters?}
+
+@subsection Can @t{mu4e} use some fancy Unicode instead of these boring plain-ASCII ones?
+Glad you asked! Yes, if you set @code{mu4e-use-fancy-chars} to @t{t},
+@t{mu4e} uses such fancy characters in a number of places. Since not
+all fonts include all characters, you may want to install the
+@t{unifont} and/or @t{symbola} fonts on your system.
+
+@subsection Can I start @t{mu4e} in the background?
+Yes --- if you provide a prefix-argument (@key{C-u}), @t{mu4e} starts,
+but does not show the main-window.
+
+@subsection Does @t{mu4e} support searching for CJK (Chinese-Japanese-Korean) characters?
 Yes, if you have @t{Xapian} 1.2.8 or newer, and set the environment
 variable @t{XAPIAN_CJK_NGRAM} to non-empty before indexing, both when
 using @t{mu} from the command-line and from @t{mu4e}.
-@item @emph{How can I customize the function to select a folder?}
-The @t{mu4e-completing-read-function} variable can be customized to select a
-folder in any way. The variable can be set to a function that receives
-five arguments, following @t{completing-read}. The default value is
-@code{ido-completing-read}; to use emacs's default behavior, set the
-variable to @code{completing-read}. Helm users can use the same value,
-and by enabling @code{helm-mode} use helm-style completion.
-@item @emph{I have a lot of Maildir folders, so regenerating them each time makes
-things slow. What can I do?}
-Set @code{mu4e-cache-maildir-list} to @code{t} (but make sure to read
+
+@subsection How can I customize the function to select a folder?
+The @t{mu4e-completing-read-function} variable can be customized to
+select a folder in any way. The variable can be set to a function that
+receives five arguments, following @t{completing-read}. The default
+value is @code{ido-completing-read}; to use emacs's default behavior,
+set the variable to @code{completing-read}. Helm users can use the
+same value, and by enabling @code{helm-mode} use helm-style
+completion.
+
+@subsection With a lot of Maildir folders, jumping to them can get slow. What can I do?
+Set @code{mu4e-cache-maildir-list} to @code{t} (make sure to read
 its docstring).
-@item @emph{How can I hide certain message from the search results?}
+
+@subsection How can I hide messages from the search results?
 See the variable @code{mu4e-headers-hide-predicate}.
-@item @emph{I'm getting an error 'Variable binding depth exceeds max-specpdl-size'
-when using mu4e -- what can I do about it?}  The error occurs because
-@t{mu4e} is binding more variables than @t{emacs} allows for, by
-default. You can avoid this by setting a higher value, e.g. by adding the
-following to your configuration:
+
+@subsection I'm getting an error 'Variable binding depth exceeds max-specpdl-size' when using mu4e -- what can I do about it?
+The error occurs because @t{mu4e} is binding more variables than
+@t{emacs} allows for, by default. You can avoid this by setting a
+higher value, e.g. by adding the following to your configuration:
 @lisp
 (setq max-specpdl-size 5000)
 @end lisp
-@end enumerate
 
 @node Retrieving mail
 @section Retrieving mail
 
-@enumerate
-@item @emph{How can I get notifications when receiving mail?} There is
-@code{mu4e-index-updated-hook}, which gets triggered when the indexing
-process triggered sees an update (not just new mail though). To use this
-hook, put something like the following in your setup (assuming you have
-@t{aplay} and some soundfile, change as needed):
+@subsection How can I get notifications when receiving mail?
+There is @code{mu4e-index-updated-hook}, which gets triggered when the
+indexing process triggered sees an update (not just new mail though).
+To use this hook, put something like the following in your setup
+(assuming you have @t{aplay} and some soundfile, change as needed):
 @lisp
 (add-hook 'mu4e-index-updated-hook
   (defun new-mail-sound ()
     (shell-command "aplay ~/Sounds/boing.wav&")))
 @end lisp
-@item @emph{It seems my headers-buffer is automatically updated when new
-  messages are found during the indexing process --- can I disable this
-  somehow?} Yes --- set @code{mu4e-headers-auto-update} to @code{nil}.
-@item @emph{I don't use @t{offlineimap}, @t{fetchmail} etc., I get my mail
-through my own mailserver. What should I use for
-@code{mu4e-get-mail-command}}? Use the literal string @t{"true"} (or
-don't do anything, it's the default) which then uses @t{/bin/true} (a
-command that does nothing and always succeeds). This makes getting mail
-a no-op, but the messages are still re-indexed.
-@item @emph{How can I re-index my messages without getting new mail?}
+
+@subsection Getting mail through a local mailserver. What should I use for @code{mu4e-get-mail-command}?
+Use the literal string @t{"true"} (or don't do anything, it's the
+default) which then uses @t{/bin/true} (a command that does nothing
+and always succeeds). This makes getting mail a no-op, but the
+messages are still re-indexed.
+
+@subsection How can I re-index my messages without getting new mail?
 Use @kbd{M-x mu4e-update-index}
-@item @emph{When I try to run @t{mu index} while @t{mu4e} is running I get
-errors like:}
+
+@subsection When I try to run @t{mu index} while @t{mu4e} is running I get errors
+For instance:
 @verbatim
 mu: mu_store_new_writable: xapian error
   'Unable to get write lock on ~/.cache/mu/xapian: already locked
 @end verbatim
-@emph{What to do about this?}  You get this error because the underlying
-Xapian database is locked by some other process; it can be opened only once in
-read-write mode. There is not much @t{mu4e} can do about this, but if is
-another @command{mu} instance that is holding the lock, you can ask it to
-(gracefully) terminate:
+What to do about this? You get this error because the underlying
+Xapian database is locked by some other process; it can be opened only
+once in read-write mode. There is not much @t{mu4e} can do about this,
+but if is another @command{mu} instance that is holding the lock, you
+can ask it to (gracefully) terminate:
 @verbatim
    pkill -2 -u $UID mu # send SIGINT
    sleep 1
@@ -3934,66 +3944,67 @@ another @command{mu} instance that is holding the lock, you can ask it to
 @end verbatim
 @t{mu4e} automatically restarts @t{mu} when it needs it. In practice, this
 seems to work quite well.
-@item @emph{I don't like the @t{Indexing...} messages that the indexing process
-gives me. Can I turn them off?}. Yes: set the variable
-@code{mu4e-hide-index-messages} to non-@t{nil}.
-@item @emph{Some IMAP-synchronization programs such as @t{mbsync} (but not
-@t{offlineimap}) don't like it when message files do not change their names
-when they are moved to different folders. Can @t{mu4e} somehow accommodate
-this?} Yes --- you can set the variable @code{mu4e-change-filenames-when-moving}
-to non-@t{nil}.
-@item @emph{@command{offlineimap} uses IMAP's UTF-7 for encoding
-non-ascii folder names, while @t{mu} expects UTF-8 (so, e.g. @t{/まりも
-えお}@footnote{some Japanese characters} becomes
-@t{/&MH4wijCCMEgwSg-}). How can I make @t{mu4e} display such folders
-correctly?} This is best solved by telling @command{offlineimap} to use
-UTF-8 instead --- see
+
+@subsection How can I disable the @t{Indexing...} messages?
+Set the variable @code{mu4e-hide-index-messages} to non-@t{nil}.
+
+@subsection IMAP-synchronization and file-name changes
+Some IMAP-synchronization programs such as @t{mbsync} (but not
+@t{offlineimap}) don't like it when message files do not change their
+names when they are moved to different folders. @t{mu4e} can attempt
+to help with this - you can set the variable
+@code{mu4e-change-filenames-when-moving} to non-@t{nil}.
+
+@subsection @command{offlineimap} and UTF-7
+@command{offlineimap} uses IMAP's UTF-7 for encoding non-ascii folder
+names, while @command{mu} expects UTF-8 (so, e.g. @t{/まりもえ
+お}@footnote{some Japanese characters} becomes @t{/&MH4wijCCMEgwSg-}).
+
+This is best solved by telling @command{offlineimap} to use UTF-8
+instead --- see
 @url{https://github.com/djcb/mu/issues/68#issuecomment-8598652}.
-@item @emph{@t{mbsync} or @t{offlineimap} do not sync properly with my web-mail
-provider (such as gmail) -- what can I do about it?} Unfortunately,
-@t{mbsync} and/or @t{offlineimap} do not always agree with @t{mu} about
-the meaning of various Maildir-flags. If you encounter unexpected
-behavior, it is recommended you check before and after a sync-operation.
-
-If the problem only shows up @emph{after} sync'ing, the problem is with
-the sync-program, and it's most productive to complain there. Otherwise,
-there have been quite a few related queries on the mailing-list;
-worthwhile to check out.
-@end enumerate
+
+@subsection @command{mbsync} or @command{offlineimap} do not sync properly
+Unfortunately, @command{mbsync} and/or @command{offlineimap} do not
+always agree with @t{mu} about the meaning of various Maildir-flags.
+If you encounter unexpected behavior, it is recommended you check
+before and after a sync-operation. If the problem only shows up
+@emph{after} sync'ing, the problem is with the sync-program, and it's
+most productive to complain there. Otherwise, there have been quite a
+few related queries on the mailing-list; worthwhile to check out.
 
 @node Reading messages
 @section Reading messages
 
-@enumerate
-@item @emph{How can I view attached images in my message view buffers?} See
+@subsection How can I view attached images in my message view buffers? See
 @ref{Viewing images inline}.
-@item @emph{How can I word-wrap long lines in when viewing a
-message?} You can toggle between wrapped and non-wrapped states using
+@subsection How can I word-wrap long lines in when viewing a message?
+You can toggle between wrapped and non-wrapped states using
 @key{w}. If you want to do this automatically, invoke @code{visual-line-mode} in
 your @code{mu4e-view-mode-hook}.
-@item @emph{How can I perform custom actions on messages and attachments?} See
-@ref{Actions}.
-@item @emph{Does @t{mu4e} support crypto (i.e., decrypting messages and
-verifying signatures)?}  Yes --- if @t{mu} was built with @t{GMime} 2.6
+@subsection How can I perform custom actions on messages and attachments?
+See @ref{Actions}.
+@subsection Does @t{mu4e} support crypto (i.e., decrypting messages and verifying signatures)?
+Yes --- if @t{mu} was built with @t{GMime} 2.6
 or later, it is possible to do both (note, only PGP/MIME is
 supported). In the @ref{Main view} the support is indicated by a big
 letter @t{C} on the right hand side of the @t{mu4e} version. See
 @ref{Decryption} and @ref{Verifying signatures}. For encryption and
 signing messages, see @ref{Writing messages}.
-@item @emph{How can I prevent @t{mu4e} from automatically marking messages as `read' when I read them?}
+@subsection How can I prevent @t{mu4e} from automatically marking messages as `read' when I read them?
 Set @code{mu4e-view-auto-mark-as-read} to @code{nil}.
-@item @emph{Does @t{mu4e} support including all related messages in a thread,
-like Gmail does?} Yes --- see @ref{Including related messages}.
-@item @emph{There seems to be a lot of duplicate messages --- how can I get rid
-of them?} See @ref{Skipping duplicates}.
-@item @emph{How can I use the @t{eww} browser to view rich-text messages?}
-With a new enough emacs, this happens automatically. See @ref{Html2text
-functions} for some details.
-@item @emph{Some messages are almost unreadable in emacs --- can I view them in
-an external web browser?} Indeed, airlines often send messages that
-heavily depend on html and are hard to digest inside emacs. Fortunately,
-there's an @emph{action} (@ref{Message view actions})
-defined for this. Simply add to your configuration:
+@subsection Does @t{mu4e} support including all related messages in a thread, like Gmail does?
+Yes --- see @ref{Including related messages}.
+@subsection There seems to be a lot of duplicate messages --- how can I get rid of them?
+See @ref{Skipping duplicates}.
+@subsection How can I use the @t{eww} browser to view rich-text messages?
+With a new enough emacs, this happens automatically. See
+@ref{Html2text functions} for some details.
+@subsection Some messages are almost unreadable in emacs --- can I view them in an external web browser?
+Indeed, airlines often send messages that heavily depend on html and
+are hard to digest inside emacs. Fortunately, there's an @emph{action}
+(@ref{Message view actions}) defined for this. Simply add to your
+configuration:
 @lisp
 (add-to-list 'mu4e-view-actions
   '("ViewInBrowser" . mu4e-action-view-in-browser) t)
@@ -4001,11 +4012,11 @@ defined for this. Simply add to your configuration:
 Now, when viewing such a difficult message, type @kbd{aV}, and the message
 opens inside a webbrowser. You can influence the browser with
 @code{browse-url-generic-program}; and see @ref{Privacy aspects}.
-@item @emph{How can I read encrypted messages that I sent?}. Since you do not own the
-recipient's key you typically cannot read those mails --- so the trick is
-to encrypt outgoing mails with your key, too. This can be automated by
-adding the following snippet to your configuration (courtesy of user
-@t{kpachnis}):
+@subsection How can I read encrypted messages that I sent?
+Since you do not own the recipient's key you typically cannot read
+those mails --- so the trick is to encrypt outgoing mails with your
+key, too. This can be automated by adding the following snippet to
+your configuration (courtesy of user @t{kpachnis}):
 @lisp
 (require 'epg-config)
 (setq mml2015-use 'epg
@@ -4013,75 +4024,78 @@ adding the following snippet to your configuration (courtesy of user
       mml2015-encrypt-to-self t
       mml2015-sign-with-sender t)
 @end lisp
-@item @emph{view-as-pdf seems to hang for some e-mails --- what can I do about that?}
-Short answer: install @t{nspluginwrapper}. Longer answer: @t{mu} comes
-with @t{msg2pdf}, which is a program used to convert the messages to
-pdf, and which depends on WebKit, which in some cases needs
-@t{nspluginwrapper} and it waits for a long time if it's not there. So,
-installing @t{nspluginwrapper} prevents that.
-@item @emph{Can I `bounce' or `resend' messages?}
-Yes --- it is possible to edit a (copy of) an existing message and then
-send it, using @code{M-x mu4e-compose-resend}. This gives you a raw copy
-of the message, including all headers, encoded parts and so on. Reason
-for this is that for resending, it is important not to change anything
-(except perhaps for the @t{To:} address when bouncing); since we cannot
-losslessly decode an existing message, you get the raw version.
-
-@end enumerate
+@subsection Can I `bounce' or `resend' messages?
+Yes --- it is possible to edit a (copy of) an existing message and
+then send it, using @code{M-x mu4e-compose-resend}. This gives you a
+raw copy of the message, including all headers, encoded parts and so
+on. Reason for this is that for resending, it is important not to
+change anything (except perhaps for the @t{To:} address when
+bouncing); since we cannot losslessly decode an existing message, you
+get the raw version.
 
 @node Writing messages
 @section Writing messages
 
-@enumerate
-@item @emph{What's the deal with replies to messages I wrote myself?} Like
-many other mail-clients, @t{mu4e} treats replies to messages you wrote
-yourself as special --- these messages keep the same @t{To:} and @t{Cc:}
-as the original message. This is to ease the common case of following up
-to a message you wrote earlier.
-@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 draft messages, sent
-messages, trashed messages, based on e.g. the @t{From:} header?} See
-@ref{Dynamic folders}.
-@item @emph{Can I define aliases for (groups of) e-mail addresses?} Sure -
-see @ref{(emacs) Mail Aliases}.
-@item @emph{How can I automatically add some header to an outgoing message?}
-Once more, see @ref{Compose hooks}.
-@item @emph{How can I influence the way the original message looks when
-replying or inline forwarding?} Since @code{mu4e-compose-mode} derives from
-@code{message-mode}, you can re-use many of its facilities.
-@inforef{Insertion Variables,,message}.
-@item @emph{How can I easily include attachments in the messages I write?}
-You can drag-and-drop from your desktop; alternatively, you can use @t{dired}
---- see @ref{Dired}.
-@item @emph{@t{mu4e} seems to remove myself from the @t{Cc:}-list; how can I
-prevent that?}  Set @code{mu4e-compose-keep-self-cc} to @t{t} in your
-configuration.
-@item @emph{How can I start a new message-thread from a reply?} Remove the @t{In-Reply-To} header,
-and @t{mu4e} automatically removes the (hidden) @t{References} header as
-well when sending it. This makes the message show up as a top-level
-message rather than as a response.
-@item @emph{How can I attach an existing message?} Use @code{mu4e-action-capture-message}
- (i.e., @kbd{a c} in the headers view) to `capture' the to-be-attached
- message, then when editing the message, use @kbd{M-x
- mu4e-compose-attach-captured-message}.
-@item @emph{How can I sign or encrypt messages?} You can do so using @command{emacs}'
-MIME-support --- check the @t{Attachments}-menu while composing a
-message. Also see @ref{Signing and encrypting}.
-@item @emph{Can I use @t{BBDB} with @t{mu4e}?} Yes, with the current
-(2015-06-23) development release of BBDB
+@subsection What's the deal with replies to messages I wrote myself?
+Like many other mail-clients, @t{mu4e} treats replies to messages you
+wrote yourself as special --- these messages keep the same @t{To:} and
+@t{Cc:} as the original message. This is to ease the common case of
+following up to a message you wrote earlier.
+
+@subsection How can I automatically set the @t{From:}-address for a reply-message?
+See @ref{Compose hooks}.
+
+@subsection How can I dynamically determine the folders for draft/sent/trashed messages?
+See @ref{Dynamic folders}.
+
+@subsection How can I define aliases for (groups of) e-mail addresses?
+See @ref{(emacs) Mail Aliases}.
+
+@subsection How can I automatically add some header to an outgoing message?
+See @ref{Compose hooks}.
+
+@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
+can re-use many of its facilities. @inforef{Insertion
+Variables,,message}.
+
+@subsection How can I easily include attachments in the messages I write?
+You can drag-and-drop from your desktop; alternatively, you can use
+@t{dired} --- see @ref{Dired}.
+
+@subsection @t{mu4e} seems to remove myself from the @t{Cc:}-list; how can Iprevent that?
+Set @code{mu4e-compose-keep-self-cc} to @t{t} in your configuration.
+
+@subsection How can I start a new message-thread from a reply?
+Remove the @t{In-Reply-To} header, and @t{mu4e} automatically removes
+the (hidden) @t{References} header as well when sending it. This makes
+the message show up as a top-level message rather than as a response.
+
+@subsection How can I attach an existing message?
+Use @code{mu4e-action-capture-message} (i.e., @kbd{a c} in the headers
+ view) to `capture' the to-be-attached message, then when editing the
+ message, use @kbd{M-x mu4e-compose-attach-captured-message}.
+
+@subsection How can I sign or encrypt messages?
+You can do so using Emacs' MIME-support --- check the
+@t{Attachments}-menu while composing a message. Also see @ref{Signing
+and encrypting}.
+
+@subsection Can I use @t{BBDB} with @t{mu4e}?
+Yes, with the current (2015-06-23) development release of BBDB
 @url{https://savannah.nongnu.org/projects/bbdb/}, or releases of BBDB
-after 3.1.2.
-@ref{BBDB}.
-@item @emph{After sending some messages, it seems the buffer for these
-messages stay around. How can I get rid of those?}
+after 3.1.2. @ref{BBDB}.
+
+@subsection How can I get rid of the message buffer after sending?
 @lisp
 (setq message-kill-buffer-on-exit t)
 @end lisp
-@item @emph{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 available from the Emacs package repository); add the following snippet
-to your configuration:
+
+@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
+available from the Emacs package repository); add the following
+snippet to your configuration:
 @lisp
 (require 'smtpmail-async)
 (setq
@@ -4091,9 +4105,9 @@ to your configuration:
 With this, messages are sent using a background Emacs instance.
 
 A word of warning though, this tends to not be as reliable as sending
-the message in the normal, synchronous fashion, and people have reported
-silent failures, where mail sending fails for some reason without any
-indication of that.
+the message in the normal, synchronous fashion, and people have
+reported silent failures, where mail sending fails for some reason
+without any indication of that.
 
 You can check the progress of the background by checking the
 @t{*Messages*}-buffer, which should show something like:
@@ -4106,24 +4120,27 @@ Sending...done
 @end verbatim
 The first and final messages are the most important, and there may be
 considerable time between them, depending on the size of the message.
-@item @emph{Is it possible to compose messages in a separate frame?}
+
+@subsection Is it possible to compose messages in a separate frame?
 Yes --- set the variable @code{mu4e-compose-in-new-frame} to @code{t}.
-@item @emph{How can I apply format=flowed to my outgoing messages, enabling
-receiving clients that support this feature to reflow my paragraphs?}
-Plain text emails with @t{Content-Type: text/plain; format=flowed} can
-be reflowed (i.e. line endings removed, paragraphs refilled) by
-receiving clients that support this standard. Clients that don't support
-this, show them as is, which means this feature is truly non-invasive.
-
-Here's an explanatory blog post which also shows why this is a desirable
-feature: @url{https://mathiasbynens.be/notes/gmail-plain-text} (if you
-don't have it, your mails mostly look quite bad especially on mobile
+
+@subsection How can I apply format=flowed to my outgoing messages?
+This enables receiving clients that support this feature to reflow
+paragraphs. Plain text emails with @t{Content-Type: text/plain;
+format=flowed} can be reflowed (i.e. line endings removed, paragraphs
+refilled) by receiving clients that support this standard. Clients
+that don't support this, show them as is, which means this feature is
+truly non-invasive.
+
+Here's an explanatory blog post which also shows why this is a
+desirable feature:
+@url{https://mathiasbynens.be/notes/gmail-plain-text} (if you don't
+have it, your mails mostly look quite bad especially on mobile
 devices) and here's the RFC with all the details:
 @url{https://www.ietf.org/rfc/rfc2646.txt}.
 
-Since version 0.9.17, @t{mu4e} send emails with @t{format=flowed} by
+Since version 0.9.17, @t{mu4e} sensd emails with @t{format=flowed} by
 setting
-
 @lisp
 (setq mu4e-compose-format-flowed t)
 @end lisp
@@ -4142,8 +4159,8 @@ understand the latter as it is the case for Google or Github), use
 @kbd{M-x use-hard-newlines} (to turn @code{use-hard-newlines} off) or
 uncheck the box @t{format=flowed} in the @t{Text} menu when composing a
 message.
-@item @emph{How can force images to be shown at the end of my messages,
-regardless of where I insert them?}
+
+@subsection How can force images to be shown at the end of my messages, regardless of where I insert them?
 User Marcin Borkowski has a solution:
 @lisp
 (defun mml-attach-file--go-to-eob (orig-fun &rest args)
@@ -4157,7 +4174,7 @@ User Marcin Borkowski has a solution:
 (advice-add 'mml-attach-file :around #'mml-attach-file--go-to-eob)
 @end lisp
 
-@item @emph{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
 with inline replies, and the entire message including-and-below the
@@ -4174,7 +4191,6 @@ such as:
 @lisp
 (setq  message-citation-line-format "On %Y-%m-%d at %R %Z, %f wrote...")
 @end lisp
-@end enumerate
 
 @node Known issues
 @section Known issues
@@ -4185,7 +4201,7 @@ won't have to search in vain for things that are not there (yet), and
 the author can use it as a todo-list.
 
 @itemize
-@item @emph{mu4e does not work well if the @command{emacs} language environment is not
+@item @emph{mu4e does not work well if the Emacs language environment is not
 UTF-8}; so, if you encounter problems with encodings, be sure to have
 @code{(set-language-environment "UTF-8")} in your @file{~/.emacs}.
 @item @emph{Thread handling is incomplete.} While threads are calculated and are
@@ -4457,11 +4473,11 @@ server.
 @item @t{mu} indexes these messages periodically, so you can quickly search for
 them. @t{mu} can run in a special @t{server}-mode, where it provides services
  to client software.
-@item @t{mu4e}, which runs inside @command{emacs} is
+@item @t{mu4e}, which runs inside Emacs is
  such a client; it communicates with @command{mu} (in its @t{server}-mode) to
  search for messages, and manipulate them.
 @item @t{mu4e} uses the facilities
- offered by @command{emacs} (the Gnus message editor and @t{smtpmail}) to send
+ offered by Emacs (the Gnus message editor and @t{smtpmail}) to send
  messages.
 @end itemize
 
@@ -4475,7 +4491,7 @@ client that is emacs-based.
 One way to implement this, would be to call the @t{mu} command-line
 tool with some parameters and then parse the output. In fact, that was
 the first approach --- @t{mu4e} would invoke e.g., @t{mu find} and
-process the output in @command{emacs}.
+process the output in Emacs.
 
 However, with this approach, we need to load the entire e-mail
 @emph{Xapian} database (in which the message is stored) for each
@@ -4490,15 +4506,15 @@ can be used manually, which is great for debugging.
 @section Reading from the server
 
 In the design, the next question was what format @t{mu} should use for its
-output for @t{mu4e} (@command{emacs}) to process. Some other programs use
+output for @t{mu4e} (Emacs) to process. Some other programs use
 @abbr{JSON} here, but it seemed easier (and possibly, more efficient) just to
-talk to @command{emacs} in its native language: @emph{s-expressions}, and
-interpret those using the @command{emacs}-function
+talk to Emacs in its native language: @emph{s-expressions}, and
+interpret those using the Emacs-function
 @code{read-from-string}. See @ref{The message s-expression} for details on the
 format.
 
 So, now let's look at how we process the data from @t{mu server} in
-@command{emacs}. We'll leave out a lot of details, @t{mu4e}-specifics, and look
+Emacs. We'll leave out a lot of details, @t{mu4e}-specifics, and look
 at a bit more generic approach.
 
 The first thing to do is to create a process (for example, with
@@ -4583,10 +4599,10 @@ Some notes on the format:
 @itemize
 @item The address fields are @emph{lists} of pairs @code{(name . email)},
 where @t{name} can be @t{nil}.
-@item The date is in format @command{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
 available for the actual number; the other bits are use by
-@command{emacs} for internal purposes. Therefore, we need to split
+Emacs for internal purposes. Therefore, we need to split
 @t{time_t} in two 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
@@ -4646,3 +4662,7 @@ it on all the time. By default, the log only maintains the most recent
 @include fdl.texi
 
 @bye
+
+@c Local Variables:
+@c coding: utf-8
+@c End: