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

[Austin Clements]

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
>