man: add mu mfind manpage

1 files changed, 390 insertions, 0 deletions

diff --git a/man/mu-mfind.1 b/man/mu-mfind.1
new file mode 100644
index 0000000..c1166d0
--- /dev/null
+++ b/man/mu-mfind.1
@@ -0,0 +1,390 @@
+.TH MU FIND 1 "19 April 2015" "User Manuals"
+
+.SH NAME
+
+mu find \- find e-mail messages in the \fBmu\fR database.
+
+mu mfind \- find e-mail messages in the \fBmu\fR database with mu4e defaults.
+
+.SH SYNOPSIS
+
+.B mu find [options] <search expression>
+
+.SH DESCRIPTION
+
+\fBmu find\fR is the \fBmu\fR command for searching e-mail message
+that were stored earlier using \fBmu index\fR(1).
+
+\fBmu mfind\fR is a version of \fBmu find\fR that defaults to
+\f--include-related\fR and \fB--skip-dups\fR, just like \fBmu4e\fR does.
+
+.SH SEARCHING MAIL
+
+\fBmu find\fR starts a search for messages in the database that match
+some search pattern. The search patterns are described in detail in
+.BR mu-query (7).
+.
+
+For example:
+
+.nf
+   $ mu find subject:snow and date:2017..
+.fi
+
+would find all messages in 2017 with 'snow' in the subject field, e.g:
+
+.nf
+  2009-03-05 17:57:33 EET Lucia  <lucia@example.com> running in the snow
+  2009-03-05 18:38:24 EET Marius <marius@foobar.com> Re: running in the snow
+.fi
+
+Note, this the default, plain-text output, which is the default, so you don't
+have to use \fB--format=plain\fR. For other types of output (such as symlinks,
+XML or s-expressions), see the discussion in the \fBOPTIONS\fR-section
+below about \fB--format\fR.
+
+The search pattern is taken as a command-line parameter. If the search
+parameter consists of multiple parts (as in the example) they are
+treated as if there were a logical \fBand\fR between them.
+
+For details on the possible queries, see
+
+
+
+.SH OPTIONS
+
+Note, some of the important options are described in the \fBmu\fR(1) man-page
+and not here, as they apply to multiple mu-commands.
+
+The \fBfind\fR-command has various options that influence the way \fBmu\fR
+displays the results. If you don't specify anything, the defaults are
+\fI\-\-fields="d f s"\fR, \fI\-\-sortfield=date\fR and \fI\-\-reverse\fR.
+
+.TP
+\fB\-f\fR, \fB\-\-fields\fR=\fI<fields>\fR
+specifies a string that determines which fields are shown in the output. This
+string consists of a number of characters (such as 's' for subject or 'f' for
+from), which will replace with the actual field in the output. Fields that are
+not known will be output as-is, allowing for some simple formatting.
+
+For example:
+
+.nf
+  $ mu find subject:snow --fields "d f s"
+.fi
+
+would list the date, subject and sender of all messages with 'snow' in the
+their subject.
+
+The table of replacement characters is superset of the list mentions for
+search parameters; the complete list:
+
+.nf
+	t	\fBt\fRo: recipient
+	c	\fBc\fRc: (carbon-copy) recipient
+	h	Bcc: (blind carbon-copy, \fBh\fRidden) recipient
+	d	Sent \fBd\fRate of the message
+	f	Message sender (\fBf\fRrom:)
+	g	Message flags (fla\fBg\fRs)
+	l	Full path to the message (\fBl\fRocation)
+	p	Message \fBp\fRriority (high, normal, low)
+	s	Message \fBs\fRubject
+	i	Message-\fBi\fRd
+	m	\fBm\fRaildir
+	v       Mailing-list Id
+.fi
+
+
+The message flags are described in \fBmu-query\fR(7). As an example, a
+message which is 'seen', has an attachment and is signed would
+have 'asz' as its corresponding output string, while an encrypted new
+message would have 'nx'.
+
+.TP
+\fB\-s\fR, \fB\-\-sortfield\fR \fR=\fI<field>\fR and \fB\-z\fR,
+\fB\-\-reverse\fR specifies the field to sort the search results by, and the
+direction (i.e., 'reverse' means that the sort should be reverted - Z-A). The
+following fields are supported:
+
+.nf
+	cc,c            Cc (carbon-copy) recipient(s)
+	bcc,h           Bcc (blind-carbon-copy) recipient(s)
+	date,d          Message sent date
+	from,f          Message sender
+	maildir,m       Maildir
+	msgid,i         Message id
+	prio,p          Nessage priority
+	subject,s       Message subject
+	to,t            To:-recipient(s)
+	list,v          Mailing-list id
+.fi
+
+Thus, for example, to sort messages by date, you could specify:
+
+.nf
+  $ mu find fahrrad --fields "d f s" --sortfield=date --reverse
+.fi
+
+Note, if you specify a sortfield, by default, messages are sorted in reverse
+(descending) order (e.g., from lowest to highest). This is usually a good
+choice, but for dates it may be more useful to sort in the opposite direction.
+
+.TP
+\fB\-n\fR, \fB\-\-maxnum=<number>\fR
+If > 0, display maximally that number of entries.  If not specified, all matching entries are displayed.
+
+.TP
+\fB\-\-summary-len=<number>\fR
+If > 0, use that number of lines of the message to provide a summary.
+
+.TP
+\fB\-\-format\fR=\fIplain|links|xquery|xml|sexp\fR
+output results in the specified format.
+
+The default is \fBplain\fR, i.e normal output with one line per message.
+
+\fBlinks\fR outputs the results as a maildir with symbolic links to the found
+messages. This enables easy integration with mail-clients (see below for more
+information).
+
+\fBxml\fR formats the search results as XML.
+
+\fBsexp\fR formats the search results as an s-expression as used in Lisp
+programming environments.
+
+\fBxquery\fR shows the Xapian query corresponding to your search terms. This
+is meant for for debugging purposes.
+
+.TP
+\fB\-\-linksdir\fR \fR=\fI<dir>\fR and \fB\-c\fR, \fB\-\-clearlinks\fR
+output the results as a maildir with symbolic links to the found
+messages. This enables easy integration with mail-clients (see below
+for more information). \fBmu\fR will create the maildir if it does not
+exist yet.
+
+If you specify \fB\-\-clearlinks\fR, all existing symlinks will be
+cleared from the target directories; this allows for re-use of the
+same maildir. However, this option will delete any symlink it finds,
+so be careful.
+
+.nf
+  $ mu find grolsch --linksdir=~/Maildir/search --clearlinks
+.fi
+
+will store links to found messages in \fI~/Maildir/search\fR. If the directory
+does not exist yet, it will be created.
+
+Note: when \fBmu\fR creates a Maildir for these links, it automatically
+inserts a \fI.noindex\fR file, to exclude the directory from \fBmu
+index\fR.
+
+.TP
+\fB\-\-after=\fR\fI<timestamp>\fR only show messages whose message files were
+last modified (\fBmtime\fR) after \fI<timestamp>\fR. \fI<timestamp>\fR is a
+UNIX \fBtime_t\fR value, the number of seconds since 1970-01-01 (in UTC).
+
+From the command line, you can use the \fBdate\fR command to get this
+value. For example, only consider messages modified (or created) in the last 5
+minutes, you could specify
+.nf
+  --after=`date +%s --date='5 min ago'`
+.fi
+This is assuming the GNU \fBdate\fR command.
+
+
+.TP
+\fB\-\-exec\fR=\fI<command>\fR
+the \fB\-\-exec\fR command causes the \fIcommand\fR to be executed on each
+matched message; for example, to see the raw text of all messages
+matching 'milkshake', you could use:
+.nf
+  $ mu find milkshake --exec='less'
+.fi
+which is roughly equivalent to:
+.nf
+  $ mu find milkshake --fields="l" | xargs less
+.fi
+
+
+.TP
+\fB\-b\fR, \fB\-\-bookmark\fR=\fI<bookmark>\fR
+use a bookmarked search query. Using this option, a query from your bookmark
+file will be prepended to other search queries. See \fBmu-bookmarks\fR(1) for the
+details of the bookmarks file.
+
+
+.TP
+\fB\-\-skip\-dups\fR,\fB-u\fR whenever there are multiple messages with the
+same name, only show the first one. This is useful if you have copies of the
+same message, which is a common occurrence when using e.g. Gmail together with
+\fBofflineimap\fR.
+
+.TP
+\fB\-\-include\-related\fR,\fB-r\fR also include messages being refered to by
+the matched messages -- i.e.. include messages that are part of the same
+message thread as some matched messages. This is useful if you want
+Gmail-style 'conversations'. Note, finding these related messages make
+searches slower.
+
+.TP
+\fB\-t\fR, \fB\-\-threads\fR show messages in a 'threaded' format -- that is,
+with indentation and arrows showing the conversation threads in the list of
+matching messages.
+
+Messages in the threaded list are indented based on the depth in the
+discussion, and are prefix with a kind of arrow with thread-related
+information about the message, as in the following table:
+
+.nf
+|             | normal | orphan | duplicate |
+|-------------+--------+--------+-----------|
+| first child | `->    | `*>    | `=>       |
+| other       | |->    | |*>    | |=>       |
+.fi
+
+Here, an 'orphan' is a message without a parent message (in the list of
+matches), and a duplicate is a message whose message-id was already seen
+before; not this may not really be the same message, if the message-id was
+copied.
+
+The algorithm used for determining the threads is based on Jamie Zawinksi's
+description:
+.BR http://www.jwz.org/doc/threading.html
+
+
+.SS Integrating mu find with mail clients
+
+.TP
+
+\fBmutt\fR
+
+For \fBmutt\fR you can use the following in your \fImuttrc\fR; pressing the F8
+key will start a search, and F9 will take you to the results.
+
+.nf
+# mutt macros for mu
+macro index <F8> "<shell-escape>mu find --clearlinks --format=links --linksdir=~/Maildir/search " \\
+					"mu find"
+macro index <F9> "<change-folder-readonly>~/Maildir/search" \\
+					"mu find results"
+.fi
+
+
+.TP
+
+\fBWanderlust\fR
+
+\fBSam B\fR suggested the following on the \fBmu\fR-mailing list. First add
+the following to your Wanderlust configuration file:
+
+.nf
+(require 'elmo-search)
+(elmo-search-register-engine
+    'mu 'local-file
+    :prog "/usr/local/bin/mu" ;; or wherever you've installed it
+    :args '("find" pattern "--fields" "l") :charset 'utf-8)
+
+(setq elmo-search-default-engine 'mu)
+;; for when you type "g" in folder or summary.
+(setq wl-default-spec "[")
+.fi
+
+Now, you can search using the \fBg\fR key binding; you can also create
+permanent virtual folders when the messages matching some expression by adding
+something like the following to your \fIfolders\fR file.
+
+.nf
+VFolders {
+  [date:today..now]!mu  "Today"
+
+  [size:1m..100m]!mu    "Big"
+
+  [flag:unread]!mu      "Unread"
+}
+.fi
+
+After restarting Wanderlust, the virtual folders should appear.
+
+
+\fBWanderlust (old)\fR
+
+Another way to integrate \fBmu\fR and \fBwanderlust\fR is shown below; the
+aforementioned method is recommended, but if that does not work for some
+reason, the below can be an alternative.
+
+.nf
+(defvar mu-wl-mu-program     "/usr/local/bin/mu")
+(defvar mu-wl-search-folder  "search")
+
+(defun mu-wl-search ()
+  "search for messages with `mu', and jump to the results"
+   (let* ((muexpr (read-string "Find messages matching: "))
+	  (sfldr  (concat elmo-maildir-folder-path "/"
+		    mu-wl-search-folder))
+	  (cmdline (concat mu-wl-mu-program " find "
+		      "--clearlinks --format=links --linksdir='" sfldr "' "
+		     muexpr))
+	  (rv (shell-command cmdline)))
+    (cond
+      ((= rv 0)  (message "Query succeeded"))
+      ((= rv 2)  (message "No matches found"))
+      (t (message "Error running query")))
+  (= rv 0)))
+
+(defun mu-wl-search-and-goto ()
+  "search and jump to the folder with the results"
+  (interactive)
+  (when (mu-wl-search)
+    (wl-summary-goto-folder-subr
+      (concat "." mu-wl-search-folder)
+      'force-update nil nil t)
+    (wl-summary-sort-by-date)))
+
+;; querying both in summary and folder
+(define-key wl-summary-mode-map (kbd "Q") ;; => query
+  '(lambda()(interactive)(mu-wl-search-and-goto)))
+(define-key wl-folder-mode-map (kbd "Q") ;; => query
+  '(lambda()(interactive)(mu-wl-search-and-goto)))
+
+.fi
+
+
+.SH RETURN VALUE
+
+\fBmu find\fR returns 0 upon successful completion; if the search was
+performed, there needs to be a least one match. Anything else leads to a
+non-zero return value, for example:
+
+.nf
+| code | meaning                        |
+|------+--------------------------------|
+|    0 | ok                             |
+|    1 | general error                  |
+|    2 | no matches (for 'mu find')     |
+|    4 | database is corrupted          |
+.fi
+
+
+.SH ENCODING
+
+\fBmu find\fR output is encoded according the locale for \fI--format=plain\fR
+(the default), and UTF-8 for all other formats (\fIsexp\fR,
+\fIxml\fR).
+
+
+.SH BUGS
+
+Please report bugs if you find them:
+.BR https://github.com/djcb/mu/issues
+If you have specific messages which are not matched correctly, please attach
+them (appropriately censored if needed).
+
+.SH AUTHOR
+
+Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
+
+.SH "SEE ALSO"
+
+.BR mu (1),
+.BR mu-index (1),
+.BR mu-query (7)