Re: doc: notmuch help search-terms, boolean operators

diff --git a/34/b96cd2e097e00176afcd0d03c3d81a801395c5 b/34/b96cd2e097e00176afcd0d03c3d81a801395c5
new file mode 100644 (file)
index 0000000..c49fef9
--- /dev/null
+++ b/34/b96cd2e097e00176afcd0d03c3d81a801395c5
@@ -0,0 +1,132 @@
+Return-Path: <amdragon@gmail.com>\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 A0DCF429E40\r
+       for <notmuch@notmuchmail.org>; Tue, 26 Apr 2011 16:55:18 -0700 (PDT)\r
+X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
+X-Spam-Flag: NO\r
+X-Spam-Score: -0.699\r
+X-Spam-Level: \r
+X-Spam-Status: No, score=-0.699 tagged_above=-999 required=5\r
+       tests=[DKIM_SIGNED=0.1, DKIM_VALID=-0.1, FREEMAIL_FROM=0.001,\r
+       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 m+PmN0x9hGd6 for <notmuch@notmuchmail.org>;\r
+       Tue, 26 Apr 2011 16:55:18 -0700 (PDT)\r
+Received: from mail-qw0-f53.google.com (mail-qw0-f53.google.com\r
+       [209.85.216.53]) (using TLSv1 with cipher RC4-SHA (128/128 bits))\r
+       (No client certificate requested)\r
+       by olra.theworths.org (Postfix) with ESMTPS id DF3BC429E38\r
+       for <notmuch@notmuchmail.org>; Tue, 26 Apr 2011 16:55:17 -0700 (PDT)\r
+Received: by qwb7 with SMTP id 7so620353qwb.26\r
+       for <notmuch@notmuchmail.org>; Tue, 26 Apr 2011 16:55:14 -0700 (PDT)\r
+DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma;\r
+       h=domainkey-signature:mime-version:sender:in-reply-to:references:date\r
+       :x-google-sender-auth:message-id:subject:from:to:cc:content-type\r
+       :content-transfer-encoding;\r
+       bh=EjJ4vnb9hXGGI6Eb1w4dCM2cxjd38673LrC6uXhgFCY=;\r
+       b=Z5bJEunGjrYF+j0ZatdDDZ8aWAZE+l7ioOsqDUVqwNB/JkUuz1ZSJFKhNRqa6pNl3v\r
+       Y9KarVCf5jaZQNKfB4gosKP8jnoyWl3QQtuOHfqjEWJJ78iekM62fgELebqZkFp18F9c\r
+       r9thwdTVY2IULmlAj5ac+vEE4ZbQulgOY7THc=\r
+DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma;\r
+       h=mime-version:sender:in-reply-to:references:date\r
+       :x-google-sender-auth:message-id:subject:from:to:cc:content-type\r
+       :content-transfer-encoding;\r
+       b=SfXjiwfQ1D03bBmSa2braitVrfn+lgGxhFhyge0DzfTAR8TDshIPr7hrzwqQbRlRiO\r
+       GO5smB1/LfqH+CawIm273XCpyJbSObDUKHgSyc4/8aJbk7RAgZpSUgEXBNTyOLoOw9eK\r
+       XXMolHxqFCBkVmHCs84QvvlQpRYdSPduijO+A=\r
+MIME-Version: 1.0\r
+Received: by 10.229.131.23 with SMTP id v23mr1156475qcs.11.1303862114636; Tue,\r
+       26 Apr 2011 16:55:14 -0700 (PDT)\r
+Sender: amdragon@gmail.com\r
+Received: by 10.229.220.148 with HTTP; Tue, 26 Apr 2011 16:55:14 -0700 (PDT)\r
+In-Reply-To: <87fwp4tzvd.fsf@eve.chaoflow.net>\r
+References: <87fwp4tzvd.fsf@eve.chaoflow.net>\r
+Date: Tue, 26 Apr 2011 19:55:14 -0400\r
+X-Google-Sender-Auth: vDvm2-1VvfQL05K9buv_ZQQwFoU\r
+Message-ID: <BANLkTinG_DdR5gdPr7=YkESPpY+apdD+Tg@mail.gmail.com>\r
+Subject: Re: doc: notmuch help search-terms, boolean operators\r
+From: Austin Clements <amdragon@mit.edu>\r
+To: Florian Friesdorf <flo@chaoflow.net>\r
+Content-Type: text/plain; charset=ISO-8859-1\r
+Content-Transfer-Encoding: quoted-printable\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: Tue, 26 Apr 2011 23:55:18 -0000\r
+\r
+The full precedence is rather complicated, once you include all Xapian\r
+operators and exceptions.  See\r
+http://trac.xapian.org/browser/trunk/xapian-core/queryparser/queryparser.le=\r
+mony,\r
+particularly starting at line 1560.  Your precedence list is mostly\r
+right, except that AND and NOT have the same precedence (and are\r
+disambiguated by left-associativity in binary situations).\r
+\r
+I think the real question is what we *want* notmuch to support.  My\r
+understanding from id:"8762rq8byr.fsf@yoom.home.cworth.org" is that\r
+things like NEAR and ADJ were intentionally omitted from the\r
+documentation; that while notmuch inherits them from the Xapian query\r
+parser, they aren't considered part of the "notmuch" query syntax.  I\r
+would also classify XOR as dubious (even the Xapian docs call it\r
+esoteric), but I'm happy to be convinced otherwise.\r
+\r
+I'd love to know what people want from the query syntax for the\r
+purposes of trimming down the custom query parser patch, and it would\r
+also answer what should be documented (the current "etc" in the\r
+documentation is just asking for trouble!).  I would propose "and",\r
+"or", "not", "-" (and maybe "+" for symmetry, even though it's a\r
+no-op), brackets, phrases, and wildcards, but what do other people\r
+think?\r
+\r
+On Tue, Apr 26, 2011 at 6:24 PM, Florian Friesdorf <flo@chaoflow.net> wrote=\r
+:\r
+>\r
+> `notmuch help search-terms` currently states: "In addition to\r
+> individual terms, multiple terms can be combined with Boolean operators\r
+> ("and", "or", "not", etc.).".\r
+>\r
+> I would like to replace the "etc" with a full list and document the\r
+> operator precedence.\r
+>\r
+> In lib/notmuch.h for notmuch_query_create I found a pointer to xapian\r
+> docs [2], which states that AND takes precedence over OR, but nothing\r
+> for NOT and XOR.\r
+>\r
+> Through playing with `notmuch tag` and `notmuch search\r
+> --output=3Dmessages` I found:\r
+>\r
+> Complete list of boolean operators in order of precedence:\r
+> - NOT\r
+> - AND\r
+> - XOR\r
+> - OR\r
+>\r
+> Is this correct? If yes, I would extend the manpage accordingly.\r
+>\r
+> [2] http://xapian.org/docs/queryparser.html\r
+>\r
+> --\r
+> Florian Friesdorf <flo@chaoflow.net>\r
+> =A0GPG FPR: 7A13 5EEE 1421 9FC2 108D =A0BAAF 38F8 99A3 0C45 F083\r
+> Jabber/XMPP: flo@chaoflow.net\r
+> IRC: chaoflow on freenode,ircnet,blafasel,OFTC\r
+>\r
+> _______________________________________________\r
+> notmuch mailing list\r
+> notmuch@notmuchmail.org\r
+> http://notmuchmail.org/mailman/listinfo/notmuch\r
+>\r
+>\r