--- /dev/null
+Return-Path: <jani@nikula.org>\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 AA75E431FBC\r
+ for <notmuch@notmuchmail.org>; Sun, 28 Oct 2012 15:41:08 -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 uQ2PnKimuHTc for <notmuch@notmuchmail.org>;\r
+ Sun, 28 Oct 2012 15:41:07 -0700 (PDT)\r
+Received: from mail-lb0-f181.google.com (mail-lb0-f181.google.com\r
+ [209.85.217.181]) (using TLSv1 with cipher RC4-SHA (128/128 bits))\r
+ (No client certificate requested)\r
+ by olra.theworths.org (Postfix) with ESMTPS id 4D06B431FAF\r
+ for <notmuch@notmuchmail.org>; Sun, 28 Oct 2012 15:41:07 -0700 (PDT)\r
+Received: by mail-lb0-f181.google.com with SMTP id gg6so3133586lbb.26\r
+ for <notmuch@notmuchmail.org>; Sun, 28 Oct 2012 15:41:05 -0700 (PDT)\r
+X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;\r
+ d=google.com; s=20120113;\r
+ h=from:to:cc:subject:in-reply-to:references:user-agent:date\r
+ :message-id:mime-version:content-type:x-gm-message-state;\r
+ bh=SNf8sHse4mzzADH8TpsSrQUwe8wy1vvwfxuXueMeiJ4=;\r
+ b=X+dsYGH/+KJPRyBKKLwKU+w0db8bQkUuKT/Pr8S2PSrcaMBKmoyRIW/zeDSaDzHTVA\r
+ 3MQV9K0Eiu5LpDix6nQiF4ajjX74utLhS6yuSMBODD/h9ITS9DW6thMHeAEVaBww3Mcw\r
+ Y7I/c/s1ta394GExT46zgM8qhzg6m7ZsMIsJ3zO8w83y9Ojvbc40gegezIWjPvO/Qmq2\r
+ UvmL1RWHpbrIsh3QVyeTXcCC3I+2k30OGKCC7NhZD60fR8Vdas/BBF7u+l8vwbsWqklh\r
+ 293Ing1zdPZZbCugQ05njrGWl4YYr2OMWlRGzdaOySTb3fg+gZixb0KA/wS3TM6MuNJm\r
+ LPAg==\r
+Received: by 10.112.44.65 with SMTP id c1mr9770248lbm.62.1351464065866;\r
+ Sun, 28 Oct 2012 15:41:05 -0700 (PDT)\r
+Received: from localhost (dsl-hkibrasgw4-fe51df00-27.dhcp.inet.fi.\r
+ [80.223.81.27])\r
+ by mx.google.com with ESMTPS id m9sm2556735lbz.16.2012.10.28.15.41.04\r
+ (version=SSLv3 cipher=OTHER); Sun, 28 Oct 2012 15:41:04 -0700 (PDT)\r
+From: Jani Nikula <jani@nikula.org>\r
+To: Austin Clements <amdragon@MIT.EDU>\r
+Subject: Re: [PATCH v5 8/9] man: document the date:since..until range queries\r
+In-Reply-To: <20121024210841.GU14861@mit.edu>\r
+References: <cover.1350854171.git.jani@nikula.org>\r
+ <cff9c1dd87b8bc11326dca0b3589c81656500f5e.1350854171.git.jani@nikula.org>\r
+ <20121024210841.GU14861@mit.edu>\r
+User-Agent: Notmuch/0.14+46~g272a1f1 (http://notmuchmail.org) Emacs/23.4.1\r
+ (i686-pc-linux-gnu)\r
+Date: Mon, 29 Oct 2012 00:41:02 +0200\r
+Message-ID: <87d302kyo1.fsf@nikula.org>\r
+MIME-Version: 1.0\r
+Content-Type: text/plain; charset=us-ascii\r
+X-Gm-Message-State:\r
+ ALoCoQkCDLQoGFuRr0R+eMz0kHwkI1VWPE+EuuFg4V/wm95EwllXLbU1x0UzF8XTQBHX9JL0PMvQ\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: Sun, 28 Oct 2012 22:41:08 -0000\r
+\r
+\r
+Many thanks, I'll incorporate most of your suggestions as-is.\r
+\r
+BR,\r
+Jani.\r
+\r
+\r
+On Thu, 25 Oct 2012, Austin Clements <amdragon@MIT.EDU> wrote:\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