mu4e: update the manual

Fill in all the menu descriptions. Rename a few sections.

mu4e/mu4e.texi

@@ -113,10 +113,10 @@ Appendices
 @chapter Introduction
 
 @menu
-* Why another e-mail client::
-* Other mail clients::
-* What mu4e does not do::
-* Becoming a mu4e user::
+* Why another e-mail client::Aren't there enough already
+* Other mail clients::Where mu4e takes its inspiration
+* What mu4e does not do::Focus on the core-business, delegate the rest
+* Becoming a mu4e user::Joining the club
 @end menu
 
 @node Why another e-mail client
@@ -624,10 +624,10 @@ correctly, and then shows you the @t{mu4e} main view. Its major mode is
 @code{mu4e-main-mode}.
 
 @menu
-* Overview: MV Overview.
-* Basic actions::
-* Bookmarks: MV Bookmarks.
-* Miscellaneous::
+* Overview:MV Overview. What is the main view
+* Basic actions::What can we do
+* Bookmarks:MV Bookmarks. Jumping to other places
+* Miscellaneous::Notes
 @end menu
 
 @node MV Overview
@@ -737,13 +737,13 @@ fields, for each matching message, followed by a footer line. The
 major-mode for the headers view is @code{mu4e-headers-mode}.
 
 @menu
-* Overview: HV Overview.
-* Keybindings::
-* Marking messages::
-* Sort order and threading::
-* HV Custom headers::
-* HV Actions::
-* Split view::
+* Overview: HV Overview. What is the Header View
+* Keybindings::Do things with your keyboard
+* Marking:HV Marking. Selecting messages for doing things
+* Sort order and threading::Influencing the display
+* HV Custom headers::Adding your own headers
+* HV Actions::Defining and using actions
+* Split view::Seeing both headers and messages
 @end menu
 
 @node HV Overview
@@ -897,8 +897,8 @@ q,z          leave the headers buffer
 @end verbatim
 
 
-@node Marking messages
-@section Marking messages
+@node HV Marking
+@section Marking
 
 You can @emph{mark} messages for a certain action, such as deletion or
 move. After one or more messages are marked, you can then execute
@@ -1044,14 +1044,14 @@ view window, which shows the message headers, followed by the message
 body. Its major mode is @code{mu4e-view-mode}.
 
 @menu
-* Overview: MSGV Overview.
-* Keybindings: MSGV Keybindings.
-* Opening and saving attachments::
-* Viewing images inline::
-* Displaying rich-text messages::
-* Crypto: MSGV Crypto.
-* Custom headers: MSGV Custom headers
-* Actions: MSGV Actions.
+* Overview: MSGV Overview. What is the Message View
+* Keybindings: MSGV Keybindings. Do things with your keyboard
+* Attachments:: Opening and saving them
+* Viewing images inline::Images display inside emacs
+* Displaying rich-text messages::Dealing with HTML mail
+* Verifying signatures and decryption: MSGV Crypto. Support for cryptography
+* Custom headers: MSGV Custom headers. Your own headers
+* Actions: MSGV Actions. Defining and using actions.
 @end menu
 
 @node MSGV Overview
@@ -1205,8 +1205,8 @@ q,z          leave the message view
 
 For the marking commands, please refer to @ref{Marking messages}.
 
