* mu4e: documentation

mu4e/mu4e.texi

@@ -1671,7 +1671,7 @@ matches the regular expression.
 
 Using the same mechanism, you can set special sent-, trash-, and draft-folders
 for messages. The message-parameter you receive for sent and draft folder is
-the @emph{original} message, that is, the message you reply to or forward. If
+the @emph{original} message, that is, the message you reply to, or forward. If
 there is not such message (for example when composing a new message) the
 message parameter will be @t{nil}.
 
@@ -2061,6 +2061,8 @@ In this chapter, we show some example configurations.
 * Minimal configuration::
 * Longer configuration::
 * Gmail configuration::
+* Some other useful settings::
+
 @end menu
 
 
@@ -2071,6 +2073,8 @@ An (almost) minimal configuration for @t{mu4e} might look something like this:
 
 @lisp
 ;; example configuration for mu-for-emacs (mu4e)
+
+make sure mu4e is in your load-path
 (require 'mu4e)
 
 ;; happily, below settings are all /optional/
@@ -2089,7 +2093,12 @@ An (almost) minimal configuration for @t{mu4e} might look something like this:
 ;; (setq mu4e-drafts-folder "/drafts")
 ;; (setq mu4e-trash-folder  "/trash")
 
-;; for the settings for outgoing mail consult the section 'Longer configuration'
+;; smtp mail setting
+(setq
+   message-send-mail-function 'smtpmail-send-it
+   smtpmail-default-smtp-server "smtp.example.com"
+   smtpmail-smtp-server ""smtp.example.com"
+   smtpmail-local-domain "example.com")
 @end lisp
 
 
@@ -2101,14 +2110,18 @@ An (almost) minimal configuration for @t{mu4e} might look something like this:
 (require 'mu4e)
 
 (setq
-   ;; a regular expression that matches all email address uses by the user;
+   ;; a regular expression that matches all email address uses by
-   ;; this allows us to correctly determine if user is the sender of some message
+   ;; the user; this allows us to correctly determine if user
+   ;; is the sender / direct recipient of some message
    mu4e-user-mail-address-regexp
       "foo@@bar\.com\\|cuux@@example\.com"
 
    ;; path to our Maildir directory
    mu4e-maildir       "/home/user/Maildir"
+
    ;; the next are relative to `mu4e-maildir'
+   ;; instead of strings, they can be functions too, see
+   ;; chapter 'Dynamic folders'
    mu4e-sent-folder   "/sent"
    mu4e-drafts-folder "/drafts"
    mu4e-trash-folder  "/trash"
@@ -2120,13 +2133,14 @@ An (almost) minimal configuration for @t{mu4e} might look something like this:
        ("/work"        . ?w)
        ("/sent"        . ?s))
 
-   ;; when you want to use some external command for text->html conversion,
+   ;; when you want to use some external command for text->html
-   ;; i.e., the 'html2text' program
+   ;; conversion, e.g. the 'html2text' program
    mu4e-html2text-command "html2text"
 
-   ;; the headers to show in the headers list -- a pair of the field + its
+   ;; the headers to show in the headers list -- a pair of the field
-   ;; width, with `nil' meaning 'unlimited' (better only use that for
+   ;; and its width, with `nil' meaning 'unlimited'
-   ;; the last field. These are the defaults:
+   ;; (better only use that for the last field.
+   ;; These are the defaults:
    mu4e-headers-fields
     '( (:date          .  25)
        (:flags         .   6)
@@ -2253,16 +2267,20 @@ Now, let's make a @t{mu4e} configuration for this:
 (require 'mu4e)
 
 ;; default
-;; (setq mu4e-maildir (expand-file-name "~/Maildir"))
+;; (setq mu4e-maildir ("~/Maildir")
 
 (setq mu4e-drafts-folder "/[Gmail].Drafts")
 (setq mu4e-sent-folder   "/[Gmail].Sent Mail")
 (setq mu4e-trash-folder  "/[Gmail].Trash")
 
-;; don't save message to Sent Messages, Gmail/IMAP will take care of this
+;; don't save message to Sent Messages, Gmail/IMAP takes care of this
 (setq mu4e-sent-messages-behavior 'delete)
 
 ;; setup some handy shortcuts
+;; you can quickly switch to your Inbox -- press ``ji''
+;; then, when you want archive some messages, move them to
+;; the 'All Mail' folder by pressing ``ma''.
+
 (setq mu4e-maildir-shortcuts
     '( ("/INBOX"               . ?i)
        ("/[Gmail].Sent Mail"   . ?s)
@@ -2289,7 +2307,8 @@ Now, let's make a @t{mu4e} configuration for this:
 (setq message-send-mail-function 'smtpmail-send-it
    starttls-use-gnutls t
    smtpmail-starttls-credentials '(("smtp.gmail.com" 587 nil nil))
-   smtpmail-auth-credentials '(("smtp.gmail.com" 587 "USERNAME@@gmail.com" nil))
+   smtpmail-auth-credentials
+     '(("smtp.gmail.com" 587 "USERNAME@@gmail.com" nil))
    smtpmail-default-smtp-server "smtp.gmail.com"
    smtpmail-smtp-server "smtp.gmail.com"
    smtpmail-smtp-service 587)
@@ -2305,13 +2324,28 @@ Now, let's make a @t{mu4e} configuration for this:
 (setq message-kill-buffer-on-exit t)
 @end lisp
 
-And that's it -- put the above in your @file{~/.emacs} (obviously you need to
+And that's it -- put the above in your @file{~/.emacs}, change @t{USERNAME}
-change @t{USERNAME} etc. to your own), and restart @t{emacs}, and run @kbd{M-x
+etc. to your own, and restart @t{emacs}, and run @kbd{M-x mu4e}.
-mu4e}.
 
-Using these settings, you can quickly switch to your Inbox -- press
+
-@kbd{ji}. Then, when you want archive some messages, move them to the 'All
+@node Some other useful settings
-Mail' folder by pressing @kbd{ma}.
+@section Some other useful settings
+
+Finally, here are some more settings that are useful, but not enabled by
+default for various reasons.
+
+@lisp
+;; use 'fancy' non-ascii characters in various places in mu4e
+(setq mu4e-use-fancy-chars t)
+
+;; save attachment to my desktop
+(setq mu4e-attachment-dir "~/Desktop")
+
+;; attempt to show images when viewing messages
+(setq
+  mu4e-view-show-images t
+  mu4e-view-image-max-width 800)
+@end lisp
 
 
 @node FAQ - Frequently Anticipated Questions
@@ -2332,44 +2366,41 @@ can also use functions like @code{mu4e-headers-mark-thread} (@key{T}),
 time, and @code{mu4e-headers-mark-pattern} (@key{%}) to mark all messages
 matching a certain regular expression.
 @item @emph{mu4e seems to return a subset of all matches - how can I get
-all?}. Indeed, for speed reasons (and because, if you are like the author, you
+all?}. Indeed, for speed reasons, @t{mu4e} returns only up to the value of the
-usually don't need thousands of matches), @t{mu4e} returns only up to the
+variable @code{m4ue-search-result-limit} (default: 500) matches. To show
-value of the variable @code{m4ue-search-result-limit} matches. To show
 @emph{all} results, use @t{M-x mu4e-headers-toggle-full-search}, or customize
 the variable @code{mu4e-headers-full-search}. This applies to all search
 commands.
 @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 -- which not necessarily implies a new message, but
+triggered sees an update (no just new mail though). To use this hook, you can
-might close enough. To use this hook, you could put something like the
+put something like the following in your setup (assuming you have @t{aplay}
-following in your setup (assuming you have @t{aplay} and some soundfile,
+and some soundfile, change as needed):
-change as needed):
 @lisp
 (add-hook 'mu4e-index-updated-hook
   (defun new-mail-sound ()
     (shell-command "aplay ~/Sounds/boing.wav&")))
 @end lisp
-@item @emph{I don't use @t{offlineimap}, @t{fetchmail} etc., what should I use
+@item @emph{I don't use @t{offlineimap}, @t{fetchmail} etc., I get my mail
-for @code{mu4e-get-mail-command}}? Use @t{"true"}. This will make the getting
+through my own mailserver. What should I use for
-mail command a no-op, and then re-index the messages.
+@code{mu4e-get-mail-command}}? Use @t{"true"}. This makes getting mail
+a no-op, but will re-index the messages.
 @item @emph{When I try to run @t{mu index} while @t{mu4e} is running I get
 errors like @t{mu: mu_store_new_writable: xapian error 'Unable to get write
 lock on ~/.mu/xapian: already locked'}. What can I do about this?} You get
 this error because the underlying Xapian database allows itself to be opened
 in read-write mode only once. There is not much @t{mu4e} can do about this,
 but what you can do is telling @t{mu} to (gracefully) terminate:
-
 @verbatim
    pkill -2 -u $UID mu # send SIGINT
    sleep 1
    mu index
 @end verbatim
-
 @t{mu4e} will automatically restart @t{mu} when it needs it. In practice, this
 seems to work quite well.
 @item @emph{Can I automatically apply the marks on messages when
-leaving the headers buffer?} Yes you can -- see the documentation on
+leaving the headers buffer?} Yes you can -- see the documentation for the
-@t{mu4e-headers-leave-behavior}.
+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 emacs?}
@@ -2380,7 +2411,6 @@ boring plain-ASCII ones?} Glad you asked! Yes, you can set
 characters in a number of places.
 @end itemize
 
-
 @subsection Reading messages
 
 @itemize