Many thanks, I'll incorporate most of your suggestions as-is. BR, Jani. On Thu, 25 Oct 2012, Austin Clements <amdragon@MIT.EDU> wrote: > Quoth Jani Nikula on Oct 22 at 12:22 am: >> --- >> man/man7/notmuch-search-terms.7 | 147 +++++++++++++++++++++++++++++++++++---- >> 1 file changed, 135 insertions(+), 12 deletions(-) >> >> diff --git a/man/man7/notmuch-search-terms.7 b/man/man7/notmuch-search-terms.7 >> index 17a109e..fbd3ee7 100644 >> --- 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> >> >> + date:<since>..<until> >> + >> 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 >> +.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 >> @@ -117,20 +139,121 @@ operators, but will have to be protected from interpretation by the >> 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> >> +This is a non-exhaustive description of the date and time search with >> +some pseudo notation. Most of the constructs can be mixed freely, and >> +in any order, but the same absolute date or time can't be expressed >> +twice. > > I'm not sure what the end of this sentence means, though I assume it's > related to the restrictions on repeated absolute components. It would > also be nice to give a broader view of the syntax here. Maybe, > > 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. >> + >> +If <since> or <until> describes time at an accuracy of days or less, >> +the date/time is rounded, towards past for <since> and towards future >> +for <until>, to be inclusive. For example, date:january..february > > The accuracy doesn't seem to have have anything to do with days; if I > say "date:1hour..1hour" I get a span of an hour. Describing it as > rounding also seems like it could be confusing to someone who hasn't > thought a lot about this (though, as someone who has though a lot > about this, I could be wrong). What about something like, > > <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. > >> +matches from the beginning of January until the end of >> +February. Similarly, date:yesterday..yesterday matches from the >> +beginning of yesterday until the end of yesterday. >> + >> +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. Unfortunately, pre-1.2.1 Xapian does > > No need for the "Unfortunately". > >> +not report an error on open ended ranges, but it does not work as >> +expected either. >> + >> +Xapian does not support spaces in range expressions. You can replace > > The man pages essentially don't reference Xapian and the fact that we > use Xapian is transparent to the uninterested user. Maybe just > "Currently, we do not support spaces ..."? Or "Due to technical > limitations, we do not currently support spaces ..." if you want to > convey that we feel the user's pain but it's actually hard to fix. > >> +the spaces with '_', or (in most cases) '-', or (in some cases) leave >> +the spaces out altogether. > > Maybe add "Examples in this man page use spaces for clarity."? It's > unfortunate that this rather critical piece of information is buried > in the middle of a subsection of the man page. I wonder if it should > at least go before the previous paragraph? We are going to get so > many people asking why their date searches don't work... > >> + >> +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 multiplier can also be written out one, two, ..., ten, dozen, > > This is the only use of "multiplier". I think it would be fine to > just say "the number". > >> +hundred. As special cases last means one ("last week") and this means >> +zero ("this month"). > > Maybe, "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 time formats > > 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 date formats > > 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 >>