[PATCH] Clarify the syntax required when searching using timestamps.

[PATCH] Clarify the syntax required when searching using timestamps.

[Matthew Lear]

Need to be clearer about specifying time ranges using timestamps.
Legacy syntax which predates the date prefix is still supported, but
timestamps used in conjunction with the date prefix require additional
syntax.
---
 doc/man7/notmuch-search-terms.rst | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/doc/man7/notmuch-search-terms.rst b/doc/man7/notmuch-search-terms.rst
index 6d2bf62a..b4d784a3 100644
--- a/doc/man7/notmuch-search-terms.rst
+++ b/doc/man7/notmuch-search-terms.rst
@@ -121,13 +121,14 @@ date:<since>..<until> or date:<date>
     expression, and supported syntax for <since> and <until> date and
     time expressions.
 
-    The time range can also be specified using timestamps with a
-    syntax of:
+    The time range can also be specified using timestamps without
+    including the date prefix using a syntax of:
 
     <initial-timestamp>..<final-timestamp>
 
     Each timestamp is a number representing the number of seconds
-    since 1970-01-01 00:00:00 UTC.
+    since 1970-01-01 00:00:00 UTC. Specifying a time range this way
+    is considered legacy and predates the date prefix.
 
 lastmod:<initial-revision>..<final-revision>
     The **lastmod:** prefix can be used to restrict the result by the
@@ -296,6 +297,13 @@ In this case, <since> is taken as the earliest time it could describe
 could describe (the end of yesterday). Similarly, date:january..february
 matches from the beginning of January to the end of February.
 
+If specifying a time range using timestamps in conjunction with the
+date prefix, each timestamp must be preceded by @ (ASCII hex 40). As
+above, each timestamp is a number representing the number of seconds
+since 1970-01-01 00:00:00 UTC. For example:
+
+    date:@<initial-timestamp>..@<final-timestamp>
+
 date:<expr>..! can be used as a shorthand for date:<expr>..<expr>. The
 expansion takes place before interpretation, and thus, for example,
 date:monday..! matches from the beginning of Monday until the end of
-- 
2.14.1

Re: [PATCH] Clarify the syntax required when searching using timestamps.

[David Bremner]

Matthew Lear <matt@bubblegen.co.uk> writes:

> Need to be clearer about specifying time ranges using timestamps.
> Legacy syntax which predates the date prefix is still supported, but
> timestamps used in conjunction with the date prefix require additional
> syntax.

Pushed to master. Thanks for working to the documentation.

d