Re: [PATCH v4 01/16] add util/search-path.{c, h} to test for executables in $PATH

[notmuch-archives.git] / 87 / 2bb2716b7f7535637a82dda6752c85e80749ad

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