mu: add fields/flags commands

Useful information for devising queries.

Directly generated from the source. Add manpages, too.

6 files changed, 95 insertions, 29 deletions

diff --git a/man/Makefile.am b/man/Makefile.am
index e055600..163c75f 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -22,7 +22,9 @@ dist_man_MANS =		\
 	mu-cfind.1	\
 	mu-easy.1	\
 	mu-extract.1	\
+	mu-fields.1     \
 	mu-find.1	\
+	mu-flags.1	\
 	mu-help.1	\
 	mu-index.1	\
 	mu-info.1	\
diff --git a/man/meson.build b/man/meson.build
index 4d7075e..6236e1f 100644
--- a/man/meson.build
+++ b/man/meson.build
@@ -21,7 +21,9 @@ install_man(
    'mu-cfind.1',
    'mu-easy.1',
    'mu-extract.1',
+   'mu-fields.1',
    'mu-find.1',
+   'mu-flags.1',
    'mu-help.1',
    'mu-index.1',
    'mu-info.1',
diff --git a/man/mu-fields.1 b/man/mu-fields.1
new file mode 100644
index 0000000..e86c22a
--- /dev/null
+++ b/man/mu-fields.1
@@ -0,0 +1,32 @@
+.TH MU FIELDS 1 "April 2022" "User Manuals"
+
+.SH NAME
+
+mu fields\-  list all message fields
+
+.SH SYNOPSIS
+
+.B mu fields [options]
+
+.SH DESCRIPTION
+
+\fBmu fields\fR is the \fBmu\fR command for showing a table of message fields
+and their properties.
+
+.SH OPTIONS
+
+Inherits common options from
+.BR mu(1)
+
+.SH BUGS
+
+Please report bugs if you find them:
+.BR https://github.com/djcb/mu/issues
+
+.SH AUTHOR
+
+Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
+
+.SH "SEE ALSO"
+
+.BR mu (1)
diff --git a/man/mu-find.1 b/man/mu-find.1
index 65ee448..ca64d3e 100644
--- a/man/mu-find.1
+++ b/man/mu-find.1
@@ -1,4 +1,4 @@
-.TH MU FIND 1 "29 January 2022" "User Manuals"
+.TH MU FIND 1 "29 April 2022" "User Manuals"
 
 .SH NAME
 
@@ -23,10 +23,10 @@ some search pattern. The search patterns are described in detail in
 For example:
 
 .nf
-   $ mu find subject:snow and date:2017..
+   $ mu find subject:snow and date:2009..
 .fi
 
-would find all messages in 2017 with 'snow' in the subject field, e.g:
+would find all messages in 2009 with 'snow' in the subject field, e.g:
 
 .nf
   2009-03-05 17:57:33 EET Lucia  <lucia@example.com> running in the snow
@@ -71,23 +71,20 @@ 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:
-
+search parameters, such as:
 .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
 
+For the complete, up-to-date list, see:
+.BR mu-fields(1)
 
 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
@@ -97,12 +94,10 @@ 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:
+direction (i.e., 'reverse' means that the sort should be reverted - Z-A). Examples include:
 
 .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
@@ -110,9 +105,11 @@ following fields are supported:
 	prio,p          Nessage priority
 	subject,s       Message subject
 	to,t            To:-recipient(s)
-	list,v          Mailing-list id
 .fi
 
+For the complete, up-to-date list, see:
+.BR mu-fields(1)
+
 Thus, for example, to sort messages by date, you could specify:
 
 .nf
@@ -338,3 +335,4 @@ Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
 .BR mu (1),
 .BR mu-index (1),
 .BR mu-query (7)
+.BR mu-fields (1)
diff --git a/man/mu-flags.1 b/man/mu-flags.1
new file mode 100644
index 0000000..7ba9e7b
--- /dev/null
+++ b/man/mu-flags.1
@@ -0,0 +1,31 @@
+.TH MU FLAGS 1 "April 2022" "User Manuals"
+
+.SH NAME
+
+mu flags\-  list all message flags
+
+.SH SYNOPSIS
+
+.B mu flags [options]
+
+.SH DESCRIPTION
+
+\fBmu flags\fR is the \fBmu\fR command for showing a table of message flags and their properties, which is useful for devising queries.
+
+.SH OPTIONS
+
+Inherits common options from
+.BR mu(1)
+
+.SH BUGS
+
+Please report bugs if you find them:
+.BR https://github.com/djcb/mu/issues
+
+.SH AUTHOR
+
+Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
+
+.SH "SEE ALSO"
+
+.BR mu (1)
diff --git a/man/mu-query.7 b/man/mu-query.7
index 7e42e23..e00891b 100644
--- a/man/mu-query.7
+++ b/man/mu-query.7
@@ -1,25 +1,24 @@
-.TH MU QUERY 7 "28 December 2017" "User Manuals"
+.TH MU QUERY 7 "22 April 2022" "User Manuals"
 
 .SH NAME
 
-mu query language \- a language for finding messages in \fBmu\fR
-databases.
+mu query language \- a language for finding messages in \fBmu\fR databases.
 
 .SH DESCRIPTION
 
-The mu query language is a language used by \fBmu find\fR and
-\fBmu4e\fR to find messages in \fBmu\fR's Xapian databases. The
-language is quite similar to Xapian's default query-parser, but is an
-independent implementation that is customized for the mu/mu4e
-use-case.
+The mu query language is a language used by \fBmu find\fR and \fBmu4e\fR to find
+messages in \fBmu\fR's Xapian databases. The language is quite similar to
+Xapian's default query-parser, but is an independent implementation that is
+customized for the mu/mu4e use-case.
 
-In this article, we give a structured but informal overview of the
-query language and provide examples.
+In this article, we give a structured but informal overview of the query
+language and provide examples.
 
-\fBNOTE:\fR if you use queries on the command-line (say, for \fBmu
-find\fR), you need to quote any characters that would otherwise be
-interpreted by the shell, such as \fB""\fR, \fB(\fR and \fB)\fR and
-whitespace.
+As a companion to this, we recommend the \fBmu fields\fR command to get an up-to-date list of the available fields.
+
+\fBNOTE:\fR if you use queries on the command-line (say, for \fBmu find\fR), you
+need to quote any characters that would otherwise be interpreted by the shell,
+such as \fB""\fR, \fB(\fR and \fB)\fR and whitespace.
 
 .de EX1
 .nf
@@ -132,8 +131,7 @@ take quite a bit longer than 'normal' queries.
 .SH FIELDS
 
 We already saw a number of search fields, such as \fBsubject:\fR and
-\fBbody:\fR. Here is the full table, a shortcut character and a
-description.
+\fBbody:\fR. Here is the full table, a shortcut character and a description.
 .EX1
 	cc,c            Cc (carbon-copy) recipient(s)
 	bcc,h           Bcc (blind-carbon-copy) recipient(s)
@@ -142,6 +140,7 @@ description.
 	subject,s       Message subject
 	body,b          Message body
 	maildir,m       Maildir
+	modified,k      Last modification time
 	msgid,i         Message-ID
 	prio,p          Message priority (\fIlow\fR, \fInormal\fR or \fIhigh\fR)
 	flag,g          Message Flags
@@ -152,6 +151,8 @@ description.
 	mime,y          MIME-type of one or more message parts
 	tag,x           Tags for the message
 	list,v          Mailing list (e.g. the List-Id value)
+
+The \fBmu fields\fR command is recommended to get the latest version.
 .EX2
 The shortcut character can be used instead of the full name:
 .EX1