From 73f6b8c56ff976bb7a30def3a8d017e1a514af7d Mon Sep 17 00:00:00 2001
From: Jules Maselbas <jmaselbas@zdiv.net>
Date: Thu, 30 May 2024 13:31:00 +0200
Subject: doc: update and rephrase -H header search syntax

The syntax for the -H option's argument was confusing, warning about
requiring the value to be from the header by a space without hinting
that it also expect a single argument: requiring the query to be wrapped
with quotes.

Since 8464b3738 ("search: use a common api for all workers") the parser
and the syntax has changed, now: the query is split around `:` without
needing a space.

Update the man page to reflect this change.

Signed-off-by: Jules Maselbas <jmaselbas@zdiv.net>
Reviewed-by: Tim Culverhouse <tim@timculverhouse.com>
Acked-by: Robin Jarry <robin@jarry.cc>
---
 doc/aerc-search.1.scd | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

(limited to 'doc')

diff --git a/doc/aerc-search.1.scd b/doc/aerc-search.1.scd
index fa630c1d..e6b0be5c 100644
--- a/doc/aerc-search.1.scd
+++ b/doc/aerc-search.1.scd
@@ -8,8 +8,8 @@ aerc-search - search and filter patterns and options for *aerc*(1)
 
 This syntax is common to all backends.
 
-*:filter* [*-ruba*] [*-x* _<flag>_] [*-X* _<flag>_] [*-H* _Header: Value_] [*-f* _<from>_] [*-t* _<to>_] [*-c* _<cc>_] [*-d* _<start[,end]>_] [_<terms>_...]++
-*:search* [*-ruba*] [*-x* _<flag>_] [*-X* _<flag>_] [*-H* _Header: Value_] [*-f* _<from>_] [*-t* _<to>_] [*-c* _<cc>_] [*-d* _<start[,end]>_] [_<terms>_...]
+*:filter* [*-ruba*] [*-x* _<flag>_] [*-X* _<flag>_] [*-H* _<header>:[<value>]_] [*-f* _<from>_] [*-t* _<to>_] [*-c* _<cc>_] [*-d* _<start[,end]>_] [_<terms>_...]++
+*:search* [*-ruba*] [*-x* _<flag>_] [*-X* _<flag>_] [*-H* _<header>:[<value>]_] [*-f* _<from>_] [*-t* _<to>_] [*-c* _<cc>_] [*-d* _<start[,end]>_] [_<terms>_...]
 	Searches the current folder for messages matching the given set of
 	conditions.
 
@@ -37,10 +37,11 @@ This syntax is common to all backends.
 			_Draft_
 				Draft messages
 
-	*-H*: Search in the headers of the messages, for a specific header
-		Syntax: _Header: Value_
-		If the space between _:_ and the value is omitted, aerc will not
-		search for the Header.
+	*-H* _<header>:[<value>]_:
+		Search in the headers of the messages for a specific _<header>_ that matches _<value>_,
+		_<value>_ can be omitted to only search for a the _<header>_.
+		If either the _<header>_ or the _<value>_ contain a space then the whole argument needs
+		to be escaped with quotes, note: spaces around _<value>_ are trimmed.
 
 	*-b*: Search in the body of the messages
 
-- 
cgit