mu4e: update docs

1 files changed, 187 insertions, 4 deletions

diff --git a/README.org b/README.org
index 41ba1ed..9cba3d0 100644
--- a/README.org
+++ b/README.org
@@ -13,7 +13,6 @@
 
 Welcome to ~mu~!
 
-
 Latest development news: [[NEWS.org]].
 
 With the enormous amounts of e-mail many people gather and the importance of
@@ -25,6 +24,10 @@ now, and quickly file away message for later use.
 Maildir-format. ~mu~'s goal is to help you to quickly find the messages you need,
 view them, extract attachments, and so on.
 
+#+BEGIN_HTML
+<img src="assets/mu-structure.png"/>
+#+END_HTML
+
 After indexing your messages into a [[http://www.xapian.org][Xapian]]-database, you can search them through
 a query language. You can use various message fields or words in the body text
 to find the right messages.
@@ -44,6 +47,10 @@ under the name ~maildir-utils~; apparently because they don't like short names.
 All of the code is distributed under the terms of the [[https://www.gnu.org/licenses/gpl-3.0.en.html][GNU General Public License
 version 3]] (or higher).
 
+The ~mu~ project welcomes contributions; see the Github issue list and [[IDEAS.org]].
+
+Users and developers are encouraged to join the [[https://groups.google.com/g/mu-discuss/][mu-discuss]] mailing-list.
+
 * Versions
 
 *mu* attempts to balance development speed and stability.
@@ -144,6 +151,182 @@ queries:
 $ mu find hello
 #+end_example
 
-* Contributing
-
-Contributions are welcome! See the Github issue list and [[IDEAS.org]].
+* Mu4e
+
+Mu4e is an e-mail client for [[https://www.gnu.org/software/emacs/][GNU/Emacs]] that works on top of ~mu~.
+
+~mu4e~ is shipped as part of the ~mu~ package, and the versions must match.
+
+Since there are so many different ways people use e-mail, there are a lot of
+ways to customize it to your needs; see the [[https://www.djcbsoftware.nl/code/mu/mu4e/][Mu4e Reference Manual]] for all the
+details, here we include quick-start instructions, in the form of ~use-package~
+declaration. Much of it is commented-out, pick the parts that best fit your
+particular needs; see the manual for a deeper dive.
+
+#+begin_src elisp
+(use-package mu4e
+  :ensure nil
+  :config
+;;;; Basics
+
+  ;; (setq mu4e-mu-binary "/path/to/mu") ; only needed if mu is not in PATH
+  (setq mail-user-agent 'mu4e) ;; mu4e as the default emacs mail program
+
+  ;; Identify yourself. Not strictly necessary.
+  ;; (setq
+  ;;  user-mail-address "mickey@example.com"
+  ;;  user-full-name "Mickey Mouse")
+
+  ;;
+;;;; Retrieving mail
+  ;;
+  ;; Here, put the command you use for getting mail from some
+  ;; remote server to your local Maildir. You can leave it at its
+  ;; default when you have local delivery (rare these days)
+  ;;
+  ;; The command depends on your local setup, e.g.:
+  ;; "offlineimap", "mbsync", "fetchmail", ... or some shell script
+  (setq mu4e-get-mail-command "/bin/true" ;;
+        mu4e-update-interval 180)         ;; check every 3 minutes
+
+  ;;
+;;;; Reading mail
+  ;;
+  ;; You need to tell mu4e where it can find certain mail folders
+  ;; in your Maildir; these are the paths relative to your maildir-root.
+  ;; (setq
+  ;;  mu4e-inbox-folder  "/inbox"
+  ;;  mu4e-sent-folder   "/sent"
+  ;;  mu4e-drafts-folder "/drafts"
+  ;;  mu4e-trash-folder  "/trash")
+  ;;
+  ;; For Gmail, these could look something like:
+  ;; (setq
+  ;;  mu4e-inbox-folder  "/INBOX"
+  ;;  mu4e-sent-folder   "/[Gmail]/Sent Mail"
+  ;;  mu4e-drafts-folder "/drafts"
+  ;;  mu4e-trash-folder  "/trash")
+  ;; ;; (here we keep /drafts & /trash local)
+
+  ;; define some shortcuts to maildirs you use often
+  ;; the :key defines the shortcut key, the other parameters
+  ;; determine what is (not) shown in the main-view. See the
+  ;; `mu4e-maildir-shortcuts' docstring.
+  ;; (setq mu4e-maildir-shortcuts
+  ;;       '((:maildir "/inbox"       :key ?i :hide-if-no-unread t :favorite t)
+  ;;         (:maildir "/lists"       :key ?l :hide-if-no-unread t)
+  ;;         (:maildir "/sent"        :key ?s :hide-unread t))))
+
+  ;; Defaults to homedir. Can also be a function, for file-specific
+  ;; dirs; see docstring.
+  ;; (setq mu4e-attachment-dir "~/Downloads")
+
+  ;;
+;;;; Sending mail
+  ;;
+  ;; Mail sending goes through the Emacs smtpmail package
+  ;; the exact settings depend on your SMTP provider
+  (setq
+   send-mail-function          smtpmail-send-it
+   message-send-mail-function  smtpmail-send-it
+   ;; smtpmail-smtp-user          "user@example.com"
+   ;; smtpmail-smtp-server        "smtp.example.com"
+   ;; smtpmail-smtp-service       465
+   ;; smtpmail-stream-type        'tls
+   )
+
+  ;;
+;;;; Extras
+  ;;
+  ;; There are *many* more settings to customize mu4e. Here are a few common
+  ;; ones; just some examples, tweak to your preferences.
+
+  ;; prefer text when mails have both text and html
+  ;; (with-eval-after-load "mm-decode"
+  ;;   (add-to-list 'mm-discouraged-alternatives "text/html")
+  ;;   (add-to-list 'mm-discouraged-alternatives "text/richtext")
+  ;;   (add-to-list 'mm-discouraged-alternatives "multipart/related"))
+
+  ;; Some visual tweaks
+  (setq mu4e-use-fancy-chars t) ;; allow for unicode emojis
+
+  ;;
+  ;;;; Custom bookmarks / queries
+  ;; e.g.:
+  ;; (add-to-list 'mu4e-bookmarks
+  ;;              '( :name  "Inbox messages in the last 7 days"
+  ;;                 :query (lambda ()
+  ;;                          (format "maildir:/inbox AND date:%s"
+  ;;                                  (format-time-string
+  ;;                                   "%Y%m%d.."
+  ;;                                   (subtract-time (current-time)
+  ;;                                                  (days-to-time 7)))))
+  ;;                 :key   ?w))
+
+  ;; Tweak headers display; i.e. what headers to show, sizes etc.
+  ;; Eg:
+  ;; (setq
+  ;;  mu4e-headers-date-format "%Y-%m-%d"
+  ;;  mu4e-headers-time-format "%H:%M"
+  ;;  mu4e-headers-fields
+  ;;  '((:human-date     .  10)
+  ;;    (:flags          .  4)
+  ;;    (:from-or-to     .  20)
+  ;;    (:mailing-list   .  8)
+  ;;    (:maildir        .  8)
+  ;;    (:labels         .  8)
+  ;;    (:thread-subject .  nil)))
+
+  ;; Refiling a messages ('r'), i.e., move messages to some other folder,
+  ;; based on their properties. mu4e-refile-folder can be a folder-name
+  ;; or a function taking a message and returning a folder-name
+  ;; (setq mu4e-refile-folder
+  ;;         (lambda (msg)
+  ;;           (cond
+  ;;            ;; all messages sent by me go to the sent folder
+  ;;            ((mu4e-message-sent-by-me msg) (mu4e-get-sent-folder msg))
+  ;;            ;; all mu-related messages go to the mu folder
+  ;;            ((mu4e-message-contact-field-matches msg :to
+  ;;                                                 "mu-discuss@googlegroups.com")
+  ;;             "/mu")
+  ;;            ;; some work-related senders
+  ;;            ((seq-some
+  ;;              (lambda (addr) (mu4e-message-contact-field-matches msg :from addr))
+  ;;              `(,(rx "boss@company.com" eos)
+  ;;                ,(rx "lucy@bookkeeper.com" eos)
+  ;;                ,(rx "jim@taxes.gov" eos)))
+  ;;             "/work")
+  ;;            ;; everything else goes to /archive
+  ;;            (t
+  ;;             "/archive"))))
+
+  ;; Tweak the message-view
+  ;; (setq
+  ;;  mu4e-view-date-format "%Y-%m-%d %H:%M"
+  ;;  mu4e-view-fields
+  ;;  '(:from :to :cc :bcc :subject :flags :date :maildir :mailing-list))
+
+  ;; with nerd-icons or all-the-icons installed, you can get some icons when
+  ;; view messaages, e.g.
+  ;; (setq mu4e-file-name-to-icon-function #'nerd-icons-icon-for-file)
+  ;;  or
+  ;; (setq mu4e-file-name-to-icon-function #'all-the-icons-icon-for-file)
+
+  ;; Set a message signature:
+  ;; (setq message-signature
+  ;;       (concat
+  ;;        "User McUserFace\n"
+  ;;        "http://www.example.com\n"))
+
+  :hook
+  ;; tweak the composer
+  ((mu4e-compose-mode . (lambda ()
+                          (set-fill-column 72)
+                          (flyspell-mode)))
+   ;; allow for inserting attachments with dired,
+   ;;   with `M-x gnus-dired-attach'
+   (dired-mode  . turn-on-gnus-dired-mode))
+
+  :bind ;; the Mu4e transient menu
+  (("C-c m" . mu4e-transient-menu)))
+#+end_src