f3/800d67fb5ac12bf5a8d5c21923a9d288538a24

   1 Return-Path: <jani@nikula.org>\r
   2 X-Original-To: notmuch@notmuchmail.org\r
   3 Delivered-To: notmuch@notmuchmail.org\r
   4 Received: from localhost (localhost [127.0.0.1])\r
   5         by olra.theworths.org (Postfix) with ESMTP id E0E3A431FC4\r
   6         for <notmuch@notmuchmail.org>; Wed, 12 Sep 2012 14:28:00 -0700 (PDT)\r
   7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
   8 X-Amavis-Alert: BAD HEADER SECTION, Duplicate header field: "References"\r
   9 X-Spam-Flag: NO\r
  10 X-Spam-Score: -0.7\r
  11 X-Spam-Level: \r
  12 X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5\r
  13         tests=[RCVD_IN_DNSWL_LOW=-0.7] autolearn=disabled\r
  14 Received: from olra.theworths.org ([127.0.0.1])\r
  15         by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
  16         with ESMTP id EF8akZUjuE-0 for <notmuch@notmuchmail.org>;\r
  17         Wed, 12 Sep 2012 14:27:59 -0700 (PDT)\r
  18 Received: from mail-lpp01m010-f53.google.com (mail-lpp01m010-f53.google.com\r
  19         [209.85.215.53]) (using TLSv1 with cipher RC4-SHA (128/128 bits))\r
  20         (No client certificate requested)\r
  21         by olra.theworths.org (Postfix) with ESMTPS id D5054431FBF\r
  22         for <notmuch@notmuchmail.org>; Wed, 12 Sep 2012 14:27:58 -0700 (PDT)\r
  23 Received: by mail-lpp01m010-f53.google.com with SMTP id c1so1533671lah.26\r
  24         for <notmuch@notmuchmail.org>; Wed, 12 Sep 2012 14:27:58 -0700 (PDT)\r
  25 X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;\r
  26         d=google.com; s=20120113;\r
  27         h=from:to:cc:subject:date:message-id:x-mailer:in-reply-to:references\r
  28         :in-reply-to:references:x-gm-message-state;\r
  29         bh=N1Ae/7X67HxGxXBlS8P8uxrKB4pxOubrwB6OBuBQiC0=;\r
  30         b=f+9jOlbaU9pK/bfBl5CiT+EYlpPdqfFK2V5Z9K7FSSBn1Xx7YlQFgQYP3Ih/zRFOYW\r
  31         4yQLRy+5BmcsoGqAwUBtdAzas1OeTgvd8yw5V+7qPLq5BrFqte8uYvUCq91fL/rH15Iw\r
  32         NBiSd0MW77wfunMxKrDanz2VL+jYTJDE3SWepjuXQVF1Ef/J398HV7HLkdplsD3SaQal\r
  33         8zkl4hbFj9x07WFfyB6QXOH4cb0Cspk9ay8/hk48NGX4RaSJgYwRWAdp39A7/zVU/4eS\r
  34         lFQbNGlxtZwZYGPj4ncUtbq3LJEAdAtrw8aeyYcreNdZzD8fdBSrMwjeyHi6FcWlS7Ob\r
  35         TgIg==\r
  36 Received: by 10.152.131.68 with SMTP id ok4mr20377243lab.47.1347485278445;\r
  37         Wed, 12 Sep 2012 14:27:58 -0700 (PDT)\r
  38 Received: from localhost (dsl-hkibrasgw4-fe51df00-27.dhcp.inet.fi.\r
  39         [80.223.81.27])\r
  40         by mx.google.com with ESMTPS id sn2sm21215528lab.16.2012.09.12.14.27.56\r
  41         (version=SSLv3 cipher=OTHER); Wed, 12 Sep 2012 14:27:57 -0700 (PDT)\r
  42 From: Jani Nikula <jani@nikula.org>\r
  43 To: notmuch@notmuchmail.org,\r
  44         David Bremner <david@tethera.net>\r
  45 Subject: [PATCH v3 8/9] man: document the date:since..until range queries\r
  46 Date: Thu, 13 Sep 2012 00:27:25 +0300\r
  47 Message-Id:\r
  48  <caf4c288d47fdc5449307209a52d3688c5ce66ee.1347484177.git.jani@nikula.org>\r
  49 X-Mailer: git-send-email 1.7.9.5\r
  50 In-Reply-To: <cover.1347484177.git.jani@nikula.org>\r
  51 References: <cover.1347484177.git.jani@nikula.org>\r
  52 In-Reply-To: <cover.1347484177.git.jani@nikula.org>\r
  53 References: <cover.1347484177.git.jani@nikula.org>\r
  54 X-Gm-Message-State:\r
  55  ALoCoQnD/NTOjs9zwdKAE6jwcJSVabNtkWFgVmsMOAzcqVvNIOJQbK16Jzu58dmHHx3G8WWgqFzv\r
  56 X-BeenThere: notmuch@notmuchmail.org\r
  57 X-Mailman-Version: 2.1.13\r
  58 Precedence: list\r
  59 List-Id: "Use and development of the notmuch mail system."\r
  60         <notmuch.notmuchmail.org>\r
  61 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
  62         <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
  63 List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
  64 List-Post: <mailto:notmuch@notmuchmail.org>\r
  65 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
  66 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
  67         <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
  68 X-List-Received-Date: Wed, 12 Sep 2012 21:28:01 -0000\r
  69 \r
  70 ---\r
  71  man/man7/notmuch-search-terms.7 |  147 +++++++++++++++++++++++++++++++++++----\r
  72  1 file changed, 135 insertions(+), 12 deletions(-)\r
  73 \r
  74 diff --git a/man/man7/notmuch-search-terms.7 b/man/man7/notmuch-search-terms.7\r
  75 index 17a109e..fbd3ee7 100644\r
  76 --- a/man/man7/notmuch-search-terms.7\r
  77 +++ b/man/man7/notmuch-search-terms.7\r
  78 @@ -54,6 +54,8 @@ terms to match against specific portions of an email, (where\r
  79  \r
  80         folder:<directory-path>\r
  81  \r
  82 +       date:<since>..<until>\r
  83 +\r
  84  The\r
  85  .B from:\r
  86  prefix is used to match the name or address of the sender of an email\r
  87 @@ -104,6 +106,26 @@ contained within particular directories within the mail store. Only\r
  88  the directory components below the top-level mail database path are\r
  89  available to be searched.\r
  90  \r
  91 +The\r
  92 +.B date:\r
  93 +prefix can be used to restrict the results to only messages within a\r
  94 +particular time range (based on the Date: header) with a range syntax\r
  95 +of:\r
  96 +\r
  97 +       date:<since>..<until>\r
  98 +\r
  99 +See \fBDATE AND TIME SEARCH\fR below for details on the range\r
 100 +expression, and supported syntax for <since> and <until> date and time\r
 101 +expressions.\r
 102 +\r
 103 +The time range can also be specified using timestamps with a syntax\r
 104 +of:\r
 105 +\r
 106 +       <initial-timestamp>..<final-timestamp>\r
 107 +\r
 108 +Each timestamp is a number representing the number of seconds since\r
 109 +1970\-01\-01 00:00:00 UTC.\r
 110 +\r
 111  In addition to individual terms, multiple terms can be\r
 112  combined with Boolean operators (\r
 113  .BR and ", " or ", " not\r
 114 @@ -117,20 +139,121 @@ operators, but will have to be protected from interpretation by the\r
 115  shell, (such as by putting quotation marks around any parenthesized\r
 116  expression).\r
 117  \r
 118 -Finally, results can be restricted to only messages within a\r
 119 -particular time range, (based on the Date: header) with a syntax of:\r
 120 +.SH DATE AND TIME SEARCH\r
 121  \r
 122 -       <initial-timestamp>..<final-timestamp>\r
 123 +This is a non-exhaustive description of the date and time search with\r
 124 +some pseudo notation. Most of the constructs can be mixed freely, and\r
 125 +in any order, but the same absolute date or time can't be expressed\r
 126 +twice.\r
 127  \r
 128 -Each timestamp is a number representing the number of seconds since\r
 129 -1970\-01\-01 00:00:00 UTC. This is not the most convenient means of\r
 130 -expressing date ranges, but until notmuch is fixed to accept a more\r
 131 -convenient form, one can use the date program to construct\r
 132 -timestamps. For example, with the bash shell the following syntax would\r
 133 -specify a date range to return messages from 2009\-10\-01 until the\r
 134 -current time:\r
 135 -\r
 136 -       $(date +%s \-d 2009\-10\-01)..$(date +%s)\r
 137 +.RS 4\r
 138 +.TP 4\r
 139 +.B The range expression\r
 140 +\r
 141 +date:<since>..<until>\r
 142 +\r
 143 +The above expression restricts the results to only messages from\r
 144 +<since> to <until>, based on the Date: header.\r
 145 +\r
 146 +If <since> or <until> describes time at an accuracy of days or less,\r
 147 +the date/time is rounded, towards past for <since> and towards future\r
 148 +for <until>, to be inclusive. For example, date:january..february\r
 149 +matches from the beginning of January until the end of\r
 150 +February. Similarly, date:yesterday..yesterday matches from the\r
 151 +beginning of yesterday until the end of yesterday.\r
 152 +\r
 153 +Open-ended ranges are supported (since Xapian 1.2.1), i.e. it's\r
 154 +possible to specify date:..<until> or date:<since>.. to not limit the\r
 155 +start or end time, respectively. Unfortunately, pre-1.2.1 Xapian does\r
 156 +not report an error on open ended ranges, but it does not work as\r
 157 +expected either.\r
 158 +\r
 159 +Xapian does not support spaces in range expressions. You can replace\r
 160 +the spaces with '_', or (in most cases) '-', or (in some cases) leave\r
 161 +the spaces out altogether.\r
 162 +\r
 163 +Entering date:expr without ".." (for example date:yesterday) won't\r
 164 +work, as it's not interpreted as a range expression at all. You can\r
 165 +achieve the expected result by duplicating the expr both sides of ".."\r
 166 +(for example date:yesterday..yesterday).\r
 167 +.RE\r
 168 +\r
 169 +.RS 4\r
 170 +.TP 4\r
 171 +.B Relative date and time\r
 172 +[N|number] (years|months|weeks|days|hours|hrs|minutes|mins|seconds|secs) [...]\r
 173 +\r
 174 +All refer to past, can be repeated and will be accumulated.\r
 175 +\r
 176 +Units can be abbreviated to any length, with the otherwise ambiguous\r
 177 +single m being m for minutes and M for months.\r
 178 +\r
 179 +Number multiplier can also be written out one, two, ..., ten, dozen,\r
 180 +hundred. As special cases last means one ("last week") and this means\r
 181 +zero ("this month").\r
 182 +\r
 183 +When combined with absolute date and time, the relative date and time\r
 184 +specification will be relative from the specified absolute date and\r
 185 +time.\r
 186 +\r
 187 +Examples: 5M2d, two weeks\r
 188 +.RE\r
 189 +\r
 190 +.RS 4\r
 191 +.TP 4\r
 192 +.B Supported time formats\r
 193 +H[H]:MM[:SS] [(am|a.m.|pm|p.m.)]\r
 194 +\r
 195 +H[H] (am|a.m.|pm|p.m.)\r
 196 +\r
 197 +HHMMSS\r
 198 +\r
 199 +now\r
 200 +\r
 201 +noon\r
 202 +\r
 203 +midnight\r
 204 +\r
 205 +Examples: 17:05, 5pm\r
 206 +.RE\r
 207 +\r
 208 +.RS 4\r
 209 +.TP 4\r
 210 +.B Supported date formats\r
 211 +YYYY-MM[-DD]\r
 212 +\r
 213 +DD-MM[-[YY]YY]\r
 214 +\r
 215 +MM-YYYY\r
 216 +\r
 217 +M[M]/D[D][/[YY]YY]\r
 218 +\r
 219 +M[M]/YYYY\r
 220 +\r
 221 +D[D].M[M][.[YY]YY]\r
 222 +\r
 223 +D[D][(st|nd|rd|th)] Mon[thname] [YYYY]\r
 224 +\r
 225 +Mon[thname] D[D][(st|nd|rd|th)] [YYYY]\r
 226 +\r
 227 +Wee[kday]\r
 228 +\r
 229 +Month names can be abbreviated at three or more characters.\r
 230 +\r
 231 +Weekday names can be abbreviated at three or more characters.\r
 232 +\r
 233 +Examples: 2012-07-31, 31-07-2012, 7/31/2012, August 3\r
 234 +.RE\r
 235 +\r
 236 +.RS 4\r
 237 +.TP 4\r
 238 +.B Time zones\r
 239 +(+|-)HH:MM\r
 240 +\r
 241 +(+|-)HH[MM]\r
 242 +\r
 243 +Some time zone codes, e.g. UTC, EET.\r
 244 +.RE\r
 245  \r
 246  .SH SEE ALSO\r
 247  \r
 248 -- \r
 249 1.7.9.5\r
 250 \r