mu4e.texi: update documentation

mu4e/mu4e.texi

@@ -732,7 +732,7 @@ The main view looks something like the following:
 
 @cartouche
 @verbatim
-* mu4e - mu for emacs version @value{VERSION}
+* mu4e - mu for emacs version x.y.z
 
   Basics
 
@@ -2792,7 +2792,7 @@ description).
 @t{mu4e} includes a number of example actions in the file
 @file{mu4e-actions.el} in the source distribution (see @kbd{C-h f
 mu4e-action-TAB}). For example, for viewing messages in an external web
-browser, or listening to a message's body-text using text-to-speech.
+browser.
 
 @node Extending mu4e
 @chapter Extending mu4e
@@ -2849,14 +2849,15 @@ certain pattern; again, see its docstring.
 @node Available functions
 @section Available functions
 
-The whole of @t{mu4e} consists of hundreds of elisp functions. However, the
+The whole of @t{mu4e} consists of hundreds of elisp functions. However,
-majority of those are for @emph{internal} use only; you can recognize them
+the majority of those are for @emph{internal} use only; you can
-easily, because they all start with @code{mu4e~}. These functions make all
+recognize them easily, because they all start with @code{mu4e~} or
-kinds of assumptions, and they are subject to change, and should therefore
+@code{mu4e--}. These functions make all kinds of assumptions, and they
-@emph{not} be used. The same is true for @emph{variables} that start with
+are subject to change, and should therefore @emph{not} be used. The same
-@code{mu4e~}; don't touch them.  Let me repeat that:
+is true for @emph{variables} with the same prefix; don't touch them. Let
+me repeat that:
 @verbatim
-Do not use mu4e~... functions or variables!
+Do not use mu4e~... or mu4e-- functions or variables!
 @end verbatim
 
 @noindent
@@ -2916,42 +2917,17 @@ point. Requires the 'formail' tool from procmail."
         (shell-quote-argument (mu4e-message-field-at-point :path))))))
 @end lisp
 
-@subsection Rewriting the message body
-
-Message body rewriting allows you to modify the message text that is
-presented in the message view. This can be useful if the message needs
-special processing, for instance for special filling or cleaning up
-encoding artifacts (this is what @t{mu4e} uses this for internally).
-
-To enable this, you can append your rewrite-function to
-@code{mu4e-message-body-rewrite-functions}; your function is expected to
-take two parameters @code{MSG} and @code{TXT}, which are the
-message-plist and the body-text, which could be the result of earlier
-transformations, including html->text conversion as per
-@code{mu4e-html2-text-command}. The function is expected to return the
-transformed text.
-
-As a fairly useless example, suppose we insist on reading @t{mu4e} as
-@t{MU4E}:
-@lisp
-(defun mu4e-to-MU4E-rewrite (msg txt)
-  (replace-regexp-in-string "mu4e" "MU4E" txt))
-
-(add-to-list 'mu4e-message-body-rewrite-functions 'mu4e-to-MU4E-rewrite t)
-@end lisp
-
-
 @node Contact functions
 @section Contact functions
 
-It can sometimes be useful to discard or rewrite the contact
+It can sometimes be useful to discard or rewrite the contact information
-information that @t{mu4e} provides, for example to fix spelling
+that @t{mu4e} provides, for example to fix spelling errors, or omit
-errors, or omit unwanted contacts.
+unwanted contacts.
 
-To handle this, @t{mu4e} provides
+To handle this, @t{mu4e} provides @code{mu4e-contact-process-function},
-@code{mu4e-contact-process-function}, which, if defined, is applied to
+which, if defined, is applied to each contact. If the result is @t{nil},
-each contact. If the result is @t{nil}, the contact is discarded,
+the contact is discarded, otherwise the (modified or not) contact
-otherwise the (modified or not) contact information is used.
+information is used.
 
 Each contact is a full e-mail address as you would see in a
 contact-field of an e-mail message, e.g.,
@@ -2984,8 +2960,8 @@ An example @code{mu4e-contact-process-function} might look like:
 @node Utility functions
 @section Utility functions
 
-@file{mu4e-utils} contains a number of utility functions; we list a few here.
+@file{mu4e-utils} contains a number of utility functions; we list a few
-See their docstrings for details:
+here. See their docstrings for details:
 @itemize
 @item @code{mu4e-read-option}: read one option from a list. For example:
 @lisp
