man: document the date:since..until range queries

diff --git a/man/man7/notmuch-search-terms.7 b/man/man7/notmuch-search-terms.7
index 17a109ec11935d9fdf4ed7c7cb74dd56b5012a4a..e39b944047a04ca6dd3d8e341709372dcaac0206 100644 (file)
--- a/man/man7/notmuch-search-terms.7
+++ b/man/man7/notmuch-search-terms.7
@@ -54,6 +54,8 @@ terms to match against specific portions of an email, (where
 
        folder:<directory-path>
 
 
        folder:<directory-path>
 

+       date:<since>..<until>
+

 The
 .B from:
 prefix is used to match the name or address of the sender of an email
 The
 .B from:
 prefix is used to match the name or address of the sender of an email


@@ -104,6 +106,26 @@ contained within particular directories within the mail store. Only
 the directory components below the top-level mail database path are
 available to be searched.
 
 the directory components below the top-level mail database path are
 available to be searched.
 

+The
+.B date:
+prefix can be used to restrict the results to only messages within a
+particular time range (based on the Date: header) with a range syntax
+of:
+
+       date:<since>..<until>
+
+See \fBDATE AND TIME SEARCH\fR below for details on the range
+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:
+
+       <initial-timestamp>..<final-timestamp>
+
+Each timestamp is a number representing the number of seconds since
+1970\-01\-01 00:00:00 UTC.
+

 In addition to individual terms, multiple terms can be
 combined with Boolean operators (
 .BR and ", " or ", " not
 In addition to individual terms, multiple terms can be
 combined with Boolean operators (
 .BR and ", " or ", " not


@@ -117,20 +139,124 @@ operators, but will have to be protected from interpretation by the
 shell, (such as by putting quotation marks around any parenthesized
 expression).
 
 shell, (such as by putting quotation marks around any parenthesized
 expression).
 

-Finally, results can be restricted to only messages within a
-particular time range, (based on the Date: header) with a syntax of:
+.SH DATE AND TIME SEARCH

 
 

-       <initial-timestamp>..<final-timestamp>
+notmuch understands a variety of standard and natural ways of
+expressing dates and times, both in absolute terms ("2012-10-24") and
+in relative terms ("yesterday"). Any number of relative terms can be
+combined ("1 hour 25 minutes") and an absolute date/time can be
+combined with relative terms to further adjust it. A non-exhaustive
+description of the syntax supported for absolute and relative terms is
+given below.

 
 

-Each timestamp is a number representing the number of seconds since
-1970\-01\-01 00:00:00 UTC. This is not the most convenient means of
-expressing date ranges, but until notmuch is fixed to accept a more
-convenient form, one can use the date program to construct
-timestamps. For example, with the bash shell the following syntax would
-specify a date range to return messages from 2009\-10\-01 until the
-current time:
-
-       $(date +%s \-d 2009\-10\-01)..$(date +%s)
+.RS 4
+.TP 4
+.B The range expression
+
+date:<since>..<until>
+
+The above expression restricts the results to only messages from
+<since> to <until>, based on the Date: header.
+
+<since> and <until> can describe imprecise times, such as "yesterday".
+In this case, <since> is taken as the earliest time it could describe
+(the beginning of yesterday) and <until> is taken as the latest time
+it could describe (the end of yesterday). Similarly,
+date:january..february matches from the beginning of January to the
+end of February.
+
+Currently, we do not support spaces in range expressions. You can
+replace the spaces with '_', or (in most cases) '-', or (in some
+cases) leave the spaces out altogether. Examples in this man page use
+spaces for clarity.
+
+Open-ended ranges are supported (since Xapian 1.2.1), i.e. it's
+possible to specify date:..<until> or date:<since>.. to not limit the
+start or end time, respectively. Pre-1.2.1 Xapian does not report an
+error on open ended ranges, but it does not work as expected either.
+
+Entering date:expr without ".." (for example date:yesterday) won't
+work, as it's not interpreted as a range expression at all. You can
+achieve the expected result by duplicating the expr both sides of ".."
+(for example date:yesterday..yesterday).
+.RE
+
+.RS 4
+.TP 4
+.B Relative date and time
+[N|number] (years|months|weeks|days|hours|hrs|minutes|mins|seconds|secs) [...]
+
+All refer to past, can be repeated and will be accumulated.
+
+Units can be abbreviated to any length, with the otherwise ambiguous
+single m being m for minutes and M for months.
+
+Number can also be written out one, two, ..., ten, dozen,
+hundred. Additionally, the unit may be preceded by "last" or "this"
+(e.g., "last week" or "this month").
+
+When combined with absolute date and time, the relative date and time
+specification will be relative from the specified absolute date and
+time.
+
+Examples: 5M2d, two weeks
+.RE
+
+.RS 4
+.TP 4
+.B Supported absolute time formats
+H[H]:MM[:SS] [(am|a.m.|pm|p.m.)]
+
+H[H] (am|a.m.|pm|p.m.)
+
+HHMMSS
+
+now
+
+noon
+
+midnight
+
+Examples: 17:05, 5pm
+.RE
+
+.RS 4
+.TP 4
+.B Supported absolute date formats
+YYYY-MM[-DD]
+
+DD-MM[-[YY]YY]
+
+MM-YYYY
+
+M[M]/D[D][/[YY]YY]
+
+M[M]/YYYY
+
+D[D].M[M][.[YY]YY]
+
+D[D][(st|nd|rd|th)] Mon[thname] [YYYY]
+
+Mon[thname] D[D][(st|nd|rd|th)] [YYYY]
+
+Wee[kday]
+
+Month names can be abbreviated at three or more characters.
+
+Weekday names can be abbreviated at three or more characters.
+
+Examples: 2012-07-31, 31-07-2012, 7/31/2012, August 3
+.RE
+
+.RS 4
+.TP 4
+.B Time zones
+(+|-)HH:MM
+
+(+|-)HH[MM]
+
+Some time zone codes, e.g. UTC, EET.
+.RE

 
 .SH SEE ALSO
 
 
 .SH SEE ALSO