From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from localhost (localhost [127.0.0.1]) by arlo.cworth.org (Postfix) with ESMTP id 6922D6DE1016 for ; Thu, 2 Nov 2017 13:01:29 -0700 (PDT) X-Virus-Scanned: Debian amavisd-new at cworth.org X-Spam-Flag: NO X-Spam-Score: 0.02 X-Spam-Level: X-Spam-Status: No, score=0.02 tagged_above=-999 required=5 tests=[AWL=0.040, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H3=-0.01, RCVD_IN_MSPIKE_WL=-0.01] autolearn=disabled Received: from arlo.cworth.org ([127.0.0.1]) by localhost (arlo.cworth.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id cVXjBmcW1Yak for ; Thu, 2 Nov 2017 13:01:28 -0700 (PDT) Received: from mail-lf0-f44.google.com (mail-lf0-f44.google.com [209.85.215.44]) by arlo.cworth.org (Postfix) with ESMTPS id 9D2286DE0C66 for ; Thu, 2 Nov 2017 13:01:27 -0700 (PDT) Received: by mail-lf0-f44.google.com with SMTP id 90so740403lfs.13 for ; Thu, 02 Nov 2017 13:01:27 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nikula-org.20150623.gappssmtp.com; s=20150623; h=from:to:cc:subject:date:message-id; bh=wLWPYw5VJWXNWOnRUl063WMXXaTZahmc7O79j0Xli1A=; b=yXI65qhoK1DPNAAWiFjVwGufzAVC3VToTcUdHoHfITPxvMYFpvHeFB9GvDZbCzMP8f SGHnqWJFUL9TUDcAbbLFHL3hCeGSnjTTO5BsVBsvlxCRown7uNs9zTr5ICDZKGv0CpT/ vJw0DcSTKvdJrdsy9rGFhtXuAR9OBDspHshyKzs0XRiAnYcRYy5/2bkxb4c8eejhN7WN n+dnxfB8T0DJO8l8oEXEVTdfJGVrbGS62YtVPyw4orjj5/9wtTuOPrf1Vgtk7IFd39SE hE3Ehc0iXUuBKW+zZ1nms/JFScCXesWShfWLpotiuJVeNlZFFE9oyyU3pPdRBByI4j6O w+SA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id; bh=wLWPYw5VJWXNWOnRUl063WMXXaTZahmc7O79j0Xli1A=; b=mSg98I9wt9279/1RGqT6ALzJZm/iPWPuO5DL2o7WDq+GYFK/SeTBBPHYh3BPEoT+dL jzm9yHk90gyyyuv8IhV4RzHShT56MI6yjS2RoCudbEik3hjXqdNGQM5bc3Rx1AKrXyUP HBzzdBAaks4jwUueTtdQuiEqkqT4Pv/cxc4CEaoBFtjWRFcsNIMtbprP7vaiIVzjxhui fJs9Je02efQ7wxTIFzhbPVjMjjPeY3WSX46CsjAVeMewpVnzzeUyRvVh3+NxdJafMzOo Gb69Rse2JrhyesDS969hGJbV7OmrUWCSLS56LzcPGfNIyfE75Cca0PRik+WJMi9A5W6I svZg== X-Gm-Message-State: AMCzsaUI6GLhXyvXatlHOCrqOUxJ9Svdf7zvi0jTxXN/tYudH+kx8rUF /vgVmy9UAEJahBG+Z58UbWsy05SvR5o= X-Google-Smtp-Source: ABhQp+S+etOOIiR87B6P1gHAdp/8+xp0zzjeOgRuY2z+1z5qsV6cSIjCbkb1Y/8jt6tIXvjy0RPXkA== X-Received: by 10.46.33.209 with SMTP id h78mr2112420lji.152.1509652885056; Thu, 02 Nov 2017 13:01:25 -0700 (PDT) Received: from localhost (mobile-access-5d6a0c-19.dhcp.inet.fi. [93.106.12.19]) by smtp.gmail.com with ESMTPSA id a73sm851102ljf.6.2017.11.02.13.01.20 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 02 Nov 2017 13:01:21 -0700 (PDT) From: Jani Nikula To: notmuch@notmuchmail.org Subject: [PATCH] doc: arrange search prefix documentation in a definition list Date: Thu, 2 Nov 2017 22:01:17 +0200 Message-Id: <20171102200117.20586-1-jani@nikula.org> X-Mailer: git-send-email 2.11.0 X-BeenThere: notmuch@notmuchmail.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Use and development of the notmuch mail system." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 02 Nov 2017 20:01:29 -0000 Having first a list of prefixes followed by detailed descriptions was viable when we didn't have all that many prefixes. Now, arranging the prefix descriptions in a definition list makes more sense. While at it, include all the supported prefix forms, especially some missing regex ones. --- doc/man7/notmuch-search-terms.rst | 237 ++++++++++++++++++-------------------- 1 file changed, 112 insertions(+), 125 deletions(-) diff --git a/doc/man7/notmuch-search-terms.rst b/doc/man7/notmuch-search-terms.rst index 637f7777dd93..6d2bf62ad7a1 100644 --- a/doc/man7/notmuch-search-terms.rst +++ b/doc/man7/notmuch-search-terms.rst @@ -30,137 +30,124 @@ recipient headers. As a special case, a search string consisting of exactly a single asterisk ("\*") will match all messages. +Search prefixes +--------------- + In addition to free text, the following prefixes can be used to force terms to match against specific portions of an email, (where -indicate user-supplied values): - -- from: - -- from:// - -- to: - -- subject: - -- subject:// - -- attachment: - -- mimetype: - -- tag: (or is:) - -- id: - -- thread: - -- folder: - -- path: or path:/** - -- date:.. - -- lastmod:.. - -- query: +indicate user-supplied values). -- property:= - -The **from:** prefix is used to match the name or address of the sender -of an email message. - -The **to:** prefix is used to match the names or addresses of any -recipient of an email message, (whether To, Cc, or Bcc). - -Any term prefixed with **subject:** will match only text from the -subject of an email. Searching for a phrase in the subject is supported -by including quotation marks around the phrase, immediately following -**subject:**. - -If notmuch is built with **Xapian Field Processors** (see below) the -**from:** and **subject** prefix can be also used to restrict the -results to those whose from/subject value matches a regular expression -(see **regex(7)**) delimited with //. - -:: +If notmuch is built with **Xapian Field Processors** (see below) some +of the prefixes with forms can be also used to restrict the +results to those whose value matches a regular expression (see +**regex(7)**) delimited with //, for example:: notmuch search 'from:/bob@.*[.]example[.]com/' -The **attachment:** prefix can be used to search for specific filenames -(or extensions) of attachments to email messages. - -The **mimetype:** prefix will be used to match text from the -content-types of MIME parts within email messages (as specified by the -sender). - -For **tag:** and **is:** valid tag values include **inbox** and -**unread** by default for new messages added by **notmuch new** as well -as any other tag values added manually with **notmuch tag**. - -For **id:**, message ID values are the literal contents of the -Message-ID: header of email messages, but without the '<', '>' -delimiters. - -The **thread:** prefix can be used with the thread ID values that are -generated internally by notmuch (and do not appear in email messages). -These thread ID values can be seen in the first column of output from -**notmuch search** - -The **path:** prefix searches for email messages that are in -particular directories within the mail store. The directory must be -specified relative to the top-level maildir (and without the leading -slash). By default, **path:** matches messages in the specified -directory only. The "/\*\*" suffix can be used to match messages in -the specified directory and all its subdirectories recursively. -**path:""** matches messages in the root of the mail store and, -likewise, **path:\*\*** matches all messages. - -The **folder:** prefix searches for email messages by maildir or MH -folder. For MH-style folders, this is equivalent to **path:**. For -maildir, this includes messages in the "new" and "cur" -subdirectories. The exact syntax for maildir folders depends on your -mail configuration. For maildir++, **folder:""** matches the inbox -folder (which is the root in maildir++), other folder names always -start with ".", and nested folders are separated by "."s, such as -**folder:.classes.topology**. For "file system" maildir, the inbox is -typically **folder:INBOX** and nested folders are separated by -slashes, such as **folder:classes/topology**. - -Both **path:** and **folder:** will find a message if *any* copy of -that message is in the specific directory/folder. - -The **date:** prefix can be used to restrict the results to only -messages within a particular time range (based on the Date: header) with -a range syntax of: - -date:.. - -See **DATE AND TIME SEARCH** below for details on the range expression, -and supported syntax for and date and time expressions. - -The time range can also be specified using timestamps with a syntax of: - -.. - -Each timestamp is a number representing the number of seconds since -1970-01-01 00:00:00 UTC. - -The **lastmod:** prefix can be used to restrict the result by the -database revision number of when messages were last modified (tags -were added/removed or filenames changed). This is usually used in -conjunction with the **--uuid** argument to **notmuch search** -to find messages that have changed since an earlier query. - -The **query:** prefix allows queries to refer to previously saved -queries added with **notmuch-config(1)**. Named queries are only -available if notmuch is built with **Xapian Field Processors** (see -below). - -The **property:** prefix searches for messages with a particular -= property pair. Properties are used internally by notmuch -(and extensions) to add metadata to messages. A given key can be -present on a given message with several different values. See -**notmuch-properties(7)** for more details. +from: or from:// + The **from:** prefix is used to match the name or address of + the sender of an email message. + +to: + The **to:** prefix is used to match the names or addresses of any + recipient of an email message, (whether To, Cc, or Bcc). + +subject: or subject:// + Any term prefixed with **subject:** will match only text from the + subject of an email. Searching for a phrase in the subject is + supported by including quotation marks around the phrase, + immediately following **subject:**. + +attachment: + The **attachment:** prefix can be used to search for specific + filenames (or extensions) of attachments to email messages. + +mimetype: + The **mimetype:** prefix will be used to match text from the + content-types of MIME parts within email messages (as specified by + the sender). + +tag: or tag:// or is: or is:// + For **tag:** and **is:** valid tag values include **inbox** and + **unread** by default for new messages added by **notmuch new** as + well as any other tag values added manually with **notmuch tag**. + +id: or mid: or mid:// + For **id:** and **mid:**, message ID values are the literal + contents of the Message-ID: header of email messages, but without + the '<', '>' delimiters. + +thread: + The **thread:** prefix can be used with the thread ID values that + are generated internally by notmuch (and do not appear in email + messages). These thread ID values can be seen in the first column + of output from **notmuch search** + +path: or path:/** or path:// + The **path:** prefix searches for email messages that are in + particular directories within the mail store. The directory must + be specified relative to the top-level maildir (and without the + leading slash). By default, **path:** matches messages in the + specified directory only. The "/\*\*" suffix can be used to match + messages in the specified directory and all its subdirectories + recursively. **path:""** matches messages in the root of the mail + store and, likewise, **path:\*\*** matches all messages. + + **path:** will find a message if *any* copy of that message is in + the specific directory. + +folder: or folder:// + The **folder:** prefix searches for email messages by maildir or + MH folder. For MH-style folders, this is equivalent to + **path:**. For maildir, this includes messages in the "new" and + "cur" subdirectories. The exact syntax for maildir folders depends + on your mail configuration. For maildir++, **folder:""** matches + the inbox folder (which is the root in maildir++), other folder + names always start with ".", and nested folders are separated by + "."s, such as **folder:.classes.topology**. For "file system" + maildir, the inbox is typically **folder:INBOX** and nested + folders are separated by slashes, such as + **folder:classes/topology**. + + **folder:** will find a message if *any* copy of that message is + in the specific folder. + +date:.. or date: + The **date:** prefix can be used to restrict the results to only + messages within a particular time range (based on the Date: + header). + + See **DATE AND TIME SEARCH** below for details on the range + expression, and supported syntax for and date and + time expressions. + + The time range can also be specified using timestamps with a + syntax of: + + .. + + Each timestamp is a number representing the number of seconds + since 1970-01-01 00:00:00 UTC. + +lastmod:.. + The **lastmod:** prefix can be used to restrict the result by the + database revision number of when messages were last modified (tags + were added/removed or filenames changed). This is usually used in + conjunction with the **--uuid** argument to **notmuch search** to + find messages that have changed since an earlier query. + +query: + The **query:** prefix allows queries to refer to previously saved + queries added with **notmuch-config(1)**. Named queries are only + available if notmuch is built with **Xapian Field Processors** + (see below). + +property:= + The **property:** prefix searches for messages with a particular + = property pair. Properties are used internally by + notmuch (and extensions) to add metadata to messages. A given key + can be present on a given message with several different values. + See **notmuch-properties(7)** for more details. Operators --------- -- 2.11.0