mu4e: update documentation

Add the beginning of some docs for the gnus-view.

mu4e/mu4e.texi

@@ -90,7 +90,8 @@ section with answers to frequenly asked questions, @ref{FAQ}.
 * Main view:: The @t{mu4e} overview
 * Headers view:: Lists of message headers
 * Message view:: Viewing specific messages
-* Editor view:: Creating / editing messages
+* Old message view:: The old way to view messages
+* Editor view:: Creating and editing messages
 * Searching:: Some more background on searching/queries`
 * Marking:: Marking messages and performing actions
 * Contexts:: Defining contexts and switching between them
@@ -753,34 +754,34 @@ The main view looks something like the following:
 
   Basics
 
-	* [j]ump to some maildir
+        * [j]ump to some maildir
-	* enter a [s]earch query
+        * enter a [s]earch query
-	* [C]ompose a new message
+        * [C]ompose a new message
 
   Bookmarks
 
-	* [bu] Unread messages      (26119/26119)
+        * [bu] Unread messages      (26119/26119)
-	* [bt] Today's messages     (1/7)
+        * [bt] Today's messages     (1/7)
-	* [bw] Last 7 days          (30/126)
+        * [bw] Last 7 days          (30/126)
-	* [bp] Messages with images (268/2309)
+        * [bp] Messages with images (268/2309)
 
   Maildirs
 
-	* [ja] /archive             (3174/17990)
+        * [ja] /archive             (3174/17990)
-	* [ji] /inbox               (0/2)
+        * [ji] /inbox               (0/2)
-	* [jm] /mu                  (1541/14884)
+        * [jm] /mu                  (1541/14884)
-	* [js] /sent
+        * [js] /sent
 
   Misc
 
-	* [;]Switch context
+        * [;]Switch context
-	* [U]pdate email & database
+        * [U]pdate email & database
-	* toggle [m]ail sending mode (currently direct)
+        * toggle [m]ail sending mode (currently direct)
 
-	* [N]ews
+        * [N]ews
-	* [A]bout mu4e
+        * [A]bout mu4e
-	* [H]elp
+        * [H]elp
-	* [q]uit
+        * [q]uit
 
   Info
 
@@ -1182,25 +1183,22 @@ headers-view to the message-view and vice-versa with
 @code{mu4e-select-other-view}, bound to @key{y}
 @end itemize
 
+
 @node Message view
 @chapter The message view
 
-After selecting a message in the @ref{Headers view}, it appears in a message
+This chapter discusses the new (since version 1.6) Gnus-based message
-view window, which shows the message headers, followed by the message
+view. However, the old one is stil available -- see @ref{Old message
-body. Its major mode is @code{mu4e-view-mode}.
+view}.
 
-Note, the current message view is to be replaced by a new one, based on
+After selecting a message in the @ref{Headers view}, it appears in a
-Gnus' article-mode. It is available now as a 'tech preview', which you
+message view window, which shows the message headers, followed by the
-can try by setting @code{mu4e-view-use-gnus} to @code{t} before starting
+message body. Its major mode is @code{mu4e-view-mode}, which derives
-@code{mu4e}.
+from @t{gnus-article-mode}.
 
 @menu
 * 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
@@ -1210,6 +1208,184 @@ can try by setting @code{mu4e-view-use-gnus} to @code{t} before starting
 
 An example message view:
 
+@cartouche
+@verbatim
+    From: randy@epiphyte.com
+    To: julia@eruditorum.org
+    Subject: Re: some pics
+    Flags: seen, attach
+    Date: Thu, 11 Feb 2021 12:59:30 +0200 (4 weeks, 3 days, 21 hours ago)
+    Maildir: /inbox
+    Attachments: [2. image/jpeg; DSCN4961.JPG]... [3. image/jpeg; DSCN4962.JPG]...
+
+    Hi Julia,
+
+    Some pics from our trip to Cerin Amroth. Enjoy!
+
+    All the best,
+    Randy.
+
+    On Sun 21 Dec 2003 09:06:34 PM EET, Julia wrote:
+
+    [....]
+@end verbatim
+@end cartouche
+
+Some notes:
+@itemize
+@item The variable @code{mu4e-view-fields} determines the header fields to be
+shown; see @code{mu4e-header-info} for a list of built-in fields. Apart from
+the built-in fields, you can also create custom fields using
+@code{mu4e-header-info-custom}; see @ref{MSGV Custom headers}.
+@item For search-related operations, see @ref{Searching}.
+@item You can scroll down the message using @key{SPC}; if you do this at the
+end of a message,it automatically takes you to the next one. If you want to
+prevent this behavior, set @code{mu4e-view-scroll-to-next} to @code{nil}.
+@end itemize
+
+@node MSGV Keybindings
+@section Keybindings
+
+You can find most things you can do with this message in the @emph{Mu4e} menu,
+or by using the keyboard; the default bindings are:
+
+@verbatim
+key          description
+==============================================================
+n,p          view the next, previous message
+],[          move to the next, previous unread message
+y            select the headers view (if it's visible)
+
+RET          scroll down
+M-RET        open URL at point / attachment at point
+
+SPC          scroll down, if at end, move to next message
+S-SPC        scroll up
+
+searching
+---------
+s            search
+e            edit last query
+/            narrow the search
+b            search bookmark
+B            edit bookmark before search
+j            jump to maildir
+
+M-left       previous query
+M-right      next query
+
+marking
+-------
+d            mark for moving to the trash folder
+=            mark for removing trash flag ('untrash')
+DEL,D        mark for complete deletion
+m            mark for moving to another maildir folder
+r            mark for refiling
++,-          mark for flagging/unflagging
+
+u            unmark message at point
+U            unmark *all* messages
+
+%            mark based on a regular expression
+T,t          mark whole thread, subthread
+
+<insert>,*   mark for 'something' (decide later)
+#            resolve deferred 'something' marks
+
+x            execute actions for the marked messages
+
+composition
+-----------
+R,F,C        reply/forward/compose
+E            edit (only allowed for draft messages)
+
+actions
+-------
+g            go to (visit) numbered URL (using `browse-url')
+(or: <mouse-1> or M-RET with point on url)
+C-u g visits multiple URLs
+f            fetch (download )the numbered URL.
+C-u f fetches multiple URLs
+k            save the numbered URL in the kill-ring.
+C-u k saves multiple URLs
+
+e            extract (save) one or more attachments (asks for numbers)
+(or: <mouse-2> or S-RET with point on attachment)
+a            execute some custom action on the message
+
+misc
+----
+;            switch context
+c            copy address at point (with C-u copy long version)
+
+h            toggle between html/text (if available)
+
+.            show the raw message view. 'q' takes you back.
+C-+,C--      increase / decrease the number of headers shown
+H            get help
+C-S-u        update mail & reindex
+q            leave the message view
+@end verbatim
+
+For the marking commands, please refer to @ref{Marking messages}.
+
+
+@node MSGV Custom headers
+@section Custom headers
+
+Sometimes the normal headers that @t{mu4e} offers (Date, From, To,
+Subject etc.) may not be enough. For these cases, @t{mu4e} offers
+@emph{custom headers} in both the headers-view and the message-view.
+
+See @ref{HV Custom headers} for an example of this; the difference for
+the message-view is that you should add your custom header to
+@code{mu4e-view-fields} rather than @code{mu4e-headers-fields}.
+
+@node MSGV Actions
+@section Actions
+
+You can perform custom functions (``actions'') on messages and their
+attachments. For a general discussion on how to define your own, see
+@ref{Actions}.
+
+@subsection Message actions
+@code{mu4e-view-action} (@key{a}) lets you pick some custom action to perform
+on the current message. You can specify these actions using the variable
+@code{mu4e-view-actions}; @t{mu4e} defines a number of example actions.
+
+
+@node Old message view
+@chapter The old message view
+
+Since version 1.6 @t{mu4e} defaults to the new, Gnus-based, message view.
+
+However, the older view is still available, and this chapter is about
+that one. While we recommend using the default one, you can still use
+the old one by configuring it:
+@lisp
+(setq mu4e-view-use-gnus nil)
+@end lisp
+
+After selecting a message in the @ref{Headers view}, it appears in a message
+view window, which shows the message headers, followed by the message
+body. Its major mode is @code{mu4e-view-mode}.
+
+@menu
+* Overview: OMSGV Overview. What is the Message View
+* Keybindings: OMSGV 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: OMSGV Crypto. Support for cryptography
+* Custom headers: OMSGV Custom headers. Your own headers
+* Actions: OMSGV Actions. Defining and using actions.
+@end menu
+
+@node OMSGV Overview
+@section Overview
+
+An example message view:
+
 @cartouche
 @verbatim
     From: randy@epiphyte.com
