--- /dev/null
+Return-Path: <amdragon@mit.edu>\r
+X-Original-To: notmuch@notmuchmail.org\r
+Delivered-To: notmuch@notmuchmail.org\r
+Received: from localhost (localhost [127.0.0.1])\r
+ by olra.theworths.org (Postfix) with ESMTP id 3319B431FAF\r
+ for <notmuch@notmuchmail.org>; Wed, 24 Oct 2012 14:08:46 -0700 (PDT)\r
+X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
+X-Spam-Flag: NO\r
+X-Spam-Score: -0.7\r
+X-Spam-Level: \r
+X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5\r
+ tests=[RCVD_IN_DNSWL_LOW=-0.7] autolearn=disabled\r
+Received: from olra.theworths.org ([127.0.0.1])\r
+ by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
+ with ESMTP id Xoi3nkTZfeKL for <notmuch@notmuchmail.org>;\r
+ Wed, 24 Oct 2012 14:08:45 -0700 (PDT)\r
+Received: from dmz-mailsec-scanner-3.mit.edu (DMZ-MAILSEC-SCANNER-3.MIT.EDU\r
+ [18.9.25.14])\r
+ by olra.theworths.org (Postfix) with ESMTP id 32D84431FAE\r
+ for <notmuch@notmuchmail.org>; Wed, 24 Oct 2012 14:08:45 -0700 (PDT)\r
+X-AuditID: 1209190e-b7f756d000000904-9e-508858db5ddf\r
+Received: from mailhub-auth-2.mit.edu ( [18.7.62.36])\r
+ by dmz-mailsec-scanner-3.mit.edu (Symantec Messaging Gateway) with SMTP\r
+ id EF.20.02308.BD858805; Wed, 24 Oct 2012 17:08:43 -0400 (EDT)\r
+Received: from outgoing.mit.edu (OUTGOING-AUTH.MIT.EDU [18.7.22.103])\r
+ by mailhub-auth-2.mit.edu (8.13.8/8.9.2) with ESMTP id q9OL8hlk023088; \r
+ Wed, 24 Oct 2012 17:08:43 -0400\r
+Received: from awakening.csail.mit.edu (awakening.csail.mit.edu [18.26.4.91])\r
+ (authenticated bits=0)\r
+ (User authenticated as amdragon@ATHENA.MIT.EDU)\r
+ by outgoing.mit.edu (8.13.6/8.12.4) with ESMTP id q9OL8fgX029227\r
+ (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NOT);\r
+ Wed, 24 Oct 2012 17:08:42 -0400 (EDT)\r
+Received: from amthrax by awakening.csail.mit.edu with local (Exim 4.77)\r
+ (envelope-from <amdragon@mit.edu>)\r
+ id 1TR8Bt-0005xj-8m; Wed, 24 Oct 2012 17:08:41 -0400\r
+Date: Wed, 24 Oct 2012 17:08:41 -0400\r
+From: Austin Clements <amdragon@MIT.EDU>\r
+To: Jani Nikula <jani@nikula.org>\r
+Subject: Re: [PATCH v5 8/9] man: document the date:since..until range queries\r
+Message-ID: <20121024210841.GU14861@mit.edu>\r
+References: <cover.1350854171.git.jani@nikula.org>\r
+ <cff9c1dd87b8bc11326dca0b3589c81656500f5e.1350854171.git.jani@nikula.org>\r
+MIME-Version: 1.0\r
+Content-Type: text/plain; charset=us-ascii\r
+Content-Disposition: inline\r
+In-Reply-To:\r
+ <cff9c1dd87b8bc11326dca0b3589c81656500f5e.1350854171.git.jani@nikula.org>\r
+User-Agent: Mutt/1.5.21 (2010-09-15)\r
+X-Brightmail-Tracker:\r
+ H4sIAAAAAAAAA+NgFupmleLIzCtJLcpLzFFi42IRYrdT0b0d0RFg8PK5uUXTdGeL6zdnMjsw\r
+ edy6/5rd49mqW8wBTFFcNimpOZllqUX6dglcGZc+dbIWfLWrOLP0P2sDY6NRFyMnh4SAicTE\r
+ ay2MELaYxIV769m6GLk4hAT2MUrs3v2FEcLZwCjx9WcvM0iVkMBJJok/E5Qg7CWMEps+y4HY\r
+ LAKqEvv/vWYDsdkENCS27V8ONlVEQFFi88n9YDazgLTEt9/NTF2M7BzCAr4SR2JBorwCOhJH\r
+ W1awQkysk/j27jcbRFxQ4uTMJywQnVoSN/69BOrkAJuy/B8HSJhTIEzixIuTYCWiAioSU05u\r
+ Y5vAKDQLSfcsJN2zELoXMDKvYpRNya3SzU3MzClOTdYtTk7My0st0jXWy80s0UtNKd3ECApn\r
+ Tkm+HYxfDyodYhTgYFTi4T3g0REgxJpYVlyZe4hRkoNJSZTXMBQoxJeUn1KZkVicEV9UmpNa\r
+ fIhRgoNZSYR38oP2ACHelMTKqtSifJiUNAeLkjjvlZSb/kIC6YklqdmpqQWpRTBZGQ4OJQle\r
+ D2DcCgkWpaanVqRl5pQgpJk4OEGG8wAN1wap4S0uSMwtzkyHyJ9i1OU4+mbuQ0Yhlrz8vFQp\r
+ cd6J4UBFAiBFGaV5cHNgaegVozjQW8K8ciCjeIApDG7SK6AlTEBLzHlaQZaUJCKkpBoYN8sK\r
+ X73cZ/O+/dMWgxcPqq5KLT7gueViAdP71TzXL2Zx95+Y++fN3T43pfkO081cfNuS/Z4prdob\r
+ KHrqn9uKM+oyPN0vj3BqTH/LwfT0kGrcvoXR601/uQX1Rx+09nNefJGpQd7/aLBvyMG2lvff\r
+ itW2muaIHPE6Pr86efUb4QU2l83ZnXUKlFiKMxINtZiLihMB0sexZB4DAAA=\r
+Cc: notmuch@notmuchmail.org\r
+X-BeenThere: notmuch@notmuchmail.org\r
+X-Mailman-Version: 2.1.13\r
+Precedence: list\r
+List-Id: "Use and development of the notmuch mail system."\r
+ <notmuch.notmuchmail.org>\r
+List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
+ <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
+List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
+List-Post: <mailto:notmuch@notmuchmail.org>\r
+List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
+List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
+ <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
+X-List-Received-Date: Wed, 24 Oct 2012 21:08:46 -0000\r
+\r
+Quoth Jani Nikula on Oct 22 at 12:22 am:\r
+> ---\r
+> man/man7/notmuch-search-terms.7 | 147 +++++++++++++++++++++++++++++++++++----\r
+> 1 file changed, 135 insertions(+), 12 deletions(-)\r
+> \r
+> diff --git a/man/man7/notmuch-search-terms.7 b/man/man7/notmuch-search-terms.7\r
+> index 17a109e..fbd3ee7 100644\r
+> --- a/man/man7/notmuch-search-terms.7\r
+> +++ b/man/man7/notmuch-search-terms.7\r
+> @@ -54,6 +54,8 @@ terms to match against specific portions of an email, (where\r
+> \r
+> folder:<directory-path>\r
+> \r
+> + date:<since>..<until>\r
+> +\r
+> The\r
+> .B from:\r
+> prefix is used to match the name or address of the sender of an email\r
+> @@ -104,6 +106,26 @@ contained within particular directories within the mail store. Only\r
+> the directory components below the top-level mail database path are\r
+> available to be searched.\r
+> \r
+> +The\r
+> +.B date:\r
+> +prefix can be used to restrict the results to only messages within a\r
+> +particular time range (based on the Date: header) with a range syntax\r
+> +of:\r
+> +\r
+> + date:<since>..<until>\r
+> +\r
+> +See \fBDATE AND TIME SEARCH\fR below for details on the range\r
+> +expression, and supported syntax for <since> and <until> date and time\r
+> +expressions.\r
+> +\r
+> +The time range can also be specified using timestamps with a syntax\r
+> +of:\r
+> +\r
+> + <initial-timestamp>..<final-timestamp>\r
+> +\r
+> +Each timestamp is a number representing the number of seconds since\r
+> +1970\-01\-01 00:00:00 UTC.\r
+> +\r
+> In addition to individual terms, multiple terms can be\r
+> combined with Boolean operators (\r
+> .BR and ", " or ", " not\r
+> @@ -117,20 +139,121 @@ operators, but will have to be protected from interpretation by the\r
+> shell, (such as by putting quotation marks around any parenthesized\r
+> expression).\r
+> \r
+> -Finally, results can be restricted to only messages within a\r
+> -particular time range, (based on the Date: header) with a syntax of:\r
+> +.SH DATE AND TIME SEARCH\r
+> \r
+> - <initial-timestamp>..<final-timestamp>\r
+> +This is a non-exhaustive description of the date and time search with\r
+> +some pseudo notation. Most of the constructs can be mixed freely, and\r
+> +in any order, but the same absolute date or time can't be expressed\r
+> +twice.\r
+\r
+I'm not sure what the end of this sentence means, though I assume it's\r
+related to the restrictions on repeated absolute components. It would\r
+also be nice to give a broader view of the syntax here. Maybe,\r
+\r
+notmuch understands a variety of standard and natural ways of\r
+expressing dates and times, both in absolute terms ("2012-10-24") and\r
+in relative terms ("yesterday"). Any number of relative terms can be\r
+combined ("1 hour 25 minutes") and an absolute date/time can be\r
+combined with relative terms to further adjust it. A non-exhaustive\r
+description of the syntax supported for absolute and relative terms is\r
+given below.\r
+\r
+> \r
+> -Each timestamp is a number representing the number of seconds since\r
+> -1970\-01\-01 00:00:00 UTC. This is not the most convenient means of\r
+> -expressing date ranges, but until notmuch is fixed to accept a more\r
+> -convenient form, one can use the date program to construct\r
+> -timestamps. For example, with the bash shell the following syntax would\r
+> -specify a date range to return messages from 2009\-10\-01 until the\r
+> -current time:\r
+> -\r
+> - $(date +%s \-d 2009\-10\-01)..$(date +%s)\r
+> +.RS 4\r
+> +.TP 4\r
+> +.B The range expression\r
+> +\r
+> +date:<since>..<until>\r
+> +\r
+> +The above expression restricts the results to only messages from\r
+> +<since> to <until>, based on the Date: header.\r
+> +\r
+> +If <since> or <until> describes time at an accuracy of days or less,\r
+> +the date/time is rounded, towards past for <since> and towards future\r
+> +for <until>, to be inclusive. For example, date:january..february\r
+\r
+The accuracy doesn't seem to have have anything to do with days; if I\r
+say "date:1hour..1hour" I get a span of an hour. Describing it as\r
+rounding also seems like it could be confusing to someone who hasn't\r
+thought a lot about this (though, as someone who has though a lot\r
+about this, I could be wrong). What about something like,\r
+\r
+<since> and <until> can describe imprecise times, such as "yesterday".\r
+In this case, <since> is taken as the earliest time it could describe\r
+(the beginning of yesterday) and <until> is taken as the latest time\r
+it could describe (the end of yesterday). Similarly,\r
+date:january..february matches from the beginning of January to the\r
+end of February.\r
+\r
+> +matches from the beginning of January until the end of\r
+> +February. Similarly, date:yesterday..yesterday matches from the\r
+> +beginning of yesterday until the end of yesterday.\r
+> +\r
+> +Open-ended ranges are supported (since Xapian 1.2.1), i.e. it's\r
+> +possible to specify date:..<until> or date:<since>.. to not limit the\r
+> +start or end time, respectively. Unfortunately, pre-1.2.1 Xapian does\r
+\r
+No need for the "Unfortunately".\r
+\r
+> +not report an error on open ended ranges, but it does not work as\r
+> +expected either.\r
+> +\r
+> +Xapian does not support spaces in range expressions. You can replace\r
+\r
+The man pages essentially don't reference Xapian and the fact that we\r
+use Xapian is transparent to the uninterested user. Maybe just\r
+"Currently, we do not support spaces ..."? Or "Due to technical\r
+limitations, we do not currently support spaces ..." if you want to\r
+convey that we feel the user's pain but it's actually hard to fix.\r
+\r
+> +the spaces with '_', or (in most cases) '-', or (in some cases) leave\r
+> +the spaces out altogether.\r
+\r
+Maybe add "Examples in this man page use spaces for clarity."? It's\r
+unfortunate that this rather critical piece of information is buried\r
+in the middle of a subsection of the man page. I wonder if it should\r
+at least go before the previous paragraph? We are going to get so\r
+many people asking why their date searches don't work...\r
+\r
+> +\r
+> +Entering date:expr without ".." (for example date:yesterday) won't\r
+> +work, as it's not interpreted as a range expression at all. You can\r
+> +achieve the expected result by duplicating the expr both sides of ".."\r
+> +(for example date:yesterday..yesterday).\r
+> +.RE\r
+> +\r
+> +.RS 4\r
+> +.TP 4\r
+> +.B Relative date and time\r
+> +[N|number] (years|months|weeks|days|hours|hrs|minutes|mins|seconds|secs) [...]\r
+> +\r
+> +All refer to past, can be repeated and will be accumulated.\r
+> +\r
+> +Units can be abbreviated to any length, with the otherwise ambiguous\r
+> +single m being m for minutes and M for months.\r
+> +\r
+> +Number multiplier can also be written out one, two, ..., ten, dozen,\r
+\r
+This is the only use of "multiplier". I think it would be fine to\r
+just say "the number".\r
+\r
+> +hundred. As special cases last means one ("last week") and this means\r
+> +zero ("this month").\r
+\r
+Maybe, "Additionally, the unit may be preceded by "last" or "this"\r
+(e.g., "last week" or "this month")."?\r
+\r
+> +\r
+> +When combined with absolute date and time, the relative date and time\r
+> +specification will be relative from the specified absolute date and\r
+> +time.\r
+> +\r
+> +Examples: 5M2d, two weeks\r
+> +.RE\r
+> +\r
+> +.RS 4\r
+> +.TP 4\r
+> +.B Supported time formats\r
+\r
+Supported absolute time formats?\r
+\r
+> +H[H]:MM[:SS] [(am|a.m.|pm|p.m.)]\r
+> +\r
+> +H[H] (am|a.m.|pm|p.m.)\r
+> +\r
+> +HHMMSS\r
+> +\r
+> +now\r
+> +\r
+> +noon\r
+> +\r
+> +midnight\r
+> +\r
+> +Examples: 17:05, 5pm\r
+> +.RE\r
+> +\r
+> +.RS 4\r
+> +.TP 4\r
+> +.B Supported date formats\r
+\r
+Supported absolute date formats?\r
+\r
+> +YYYY-MM[-DD]\r
+> +\r
+> +DD-MM[-[YY]YY]\r
+> +\r
+> +MM-YYYY\r
+> +\r
+> +M[M]/D[D][/[YY]YY]\r
+> +\r
+> +M[M]/YYYY\r
+> +\r
+> +D[D].M[M][.[YY]YY]\r
+> +\r
+> +D[D][(st|nd|rd|th)] Mon[thname] [YYYY]\r
+> +\r
+> +Mon[thname] D[D][(st|nd|rd|th)] [YYYY]\r
+> +\r
+> +Wee[kday]\r
+> +\r
+> +Month names can be abbreviated at three or more characters.\r
+> +\r
+> +Weekday names can be abbreviated at three or more characters.\r
+> +\r
+> +Examples: 2012-07-31, 31-07-2012, 7/31/2012, August 3\r
+> +.RE\r
+> +\r
+> +.RS 4\r
+> +.TP 4\r
+> +.B Time zones\r
+> +(+|-)HH:MM\r
+> +\r
+> +(+|-)HH[MM]\r
+> +\r
+> +Some time zone codes, e.g. UTC, EET.\r
+> +.RE\r
+> \r
+> .SH SEE ALSO\r
+> \r
projects / notmuch-archives.git / commitdiff