[PATCH v5 8/9] man: document the date:since..until range queries

[Jani Nikula]

Many thanks, I'll incorporate most of your suggestions as-is.

BR,
Jani.


On Thu, 25 Oct 2012, Austin Clements <amdragon at 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
>>