commands: add :query to create named notmuch dirs

The current :cf command can be used to create folders for arbitrary
notmuch queries. These folders use the query as their namee. In some
cases, though, it's useful to give a more human-readable name. Create a
new :query command to allow doing so.

The :query command accepts an optional -n flag to specify a name. The
remaining arguments are interpreted verbatim as a notmuch query. If no
name is specified, the query itself is used as the name.

For example, to create a new folder with the full thread of the current
message, named by its subject, run the following command:

    :query -n "{{.SubjectBase}}" thread:"{mid:{{.MessageId}}}"

:query could have been implemented as an additional flag to :cf. Giving
a name to the created folder would make the smantics of :cf strange,
though. For example, to create a named query folder, one would use
:cf -n <name> <query>. This syntax feels odd; the name of the folder
seems like it ought to be the positional argument of the change folder
command. Alternatively, the usage could be :cf -q <query> <name>, but
this feels wrong as well: the query, which is provided as a positional
parameter when no name is specified, becomes a flag parameter when a
name is specified. What's more, both of these potential usages add a
notmuch-specific flag to an otherwise general command. Creating a new
command feels cleaner. Perhaps the current query functionality of the
:cf command could eventually be deprecated to remove the duplicate
functionality and keep :cf limited to changing to existing folders.

Changelog-added: Create notmuch named queries with the `:query`
 command.
Signed-off-by: Jason Cox <me@jasoncarloscox.com>
Tested-by: Inwit <inwit@sindominio.net>
Acked-by: Robin Jarry <robin@jarry.cc>

1 files changed, 12 insertions, 0 deletions

diff --git a/doc/aerc.1.scd b/doc/aerc.1.scd
index 91e75d60..2a20213a 100644
--- a/doc/aerc.1.scd
+++ b/doc/aerc.1.scd
@@ -596,6 +596,18 @@ message list, the message in the message viewer, etc).
 *:prev-result*
 	Selects the next or previous search result.
 
+*:query* [*-a* _<account>_] [*-n* _name_] _<notmuch query>_
+	Create a virtual folder using the specified top-level notmuch query. This
+	command is exclusive to the notmuch backend.
+
+	*-a* _<account>_
+		Change to _<folder>_ of _<account>_ and focus its corresponding
+		tab.
+
+	*-n* _<name>_
+		Specify the display name for the virtual folder. If not provided,
+		_<notmuch query>_ is used as the display name.
+
 *:search* [_<options>_] _<terms>_...
 	Searches the current folder for messages matching the given set of
 	conditions.  The search syntax is dependent on the underlying backend.