@@ -1238,7 +1414,7 @@ Some notes:
 @item The variable @code{mu4e-view-fields} determines the header fields to be
 shown; see @code{mu4e-header-info} for a list of built-in fields. Apart from
 the built-in fields, you can also create custom fields using
-@code{mu4e-header-info-custom}; see @ref{MSGV Custom headers}.
+@code{mu4e-header-info-custom}; see @ref{OMSGV Custom headers}.
 @item You can set the date format with the variable
 @code{mu4e-date-format-long}.
 @item By default, only the names of contacts in address fields are visible
@@ -1263,7 +1439,7 @@ end of a message,it automatically takes you to the next one. If you want to
 prevent this behavior, set @code{mu4e-view-scroll-to-next} to @code{nil}.
 @end itemize
 
-@node MSGV Keybindings
+@node OMSGV Keybindings
 @section Keybindings
 
 You can find most things you can do with this message in the @emph{Mu4e} menu,
@@ -1508,8 +1684,8 @@ long messages in some external browser (see `browse-url-generic-program')."
   (let ((html (or (mu4e-message-field msg :body-html) "")))
     (if (> (length html) 20000)
       (progn
-	(mu4e-action-view-in-browser msg)
+        (mu4e-action-view-in-browser msg)
-	"[Viewing message in external browser]")
+        "[Viewing message in external browser]")
       (mu4e-shr2text msg))))
 
 (setq mu4e-html2text-command 'my-mu4e-html2text)
@@ -1526,7 +1702,7 @@ If that is an issue, it is recommended to use a browser (or browser
 profile) that does not load images. The same applies to Javascript.
 
 
-@node MSGV Crypto
+@node OMSGV Crypto
 @section Crypto
 
 The @t{mu4e} message view supports decryption of encrypted messages,
@@ -1598,7 +1774,7 @@ Also, the From: address can easily be forged.
 
 For more information, see the @command{mu-verify} manual page.
 
-@node MSGV Custom headers
+@node OMSGV Custom headers
 @section Custom headers
 
 Sometimes the normal headers that @t{mu4e} offers (Date, From, To, Subject
@@ -1609,7 +1785,7 @@ See @ref{HV Custom headers} for an example of this; the difference for the
 message-view is that you should add your custom header to
 @code{mu4e-view-fields} rather than @code{mu4e-headers-fields}.
 
-@node MSGV Actions
+@node OMSGV Actions
 @section Actions
 
 You can perform custom functions (``actions'') on messages and their
@@ -1773,13 +1949,13 @@ Let's look at some examples. First, suppose we want to set the
     "Set the From address based on the To address of the original."
     (let ((msg mu4e-compose-parent-message)) ;; msg is shorter...
       (when msg
-	(setq user-mail-address
+        (setq user-mail-address
-	  (cond
+          (cond
-	    ((mu4e-message-contact-field-matches msg :to "me@@foo.example.com")
+            ((mu4e-message-contact-field-matches msg :to "me@@foo.example.com")
-	      "me@@foo.example.com")
+              "me@@foo.example.com")
-	    ((mu4e-message-contact-field-matches msg :to "me@@bar.example.com")
+            ((mu4e-message-contact-field-matches msg :to "me@@bar.example.com")
-	      "me@@bar.example.com")
+              "me@@bar.example.com")
-	    (t "me@@cuux.example.com")))))))
+            (t "me@@cuux.example.com")))))))
 @end lisp
 
 Secondly, as mentioned, @code{mu4e-compose-mode-hook} is especially
@@ -1810,12 +1986,12 @@ Or to something context-specific:
 (add-hook 'mu4e-compose-mode-hook
   (lambda()
     (let* ((ctx (mu4e-context-current))
-	    (name (if ctx (mu4e-context-name ctx))))
+            (name (if ctx (mu4e-context-name ctx))))
       (when name
-	(cond
+        (cond
-	  ((string= name "account1")
+          ((string= name "account1")
             (save-excursion (message-add-header "Bcc: account1@@example.com\n")))
-	  ((string= name "account2")
+          ((string= name "account2")
             (save-excursion (message-add-header "Bcc: account2@@example.com\n"))))))))
 @end lisp
 
@@ -1833,7 +2009,7 @@ mml-secure-message-encrypt-pgp}, @kbd{M-x mml-secure-message-sign-pgp}.
 
 The support for encryption and signing is @emph{independent} of the support
 for their counterparts, decrypting and signature verification (as discussed in
-@ref{MSGV Crypto}). Even if your @t{mu4e} does not have support for the latter
+@ref{OMSGV Crypto}). Even if your @t{mu4e} does not have support for the latter
 two, you can still sign/encrypt messages.
 
 Important note: the messages are encrypted when they are @emph{sent}:
@@ -2434,7 +2610,7 @@ than @emph{n} recipients --- we could do this with the following recipe:
   '("More than n recipients"
      (lambda (msg n)
        (> (+ (length (mu4e-message-field msg :to))
-	    (length (mu4e-message-field msg :cc))) n))
+            (length (mu4e-message-field msg :cc))) n))
      (lambda ()
        (read-number "Match messages with more recipients than: "))) t)
 @end lisp
@@ -2498,7 +2674,7 @@ loading @t{mu4e}):
      :prompt     "gtag"
      :ask-target (lambda () (read-string "What tag do you want to add?"))
      :action      (lambda (docid msg target)
-		    (mu4e-action-retag-message msg (concat "+" target)))))
+                    (mu4e-action-retag-message msg (concat "+" target)))))
 @end lisp
 
 As another example, suppose we would like to ``archive and mark read''
@@ -2512,10 +2688,10 @@ loading @t{mu4e}):
      :prompt     "Archive"
      :show-target (lambda (target) "archive")
      :action      (lambda (docid msg target)
-		    ;; must come before proc-move since retag runs
+                    ;; must come before proc-move since retag runs
-		    ;; 'sed' on the file
+                    ;; 'sed' on the file
-		    (mu4e-action-retag-message msg "-\\Inbox")
+                    (mu4e-action-retag-message msg "-\\Inbox")
-		    (mu4e~proc-move docid nil "+S-u-N"))))
+                    (mu4e~proc-move docid nil "+S-u-N"))))
 @end lisp
 
 Adding to @code{mu4e-marks} list allows to use the mark in bulk operations
@@ -2616,9 +2792,10 @@ following options:
 things out the context by itself (through the match-function). This is a
 good policy if there are no match functions, or if the match functions
 don't cover all cases.
-@item a symbol @code{ask-if-none}: if there's already a context, don't change it; otherwise,
+@item a symbol @code{ask-if-none}: if there's already a context, don't change it;
-ask the user.
+otherwise, ask the user.
-@item a symbol @code{pick-first}: pick the first (default) context. This is a good choice if
+@item a symbol @code{pick-first}: pick the first (default) context. This is a
+good choice if
 you want to specify context for special case, and fall back to the first
 one if none match.
 @item @code{nil}: don't change the context; this is useful if you don't change
@@ -2666,48 +2843,48 @@ when starting; see the discussion in the previous section.
 
  (setq mu4e-contexts
     `( ,(make-mu4e-context
-	  :name "Private"
+          :name "Private"
-	  :enter-func (lambda () (mu4e-message "Entering Private context"))
+          :enter-func (lambda () (mu4e-message "Entering Private context"))
           :leave-func (lambda () (mu4e-message "Leaving Private context"))
-	  ;; we match based on the contact-fields of the message
+          ;; we match based on the contact-fields of the message
-	  :match-func (lambda (msg)
+          :match-func (lambda (msg)
-			(when msg
+                        (when msg
-			  (mu4e-message-contact-field-matches msg
+                          (mu4e-message-contact-field-matches msg
-			    :to "aliced@@home.example.com")))
+                            :to "aliced@@home.example.com")))
-	  :vars '( ( user-mail-address	    . "aliced@@home.example.com"  )
+          :vars '( ( user-mail-address	    . "aliced@@home.example.com"  )
-		   ( user-full-name	    . "Alice Derleth" )
+                   ( user-full-name	    . "Alice Derleth" )
-		   ( mu4e-compose-signature .
+                   ( mu4e-compose-signature .
-		     (concat
+                     (concat
-		       "Alice Derleth\n"
+                       "Alice Derleth\n"
-		       "Lauttasaari, Finland\n"))))
+                       "Lauttasaari, Finland\n"))))
        ,(make-mu4e-context
-	  :name "Work"
+          :name "Work"
-	  :enter-func (lambda () (mu4e-message "Switch to the Work context"))
+          :enter-func (lambda () (mu4e-message "Switch to the Work context"))
-	  ;; no leave-func
+          ;; no leave-func
-	  ;; we match based on the maildir of the message
+          ;; we match based on the maildir of the message
-	  ;; this matches maildir /Arkham and its sub-directories
+          ;; this matches maildir /Arkham and its sub-directories
-	  :match-func (lambda (msg)
+          :match-func (lambda (msg)
-			(when msg
+                        (when msg
-			  (string-match-p "^/Arkham" (mu4e-message-field msg :maildir))))
+                          (string-match-p "^/Arkham" (mu4e-message-field msg :maildir))))
-	  :vars '( ( user-mail-address	     . "aderleth@@miskatonic.example.com" )
+          :vars '( ( user-mail-address	     . "aderleth@@miskatonic.example.com" )
-		   ( user-full-name	     . "Alice Derleth" )
+                   ( user-full-name	     . "Alice Derleth" )
-		   ( mu4e-compose-signature  .
+                   ( mu4e-compose-signature  .
-		     (concat
+                     (concat
-		       "Prof. Alice Derleth\n"
+                       "Prof. Alice Derleth\n"
-		       "Miskatonic University, Dept. of Occult Sciences\n"))))
+                       "Miskatonic University, Dept. of Occult Sciences\n"))))
 
        ,(make-mu4e-context
-	  :name "Cycling"
+          :name "Cycling"
-	  :enter-func (lambda () (mu4e-message "Switch to the Cycling context"))
+          :enter-func (lambda () (mu4e-message "Switch to the Cycling context"))
-	  ;; no leave-func
+          ;; no leave-func
-	  ;; we match based on the maildir of the message; assume all
+          ;; we match based on the maildir of the message; assume all
-	  ;; cycling-related messages go into the /cycling maildir
+          ;; cycling-related messages go into the /cycling maildir
-	  :match-func (lambda (msg)
+          :match-func (lambda (msg)
-			(when msg
+                        (when msg
-			  (string= (mu4e-message-field msg :maildir) "/cycling")))
+                          (string= (mu4e-message-field msg :maildir) "/cycling")))
-	  :vars '( ( user-mail-address	     . "aderleth@@example.com" )
+          :vars '( ( user-mail-address	     . "aderleth@@example.com" )
-		   ( user-full-name	     . "AliceD" )
+                   ( user-full-name	     . "AliceD" )
-		   ( mu4e-compose-signature  . nil)))))
+                   ( mu4e-compose-signature  . nil)))))
 
   ;; set `mu4e-context-policy` and `mu4e-compose-policy` to tweak when mu4e should
   ;; guess or ask the correct context, e.g.