@@ -3041,8 +3017,8 @@ you can do so by adding the following to your configuration:
 (setq mail-user-agent 'mu4e-user-agent)
 @end lisp
 
-Similarly, to specify @t{mu4e} as your preferred method for reading mail,
+Similarly, to specify @t{mu4e} as your preferred method for reading
-customize the variable @code{read-mail-command}.
+mail, customize the variable @code{read-mail-command}.
 
 @lisp
 (set-variable 'read-mail-command 'mu4e)
@@ -3121,9 +3097,9 @@ 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{https://julien.danjou.info/projects/emacs-packages#org-contacts}}.
 
-@t{mu4e-actions} defines a useful action (@ref{Actions}) for adding a contact
+@t{mu4e-actions} defines a useful action (@ref{Actions}) for adding a
-based on the @t{From:}-address in the message at point. To enable this, add to
+contact based on the @t{From:}-address in the message at point. To
-your configuration something like:
+enable this, add to your configuration something like:
 
 @lisp
   (setq mu4e-org-contacts-file  <full-path-to-your-org-contacts-file>)
@@ -3134,9 +3110,9 @@ your configuration something like:
 @end lisp
 
 @noindent
-After this, you should be able to add contacts using @key{a o} in the headers
+After this, you should be able to add contacts using @key{a o} in the
-view and the message view, using the @t{org-capture} mechanism. Note, the
+headers view and the message view, using the @t{org-capture} mechanism.
-shortcut character @key{o} is due to the first character of
+Note, the shortcut character @key{o} is due to the first character of
 @t{org-contact-add}.
 
 @node BBDB
@@ -3181,14 +3157,14 @@ After this, you should be able to:
 @section iCalendar
 
 When Gnus' article-mode is chosen (@ref{Message view}), it is possible
-to view and reply to iCalendar events.  To enable this feature, add
+to view and reply to iCalendar events. To enable this feature, add
 
 @lisp
 (require 'mu4e-icalendar)
 (mu4e-icalendar-setup)
 @end lisp
 
-to your configuration.  If you want that the original invitation message
+to your configuration. If you want that the original invitation message
 be automatically trashed after sending the message created by clicking
 on the buttons “Accept”, “Tentative”, or “Decline”, also add:
 
@@ -3197,7 +3173,7 @@ on the buttons “Accept”, “Tentative”, or “Decline”, also add:
 @end lisp
 
 When you reply to an iCal event, a line may be automatically added to
-the diary file of your choice.  You can specify that file with
+the diary file of your choice. You can specify that file with
 
 @lisp
 (setq mu4e-icalendar-diary-file "/path/to/your/diary")
@@ -3220,9 +3196,9 @@ Both the capture file and the headline(s) inside it must already exist.
 By default, @code{gnus-icalendar-org-setup} adds a temporary capture
 template to the variable @code{org-capture-templates}, with the
 description ``used by gnus-icalendar-org'', and the shortcut key ``#''.
-If you want to use your own template, create it using the same key
+If you want to use your own template, create it using the same key and
-and description. This will prevent the temporary one from being
+description. This will prevent the temporary one from being installed
-installed next time you @code{gnus-icalendar-org-setup} is called.
+next time you @code{gnus-icalendar-org-setup} is called.
 
 The full default capture template is:
 
@@ -3246,9 +3222,9 @@ prompting for the date, you could use the following:
    "%i" :immediate-finish t :time-prompt t)
 @end lisp
 
-Note that the default behaviour for @code{datetree} targets in this situation
+Note that the default behaviour for @code{datetree} targets in this
-is to store the event at the date that you capture it, not at the date
+situation is to store the event at the date that you capture it, not at
-that it is scheduled. That's why I've suggested using the
+the date that it is scheduled. That's why I've suggested using the
 @code{:timeprompt t} argument. This gives you an opportunity to set the
 time to the correct value yourself.
 
@@ -3333,32 +3309,32 @@ 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.
 
-To enable this, add @t{(require 'mu4e-speedbar)} to your
+To enable this, add @t{(require 'mu4e-speedbar)} to your configuration;
-configuration; then, all you need to do to activate it is @kbd{M-x
+then, all you need to do to activate it is @kbd{M-x speedbar}. Then,
-speedbar}. Then, when then switching to the @ref{Main view}, the
+when then switching to the @ref{Main view}, the speedbar-frame is
-speedbar-frame is updated with your bookmarks and maildirs.
+updated with your bookmarks and maildirs.
 
 For speed reasons, the list of maildirs is determined when @t{mu4e}
 starts; if the list of maildirs changes while @t{mu4e} is running, you
-need to restart @t{mu4e} to have those changes reflected in the
+need to restart @t{mu4e} to have those changes reflected in the speedbar
-speedbar and in other places that use this list, such as
+and in other places that use this list, such as auto-completion when
-auto-completion when jumping to a maildir.
+jumping to a maildir.
 
 @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
+(@inforef{Dired,,emacs}), using the following steps (based on a post on
-@t{mu-discuss} mailing list by @emph{Stephen Eglen}).
+the @t{mu-discuss} mailing list by @emph{Stephen Eglen}).
 
 
 @lisp
 (add-hook 'dired-mode-hook 'turn-on-gnus-dired-mode)
 @end lisp
 
-Then, mark the file(s) in @t{dired} you would like to attach and press @t{C-c
+Then, mark the file(s) in @t{dired} you would like to attach and press
-RET C-a}, and you'll be asked whether to attach them to an existing message,
+@t{C-c RET C-a}, and you'll be asked whether to attach them to an
-or create a new one.
+existing message, or create a new one.
 
 @node Hydra
 @section Hydra
@@ -3393,8 +3369,8 @@ Now, you can bind a convenient key to my-mu4e-bookmarks/body.
 By default, mu4e presents iCalendar invitations as .vcs file
 attachments. Experimental support is available to parse these
 attachments in order to add the expected ``Accept'', ``Reject'', ``Add
-to Calendar'' buttons. This requires using Gnus' article view, which
+to Calendar'' buttons. This requires using Gnus' article view, which is
-is the default since @t{mu4e} version 1.6.
+the default since @t{mu4e} version 1.6.
 
 The minimal setup is:
 
@@ -3545,9 +3521,9 @@ customize.
 @node Gmail configuration
 @section Gmail configuration
 
-@emph{Gmail} is a popular e-mail provider; let's see how we can make it work
+@emph{Gmail} is a popular e-mail provider; let's see how we can make it
-with @t{mu4e}. Since we are using @abbr{IMAP}, you must enable that in the
+work with @t{mu4e}. Since we are using @abbr{IMAP}, you must enable that
-Gmail web interface (in the settings, under the ``Forwarding and
+in the Gmail web interface (in the settings, under the ``Forwarding and
 POP/IMAP''-tab).
 
 Gmail users may also be interested in @ref{Including related messages},
@@ -3555,9 +3531,9 @@ and in @ref{Skipping duplicates}.
 
 @subsection Setting up offlineimap
 
-First of all, we need a program to get the e-mail from Gmail to our local
+First of all, we need a program to get the e-mail from Gmail to our
-machine; for this we use @t{offlineimap}; on Debian (and derivatives like
+local machine; for this we use @t{offlineimap}; on Debian (and
-Ubuntu), this is as easy as:
+derivatives like Ubuntu), this is as easy as:
 
 @verbatim
 $ sudo apt-get install offlineimap
@@ -3836,9 +3812,9 @@ higher value, e.g. by adding the following to your configuration:
 
 @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).
+indexing process triggered sees an update (not just new mail though). To
-To use this hook, put something like the following in your setup
+use this hook, put something like the following in your setup (assuming
-(assuming you have @t{aplay} and some soundfile, change as needed):
+you have @t{aplay} and some soundfile, change as needed):
 @lisp
 (add-hook 'mu4e-index-updated-hook
   (defun new-mail-sound ()
@@ -3847,9 +3823,9 @@ To use this hook, put something like the following in your setup
 
 @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
+default) which then uses @t{/bin/true} (a command that does nothing and
-and always succeeds). This makes getting mail a no-op, but the
+always succeeds). This makes getting mail a no-op, but the messages are
-messages are still re-indexed.
+still re-indexed.
 
 @subsection How can I re-index my messages without getting new mail?
 Use @kbd{M-x mu4e-update-index}
@@ -3860,11 +3836,11 @@ For instance:
 mu: mu_store_new_writable: xapian error
   'Unable to get write lock on ~/.cache/mu/xapian: already locked
 @end verbatim
-What to do about this? You get this error because the underlying
+What to do about this? You get this error because the underlying Xapian
-Xapian database is locked by some other process; it can be opened only
+database is locked by some other process; it can be opened only once in
-once in read-write mode. There is not much @t{mu4e} can do about this,
+read-write mode. There is not much @t{mu4e} can do about this, but if is
-but if is another @command{mu} instance that is holding the lock, you
+another @command{mu} instance that is holding the lock, you can ask it
-can ask it to (gracefully) terminate:
+to (gracefully) terminate:
 @verbatim
    pkill -2 -u $UID mu # send SIGINT
    sleep 1
@@ -3879,8 +3855,8 @@ 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
+names when they are moved to different folders. @t{mu4e} can attempt to
-to help with this - you can set the variable
+help with this - you can set the variable
 @code{mu4e-change-filenames-when-moving} to non-@t{nil}.
 
 @subsection @command{offlineimap} and UTF-7
@@ -3894,11 +3870,11 @@ instead --- see
 
 @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.
+always agree with @t{mu} about the meaning of various Maildir-flags. If
-If you encounter unexpected behavior, it is recommended you check
+you encounter unexpected behavior, it is recommended you check before
-before and after a sync-operation. If the problem only shows up
+and after a sync-operation. If the problem only shows up @emph{after}
-@emph{after} sync'ing, the problem is with the sync-program, and it's
+sync'ing, the problem is with the sync-program, and it's most productive
-most productive to complain there.
+to complain there.
 
 Also, you may want to ensure that @t{mu4e-index-lazy-check} is kept at
 its default (@t{nil}) value, since it seems @command{mbsync} can make