-@node Opening and saving attachments
-@section Opening and saving attachments
+@node Attachments
+@section Attachments
 
 By default, @t{mu4e} uses the @t{xdg-open}-program
 @footnote{@url{http://portland.freedesktop.org/wiki/}} or (on OS X) the
@@ -1461,14 +1461,14 @@ functionality is available, as well some @t{mu4e}-specifics. Its major mode is
 @code{mu4e-compose-mode}.
 
 @menu
-* EV Overview::
-* Useful keybindings::
-* Address autocompletion::
-* Compose hooks::
-* Signing and encrypting::
-* Queuing mail::
-* Message signatures::
-* Other settings::
+* Overview:EV Overview. What is the Editor view
+* Keybindings: EV Keybindings. Doing things with your keyboard
+* Address autocompletion:: Quickly entering known addresses
+* Compose hooks::Calling functions when composing
+* Signing and encrypting:: Support for cryptography
+* Queuing mail:: Sending mail when the time is ripe
+* Message signatures:: Adding your personal footer to messages
+* Other settings::Miscellanea
 @end menu
 
 @node EV Overview
@@ -1492,8 +1492,8 @@ On Mon 16 Jan 2012 10:18:47 AM EET, Wally the Walrus wrote:
 @end cartouche
 
 
-@node Useful keybindings
-@section Useful keybindings
+@node EV Keybindings
+@section Keybindings
 
 @t{mu4e}'s editor view derives from Gnu's message editor and shares most of
 its keybindings. Here are some of the more useful ones (you can use the menu
@@ -1686,13 +1686,12 @@ you can set @code{mu4e-compose-signature-auto-include} to @code{nil}; you can
 then still include the signature manually, using the function
 @code{message-insert-signature}, typically bound to @kbd{C-c C-w}.
 
-
 @node Other settings
 @section Other settings
 
 @itemize
 @item If you want use @t{mu4e} as @command{emacs}' default program for sending mail,
-see @ref{Setting the default emacs mail program}.
+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
 configuration:
@@ -2041,17 +2040,17 @@ first you @emph{mark} them for a certain action, then you @emph{execute}
 can happen in both the @ref{Headers view} and the @ref{Message view}.
 
 @menu
-* Selecting messages for marking::
-* What to mark for::
-* Executing the marks::
-* Leaving the headers buffer::
-* Built-in marking functions::
-* Custom mark functions::
-* Adding a new kind of mark::
+* Marking messages::Selecting message do something with them 
+* What to mark for::What can we do with them
+* Executing the marks::Do it
+* Leaving the headers buffer::Handling marks automatically when leaving
+* Built-in marking functions::Helper functions for dealing with them
+* Custom mark functions::Define your own mark function
+* Adding a new kind of mark::Adding your own marks
 @end menu
 
-@node Selecting messages for marking
-@section Selecting messages for marking
+@node Marking messages
+@section Marking messages
 
 There are multiple ways to mark messages:
 @itemize
@@ -2268,11 +2267,11 @@ example:
 @chapter Contexts
 
 @menu
-* What contexts are made of::
-* Context policies::
-* Contexts and special folders::
-* Contexts example::
-* Some context tricks::
+* What are contexts::Defining the concept
+* Context policies::How to determine the current context
+* Contexts and special folders::Using context variables to determine them
+* Contexts example::How to define contexts
+* Some context tricks::Other thing to do with contexts
 @end menu
 
 It can be useful to switch between different sets of settings in
@@ -2292,8 +2291,8 @@ Tricks} section of this manual. Those still work - but the new mechanism
 has the benefit of being a core part of @code{mu4e}, thus allowing for
 deeper integration.
 
-@node What contexts are made of
-@section What context are made of
+@node What are contexts
+@section What are contexts
 
 Let's see what's contained in a context. Most of it is optional.
 
@@ -2628,11 +2627,11 @@ For general information extending @t{mu4e} and writing your own functions, see
 @ref{Extending mu4e}.
 
 @menu
-* Defining actions::
-* Adding an action in the headers view::
-* Adding an action in the message view::
-* Adding an attachment action::
-* More example actions::
+* Defining actions::How to create an action
+* Headers view actions::Doing things with message headers
+* Message view actions::Doing things with messages
+* Attachment actions::Doing things with attachments
+* Example actions::Some more examples
 @end menu
 
 @node Defining actions
@@ -2675,8 +2674,8 @@ description with that character.
 
 Let's look at some examples.
 
-@node Adding an action in the headers view
-@section Adding an action in the headers view
+@node Headers view actions
+@section Headers view actions
 
 Suppose we want to inspect the number of recipients for a message in the
 @ref{Headers view}. We add the following to our configuration:
@@ -2697,8 +2696,8 @@ Suppose we want to inspect the number of recipients for a message in the
 After evaluating this, @kbd{a N} in the headers view shows the number of
 recipients for the message at point.
 
-@node Adding an action in the message view
-@section Adding an action in the message view
+@node Message view actions
+@section Message view actions
 
 As another example, suppose we would like to search for messages by the sender
 of the message at point:
@@ -2720,8 +2719,8 @@ list of @code{(NAME . EMAIL)} cells; thus, @code{cdar} gets us the e-mail
 address of the first in the list. @t{From:}-fields rarely contain multiple
 cells.
 
-@node Adding an attachment action
-@section Adding an attachment action
+@node Attachment actions
+@section Attachment actions
 
 Finally, let's define an attachment action. As mentioned, attachment-action
 functions receive @emph{2} arguments, the message and the attachment number to
@@ -2741,8 +2740,8 @@ description).
 '("ncount lines" . count-lines-in-attachment) t)
 @end lisp
 
-@node More example actions
-@section More example actions
+@node Example actions
+@section Example actions
 
 @t{mu4e} includes a number of example actions in the file
 @file{mu4e-actions.el} in the source distribution (see @kbd{C-h f
@@ -2757,11 +2756,11 @@ emacs-lisp to make @t{mu4e} behave exactly as you want. Here, we provide some
 guidelines for doing so.
 
 @menu
-* Extension points::
-* Available functions::
-* Message functions::
-* Contact functions::
-* Utility functions::
+* Extension points::Where to hook into mu4e
+* Available functions::General helper functions
+* Message functions::Working with messages
+* Contact functions::Working with contacts
+* Utility functions::Miscellaneous helpers
 @end menu
 
 @node Extension points
@@ -2777,13 +2776,11 @@ refiling, based on a function - see @ref{Dynamic folders}
 @item Using an attachment-specific download-directory - see the
 variable @code{mu4e-attachment-dir}.
 @item Apply a function to a message in the headers view -
-see @ref{Adding an action in the headers view}
-@item Apply a function to a message in the message view - see @ref{Adding an
-action in the message view}
+see @ref{Headers view actions}
+@item Apply a function to a message in the message view - see @ref{Message view actions}
 @item Add a new kind of mark for use in the headers view
 - see @ref{Adding a new kind of mark}
-@item Apply a function to an attachment - see @ref{Adding an attachment
-action}
+@item Apply a function to an attachment - see @ref{Attachment actions}
 @item Custom function to mark certain messages - see @ref{Custom mark functions}
 @item Using various @emph{mode}-hooks, @code{mu4e-compose-pre-hook} (see
 @ref{Compose hooks}), @code{mu4e-index-updated-hook} (see @ref{FAQ})
@@ -2949,18 +2946,18 @@ In this chapter, we discuss some ways in ways in which @t{mu4e} can cooperate
 with other tools.
 
 @menu
-* Setting the default emacs mail program::
-* Creating org-mode links::
-* Maintaining an address-book with org-contacts::
-* Maintaining an address-book with BBDB::
-* Getting new mail notifications with Sauron::
-* Speedbar support::
-* Citations with mu-cite::
-* Attaching files with dired::
+* Emacs default::Making mu4e the default emacs e-mail program
+* Org-mode links::Adding mu4e to your organized life
+* Org-contacts::Hooking up with org-contacts
+* 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}
 @end menu
 
-@node Setting the default emacs mail program
-@section Setting the default @command{emacs} mail program
+@node Emacs default
+@section Emacs default
 
 @command{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
@@ -2971,8 +2968,9 @@ you can do so by adding the following to your configuration:
 (setq mail-user-agent 'mu4e-user-agent)
 @end lisp
 
-@node Creating org-mode links
-@section Creating @t{org-mode} links
+@node Org-mode links
+@section Org-mode links
+
 It can be useful to include links to e-mail messages or even search
 queries in your org-mode files. @t{mu4e} supports this with the
 @t{org-mu4e} module; you can set it up by adding it to your
@@ -3022,12 +3020,12 @@ for that in headers and view mode:
 (define-key mu4e-view-mode-map    (kbd "C-c c") 'org-mu4e-store-and-capture)
 @end lisp
 
-@node Maintaining an address-book with org-contacts
-@section Maintaining an address-book with org-contacts
+@node Org-contacts
+@section Org-contacts
 
 Note, @t{mu4e} supports built-in address autocompletion; @ref{Address
-autocompletion}, and that is the recommended way to do this. However, it is
-also possible to manage your addresses with @t{org-mode}, using
+autocompletion}, and that is the recommended way to do this. However, it
+is also possible to manage your addresses with @t{org-mode}, using
 @t{org-contacts}@footnote{@url{http://julien.danjou.info/software/org-contacts.el}}.
 
 @t{mu4e-actions} defines a useful action (@ref{Actions}) for adding a contact
@@ -3048,8 +3046,8 @@ view and the message view, using the @t{org-capture} mechanism. Note, the
 shortcut character @key{o} is due to the first character of
 @t{org-contact-add}.
 
-@node Maintaining an address-book with BBDB
-@section Maintaining an address-book with BBDB
+@node BBDB
+@section BBDB
 
 Note, @t{mu4e} supports built-in address autocompletion; @ref{Address
 autocompletion}, and that is the recommended way to do this. However, it
@@ -3084,8 +3082,8 @@ After this, you should be able to:
 @item View the BBDB contact while viewing a message
 @end itemize
 
-@node Getting new mail notifications with Sauron
-@section Getting new mail notifications with Sauron
+@node Sauron
+@section Sauron
 
 The @command{emacs}-package @t{sauron}@footnote{Sauron can be found at
 @url{https://github.com/djcb/sauron}, or in the Marmalade package-repository
@@ -3140,8 +3138,8 @@ You might want to put:
 in your setup, to allow the script to find the D-Bus session bus, even when
 running outside its session.
 
-@node Speedbar support
-@section Speedbar support
+@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}
@@ -3158,8 +3156,8 @@ list, such as auto-completion when jumping to a maildir.
 
 @code{mu4e-speedbar} was contributed by @emph{Antono Vasiljev}.
 
-@node Citations with mu-cite
-@section Citations with @t{mu-cite}
+@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
@@ -3173,13 +3171,12 @@ it work with @t{mu4e}:
 @lisp
 (require 'mu-cite)
 (setq mu4e-cite-function 'mu-cite-original)
-(setq mu-cite-top-format
-    '("On " date ", " from " wrote:\n\n"))
-(setq mu-cite-prefix-format '(" > ")))
+(setq mu-cite-top-format '("On " date ", " from " wrote:\n\n"))
+(setq mu-cite-prefix-format '(" > "))
 @end lisp
 
-@node Attaching files with dired
-@section Attaching files with @t{dired}
+@node Dired
+@section Dired
 
 It is possible to attach files to @t{mu4e} messages using @t{dired}
 (@inforef{Dired,,emacs}), using the following steps (based on a post on the
@@ -3220,14 +3217,13 @@ to see some working settings, we'd like to warn against blindly copying such
 things.
 
 @menu
-* Minimal configuration::
-* Longer configuration::
-* Gmail configuration::
-* Some other useful settings::
+* Minimal configuration::Simplest configuration to get you going
+* Longer configuration::A more extensive setup
+* Gmail configuration::GMail-specific setup
+* Other settings:CONF Other settings. Some other useful configuration
 
 @end menu
 
-
 @node Minimal configuration
 @section Minimal configuration
 
@@ -3510,8 +3506,8 @@ Next step: let's make a @t{mu4e} configuration for this:
 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}.
 
-@node Some other useful settings
-@section Some other useful settings
+@node CONF Other settings
+@section Other settings
 
 Finally, here are some more settings that are useful, but not enabled by
 default for various reasons.
@@ -3534,16 +3530,18 @@ In this chapter we list a number of actual and anticipated questions and their
 answers.
 
 @menu
-* General::
-* Reading messages::
-* Writing messages::
-* Known issues::
+* General::General questions and answers about mu4e
+* Reading messages::Dealing with incoming messages
+* Writing messages::Dealing with outgoing messages
+* Known issues::Limitations we know about
 @end menu
 
 @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,
@@ -3601,10 +3599,8 @@ gives me. Can I turn them off?}. Yes: set the variable
 @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{Is there context-sensitive help available?} Yes - pressing @key{H}
-should take you to the right place in this manual.
 @item @emph{How can I set @t{mu4e} as the default e-mail client in @command{emacs}?}
-See @ref{Setting the default emacs mail program}.
+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
@@ -3620,19 +3616,19 @@ 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-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, invisible in the UTF-8 version of this
-manual} becomes @t{/&MH4wijCCMEgwSg-}). How can display such folders
-correctly?} This is best solved by telling @command{offlineimap} to use UTF-8
-instead -- see
+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
 @url{https://github.com/djcb/mu/issues/68#issuecomment-8598652}.
 @item @emph{How can I customize the function to select a folder?}
 The @t{mu4e-completing-read} 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
-@t{ido-completing-read}; to use emacs's default behaviour, set the
-variable to @t{completing-read}. Helm users can use the same value, and
-by enabling @t{helm-mode} use helm-style completion.
+@code{ido-completing-read}; to use emacs's default behaviour, 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
@@ -3670,7 +3666,7 @@ See @ref{Html2text functions}.
 @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{Adding an action in the message view})
+there's an @emph{action} (@ref{Message view actions})
 defined for this. Simply add to your configuration:
 @lisp
 (add-to-list 'mu4e-view-actions
@@ -3723,7 +3719,7 @@ replying or forwarding?} Since @code{mu4e-compose-mode} derives from
 @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{Attaching files with 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.
@@ -3738,7 +3734,7 @@ message. Also see @ref{Signing and encrypting}.
 (2015-06-23) development release of BBDB
 @url{http://savannah.nongnu.org/projects/bbdb/}, or releases of BBDB
 after 3.1.2.
-@ref{Maintaining an address-book with BBDB}.
+@ref{BBDB}.
 @item @emph{After sending some messages, it seems the buffer for these
 messages stay around. How can I get rid of those?}
 @lisp
@@ -3843,13 +3839,43 @@ github-repository.
 @appendix Tips and Tricks
 
 @menu
-* Multiple accounts::
-* Refiling messages::
-* Saving outgoing messages::
-* Fancy characters and Inconsolata::
-* Confirmation before sending::
+* Fancy characters:: Non-ascii characters in the UI
+* Multiple accounts:: (Obsolete) the old way to deal with multiple accounts
+* Refiling messages:: Moving message to some archive folder
+* Saving outgoing messages:: Automatically save sent messages
+* Confirmation before sending:: Check messages before sending
 @end menu
 
+@node Fancy characters
+@section Fancy characters
+
+When using 'fancy characters' (@code{mu4e-use-fancy-chars}) with the
+@emph{Inconsolata}-font (and likely others as well), the display may be
+slightly off; the reason for this issue is that Inconsolata does not
+contain the glyphs for the 'fancy' arrows and the glyphs that are used
+as replacements are too high.
+
+To fix this, you can use something like the following workaround (in
+your @t{.emacs}-file):
+@lisp
+(if (equal window-system 'x)
+    (progn
+      (set-fontset-font "fontset-default" 'unicode "Dejavu Sans Mono")
+      (set-face-font 'default "Inconsolata-10")))
+@end lisp
+
+Other fonts with good support for Unicode are @t{unifont} and
+@t{symbola}.
+
+For a more complete solution, but with greater overhead, you can also
+try the @emph{unicode-fonts} package:
+@lisp
+(require 'unicode-fonts)
+(require 'persistent-soft) ; To cache the fonts and reduce load time
+(unicode-fonts-setup)
+@end lisp
+
+
 @node Multiple accounts
 @section Multiple accounts
 
@@ -4099,35 +4125,6 @@ If the from address is not associated with Account1 or with the Gmail
 account, the function uses @code{mu4e-ask-maildir-check-exists} to ask
 the user for a maildir to save the message in.
 
-@node Fancy characters and Inconsolata
-@section Fancy characters and Inconsolata
-
-When using 'fancy characters' (@code{mu4e-use-fancy-chars}) with the
-@emph{Inconsolata}-font (and likely others as well), the display may be
-slightly off; the reason for this issue is that Inconsolata does not
-contain the glyphs for the 'fancy' arrows and the glyphs that are used
-as replacements are too high.
-
-To fix this, you can use something like the following workaround (in
-your @t{.emacs}-file):
-@lisp
-(if (equal window-system 'x)
-    (progn
-      (set-fontset-font "fontset-default" 'unicode "Dejavu Sans Mono")
-      (set-face-font 'default "Inconsolata-10")))
-@end lisp
-
-Other fonts with good support for Unicode are @t{unifont} and
-@t{symbola}.
-
-For a more complete solution, but with greater overhead, you can also
-try the @emph{unicode-fonts} package:
-@lisp
-(require 'unicode-fonts)
-(require 'persistent-soft) ; To cache the fonts and reduce load time
-(unicode-fonts-setup)
-@end lisp
-
 @node Confirmation before sending
 @section Confirmation before sending
 
@@ -4149,10 +4146,10 @@ While perhaps not interesting for all users of @t{mu4e}, some curious
 souls may want to know how @t{mu4e} does its job.
 
 @menu
-* High-level overview::
-* mu server::
-* Reading from the server::
-* The message s-expression::
+* High-level overview::How the pieces go together
+* mu server::The mu process running in the background
+* Reading from the server::Processing responses from the server
+* The message s-expression::What messages look like from the inside
 @end menu
 
 @node High-level overview