* mu4e: update documentation on queries / bookmarks as bit

2 files changed, 85 insertions, 35 deletions

diff --git a/mu4e/mu4e-vars.el b/mu4e/mu4e-vars.el
index f648563..a49df92 100644
--- a/mu4e/mu4e-vars.el
+++ b/mu4e/mu4e-vars.el
@@ -302,14 +302,16 @@ re-edited, and is nil otherwise."
 
 (defcustom mu4e-maildir-shortcuts nil
   "A list of maildir shortcuts.
-This enables quickly going to the particular for, or quickly
-moving messages towards them (i.e., archiving or refiling). The
+This enables quickly going to the particular maildir (folder), or
+quickly moving messages to them (i.e., archiving or refiling). The
 list contains elements of the form (maildir . shortcut), where
-MAILDIR is a maildir (such as \"/archive/\"), and shortcut a
-single shortcut character. With this, in the header buffer and
-view buffer you can execute `mu4e-mark-for-move-quick' (or 'm',
-by default) or `mu4e-jump-to-maildir' (or 'j', by default),
-followed by the designated shortcut character for the maildir."
+MAILDIR is a maildir (such as \"/archive/\"), and shortcut a single
+shortcut character. With this, in the header buffer and view buffer
+you can execute `mu4e-mark-for-move-quick' (or 'm', by default) or
+`mu4e-jump-to-maildir' (or 'j', by default), followed by the
+designated shortcut character for the maildir. Unlike in search
+queries, folder names with spaces in them must NOT be quoted, since
+mu4e does this automatically for you."
   :type '(repeat (cons (string :tag "Maildir") character))
   :group 'mu4e-folders)
 
diff --git a/mu4e/mu4e.texi b/mu4e/mu4e.texi
index 3a10ad6..b590251 100644
--- a/mu4e/mu4e.texi
+++ b/mu4e/mu4e.texi
@@ -1489,7 +1489,7 @@ configuration:
 
 @t{mu4e} is fully search-based: even if you 'jump to a folder', you are
 executing a query for messages that happen to have the property of being in a
-certain folder.
+certain folder (maildir).
 
 Normally, queries return up to @code{mu4e-headers-results-limit} (default:
 500) results. That is usually more than enough, and makes things significantly
@@ -1515,68 +1515,112 @@ see @ref{Sort order and threading}.
 understands@footnote{with the caveat that command-line queries are subject to
 the shell's interpretation before @t{mu} sees them}. Let's look at some
 examples here, please refer to the @code{mu-find} and @code{mu-easy} man pages
-for details and even more examples.
+for details and more examples.
 
+@itemize
+
+@item Get all messages regarding @emph{bananas}:
 @verbatim
-# get all messages regarding bananas:
 bananas
+@end verbatim
 
-# get all messages regarding bananas from John with an attachment:
+@item Get all messages regarding @emph{bananas} from @emph{John} with an attachment:
+@verbatim
 from:john flag:attach bananas
+@end verbatim
 
-# get all messages with subject wombat in June 2009
+@item Get all messages with subject @emph{wombat} in June 2009
+@verbatim
 subject:wombat date:20090601..20090630
+@end verbatim
 
-# get all messages with PDF attachments in the /projects folder
+@item Get all messages with PDF attachments in the @t{/projects} folder
+@verbatim
 maildir:/projects mime:application/pdf
+@end verbatim
 
-# get all messages about Rupert in the Sent Items folder
+@item Get all messages about @emph{Rupert} in the @t{/Sent Items} folder. Note that
+maildirs with spaces must be quoted.
+@verbatim
 maildir:"/Sent Items" rupert
-# note: terms with spaces need quoting
+@end verbatim
 
-# get all important messages which are signed:
+@item Get all important messages which are signed:
+@verbatim
 flag:signed prio:high
+@end verbatim
 
-# get all messages from Jim without an attachment:
+@item Get all messages from @emph{Jim} without an attachment:
+@verbatim
 from:jim AND NOT flag:attach
+@end verbatim
 
-# get all message with Alice in one of the contacts fields (to, from, cc,
-# bcc):
+@item Get all messages with Alice in one of the contacts-fields (@t{to}, @t{from},
+@t{cc}, @t{bcc}):
+@verbatim
 contact:alice
+@end verbatim
 
-# get all unread messages where the subject mentions Angstrom:
-# (search is case-insensitive and accent-insensitive)
-subject:angstrom flag:unread
+@item Get all unread messages where the subject mentions Ångström: (search is
+case-insensitive and accent-insensitive, so this matches Ångström, angstrom,
+aNGstrøM, ...)
+@verbatim
+subject:Ångström flag:unread
+@end verbatim
 
-# get all unread messages between Mar-2002 and Aug-2003 about some bird:
+@item Get all unread messages between Mar-2002 and Aug-2003 about some bird:
+@verbatim
 date:20020301..20030831 nightingale flag:unread
+@end verbatim
 
-# get today's messages:
+@item Get today's messages:
+@verbatim
 date:today..now
+@end verbatim
+or, unless you have a really old Xapian
+@verbatim
+date:today
+@end verbatim
 
-# get all messages we got in the last two weeks regarding emacs:
+@item Get all messages we got in the last two weeks regarding @emph{emacs}:
+@verbatim
 date:2w..now emacs
+@end verbatim
+or, unless you have a really old Xapian
+@verbatim
+date:2w.. emacs
+@end verbatim
 
-# get messages from the the Mu mailing list:
-mu find list:mu-discuss.googlegroups.com
+@item Get messages from the the @emph{Mu} mailing list:
+@verbatim
+list:mu-discuss.googlegroups.com
+@end verbatim
 
-# get messages with a subject soccer, Socrates, society...:
+@item Get messages with a subject soccer, Socrates, society, ...; note that the '*'
+wildcard can only appear as the term's rightmost character:
+@verbatim
 subject:soc*
-# note: the '*' wildcard can only appear as the term's rightmost character
+@end verbatim
 
-# get all mails with attachment with filenames starting with 'pic':
+@item Get all mails with attachments with filenames starting with @emph{pic}; note
+that the '*' wildcard can only appear as the term's rightmost character:
+@verbatim
 file:pic*
-# note: the '*' wildcard can only appear as the term's rightmost character
+@end verbatim
 
-# get all messages with PDF attachments:
+@item Get all messages with PDF-attachments:
+@verbatim
 mime:application/pdf
+@end verbatim
 
-# get all messages with image attachments:
+Get all messages with image attachments, and note that the '*' wildcard can
+only appear as the term's rightmost character:
+@verbatim
 mime:image/*
-# note: the '*' wildcard can only appear as the term's @emph{rightmost}
-# character
 @end verbatim
 
+@end itemize
+
 @node Bookmarks
 @section Bookmarks
 
@@ -1672,6 +1716,10 @@ maildirs (folders) very quickly - for example, getting to the @t{/lists}
 folder only requires you to type @kbd{jl}, then change to @t{/work} with
 @kbd{jw}.
 
+While in queries you need to quote folder names (maildirs) with spaces in
+them, you should @emph{not} quote them when used in
+@code{mu4e-maildir-shortcuts}, since @t{mu4e} does that automatically for you.
+
 The very same shortcuts are used by @kbd{M-x mu4e-mark-for-move} (default
 shortcut @key{m}); so, for example, if you want to move a message the
 @t{/archive} folder, you can do so by typing @kbd{ma}.