From: Austin Clements Date: Wed, 24 Oct 2012 21:08:41 +0000 (+2000) Subject: Re: [PATCH v5 8/9] man: document the date:since..until range queries X-Git-Url: http://git.tremily.us/gitweb.cgi?a=commitdiff_plain;h=ce250d12cb0116f265919debf62eb16e39206593;p=notmuch-archives.git Re: [PATCH v5 8/9] man: document the date:since..until range queries --- diff --git a/87/2bb2716b7f7535637a82dda6752c85e80749ad b/87/2bb2716b7f7535637a82dda6752c85e80749ad new file mode 100644 index 000000000..e12448260 --- /dev/null +++ b/87/2bb2716b7f7535637a82dda6752c85e80749ad @@ -0,0 +1,315 @@ +Return-Path: +X-Original-To: notmuch@notmuchmail.org +Delivered-To: notmuch@notmuchmail.org +Received: from localhost (localhost [127.0.0.1]) + by olra.theworths.org (Postfix) with ESMTP id 3319B431FAF + for ; Wed, 24 Oct 2012 14:08:46 -0700 (PDT) +X-Virus-Scanned: Debian amavisd-new at olra.theworths.org +X-Spam-Flag: NO +X-Spam-Score: -0.7 +X-Spam-Level: +X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5 + tests=[RCVD_IN_DNSWL_LOW=-0.7] autolearn=disabled +Received: from olra.theworths.org ([127.0.0.1]) + by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024) + with ESMTP id Xoi3nkTZfeKL for ; + Wed, 24 Oct 2012 14:08:45 -0700 (PDT) +Received: from dmz-mailsec-scanner-3.mit.edu (DMZ-MAILSEC-SCANNER-3.MIT.EDU + [18.9.25.14]) + by olra.theworths.org (Postfix) with ESMTP id 32D84431FAE + for ; Wed, 24 Oct 2012 14:08:45 -0700 (PDT) +X-AuditID: 1209190e-b7f756d000000904-9e-508858db5ddf +Received: from mailhub-auth-2.mit.edu ( [18.7.62.36]) + by dmz-mailsec-scanner-3.mit.edu (Symantec Messaging Gateway) with SMTP + id EF.20.02308.BD858805; Wed, 24 Oct 2012 17:08:43 -0400 (EDT) +Received: from outgoing.mit.edu (OUTGOING-AUTH.MIT.EDU [18.7.22.103]) + by mailhub-auth-2.mit.edu (8.13.8/8.9.2) with ESMTP id q9OL8hlk023088; + Wed, 24 Oct 2012 17:08:43 -0400 +Received: from awakening.csail.mit.edu (awakening.csail.mit.edu [18.26.4.91]) + (authenticated bits=0) + (User authenticated as amdragon@ATHENA.MIT.EDU) + by outgoing.mit.edu (8.13.6/8.12.4) with ESMTP id q9OL8fgX029227 + (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NOT); + Wed, 24 Oct 2012 17:08:42 -0400 (EDT) +Received: from amthrax by awakening.csail.mit.edu with local (Exim 4.77) + (envelope-from ) + id 1TR8Bt-0005xj-8m; Wed, 24 Oct 2012 17:08:41 -0400 +Date: Wed, 24 Oct 2012 17:08:41 -0400 +From: Austin Clements +To: Jani Nikula +Subject: Re: [PATCH v5 8/9] man: document the date:since..until range queries +Message-ID: <20121024210841.GU14861@mit.edu> +References: + +MIME-Version: 1.0 +Content-Type: text/plain; charset=us-ascii +Content-Disposition: inline +In-Reply-To: + +User-Agent: Mutt/1.5.21 (2010-09-15) +X-Brightmail-Tracker: + H4sIAAAAAAAAA+NgFupmleLIzCtJLcpLzFFi42IRYrdT0b0d0RFg8PK5uUXTdGeL6zdnMjsw + edy6/5rd49mqW8wBTFFcNimpOZllqUX6dglcGZc+dbIWfLWrOLP0P2sDY6NRFyMnh4SAicTE + ay2MELaYxIV769m6GLk4hAT2MUrs3v2FEcLZwCjx9WcvM0iVkMBJJok/E5Qg7CWMEps+y4HY + LAKqEvv/vWYDsdkENCS27V8ONlVEQFFi88n9YDazgLTEt9/NTF2M7BzCAr4SR2JBorwCOhJH + W1awQkysk/j27jcbRFxQ4uTMJywQnVoSN/69BOrkAJuy/B8HSJhTIEzixIuTYCWiAioSU05u + Y5vAKDQLSfcsJN2zELoXMDKvYpRNya3SzU3MzClOTdYtTk7My0st0jXWy80s0UtNKd3ECApn + Tkm+HYxfDyodYhTgYFTi4T3g0REgxJpYVlyZe4hRkoNJSZTXMBQoxJeUn1KZkVicEV9UmpNa + fIhRgoNZSYR38oP2ACHelMTKqtSifJiUNAeLkjjvlZSb/kIC6YklqdmpqQWpRTBZGQ4OJQle + D2DcCgkWpaanVqRl5pQgpJk4OEGG8wAN1wap4S0uSMwtzkyHyJ9i1OU4+mbuQ0Yhlrz8vFQp + cd6J4UBFAiBFGaV5cHNgaegVozjQW8K8ciCjeIApDG7SK6AlTEBLzHlaQZaUJCKkpBoYN8sK + X73cZ/O+/dMWgxcPqq5KLT7gueViAdP71TzXL2Zx95+Y++fN3T43pfkO081cfNuS/Z4prdob + KHrqn9uKM+oyPN0vj3BqTH/LwfT0kGrcvoXR601/uQX1Rx+09nNefJGpQd7/aLBvyMG2lvff + itW2muaIHPE6Pr86efUb4QU2l83ZnXUKlFiKMxINtZiLihMB0sexZB4DAAA= +Cc: notmuch@notmuchmail.org +X-BeenThere: notmuch@notmuchmail.org +X-Mailman-Version: 2.1.13 +Precedence: list +List-Id: "Use and development of the notmuch mail system." + +List-Unsubscribe: , + +List-Archive: +List-Post: +List-Help: +List-Subscribe: , + +X-List-Received-Date: Wed, 24 Oct 2012 21:08:46 -0000 + +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: +> +> + date:.. +> + +> 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:.. +> + +> +See \fBDATE AND TIME SEARCH\fR below for details on the range +> +expression, and supported syntax for and date and time +> +expressions. +> + +> +The time range can also be specified using timestamps with a syntax +> +of: +> + +> + .. +> + +> +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 +> +> - .. +> +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:.. +> + +> +The above expression restricts the results to only messages from +> + to , based on the Date: header. +> + +> +If or describes time at an accuracy of days or less, +> +the date/time is rounded, towards past for and towards future +> +for , 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, + + and can describe imprecise times, such as "yesterday". +In this case, is taken as the earliest time it could describe +(the beginning of yesterday) and 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:.. or date:.. 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 +>