@@ -2797,19 +2974,19 @@ message. An example should clarify this:
     (cond
       ;; messages to the mu mailing list go to the /mu folder
       ((mu4e-message-contact-field-matches msg :to
-	 "mu-discuss@@googlegroups.com")
+         "mu-discuss@@googlegroups.com")
-	"/mu")
+        "/mu")
       ;; messages sent directly to some spefic address me go to /private
       ((mu4e-message-contact-field-matches msg :to "me@@example.com")
-	"/private")
+        "/private")
       ;; messages with football or soccer in the subject go to /football
       ((string-match "football\\|soccer"
-	 (mu4e-message-field msg :subject))
+         (mu4e-message-field msg :subject))
-	"/football")
+        "/football")
       ;; messages sent by me go to the sent folder
       ((mu4e-message-sent-by-me msg
-	 (mu4e-personal-addresses))
+         (mu4e-personal-addresses))
-	mu4e-sent-folder)
+        mu4e-sent-folder)
       ;; everything else goes to /archive
       ;; important to have a catch-all at the end!
       (t  "/archive"))))
@@ -3030,18 +3207,20 @@ There are a number of places where @t{mu4e} lets you plug in your own
 functions:
 @itemize
 @item Custom functions for message headers in the message-view and
-headers-view --- see @ref{HV Custom headers}, @ref{MSGV Custom headers}
+headers-view --- see @ref{HV Custom headers}, @ref{OMSGV Custom headers}
 @item Using message-specific folders for drafts, trash, sent messages and
 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{Headers view actions}
-@item Apply a function to a message in the message view --- see @ref{Message 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{Attachment actions}
-@item Custom function to mark certain messages --- see @ref{Custom mark functions}
+@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})
 @end itemize
@@ -3126,7 +3305,7 @@ point. Requires the 'formail' tool from procmail."
   (replace-regexp-in-string "\n$" ""
     (shell-command-to-string
       (concat "formail -x " hdr " -c < "
-	(shell-quote-argument (mu4e-message-field-at-point :path))))))
+        (shell-quote-argument (mu4e-message-field-at-point :path))))))
 @end lisp
 
 @subsection Rewriting the message body
@@ -3579,10 +3758,10 @@ well; so put in your configuration:
   (let (buffers)
     (save-current-buffer
       (dolist (buffer (buffer-list t))
-	(set-buffer buffer)
+        (set-buffer buffer)
-	(when (and (derived-mode-p 'message-mode)
+        (when (and (derived-mode-p 'message-mode)
-		(null message-sent-message-via))
+                (null message-sent-message-via))
-	  (push (buffer-name buffer) buffers))))
+          (push (buffer-name buffer) buffers))))
     (nreverse buffers)))
 
 (setq gnus-dired-mail-mode 'mu4e-user-agent)
@@ -4396,7 +4575,7 @@ understand the latter as it is the case for Google or Github), use
 uncheck the box @t{format=flowed} in the @t{Text} menu when composing a
 message.
 
-@subsection How can force images to be shown at the end of my messages, regardless of where I insert them?
+@subsection How can I 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)