shorten description of jaro-mail

[notmuch-wiki] / manpages / notmuch-search-terms-7.mdwn

diff --git a/manpages/notmuch-search-terms-7.mdwn b/manpages/notmuch-search-terms-7.mdwn
index b36c16b2fe0a7f3674f75d737c3f6b9ddc7944ee..f92b7c4e791b7d3b24bdcac5f7f2bbdd2d8006a4 100644 (file)
--- a/manpages/notmuch-search-terms-7.mdwn
+++ b/manpages/notmuch-search-terms-7.mdwn
@@ -37,10 +37,14 @@
 
        · from:<name-or-address>
 
 
        · from:<name-or-address>
 

+       · from:/<regex>/
+

        · to:<name-or-address>
 
        · subject:<word-or-quoted-phrase>
 
        · to:<name-or-address>
 
        · subject:<word-or-quoted-phrase>
 

+       · subject:/<regex>/
+

        · attachment:<word>
 
        · mimetype:<word>
        · attachment:<word>
 
        · mimetype:<word>


@@ -59,6 +63,10 @@
 
        · lastmod:<initial-revision>..<final-revision>
 
 
        · lastmod:<initial-revision>..<final-revision>
 

+       · query:<name>
+
+       · property:<key>=<value>
+

        The <b>from:</b> prefix is used to match the name or address of the sender  of
        an email message.
 
        The <b>from:</b> prefix is used to match the name or address of the sender  of
        an email message.
 


@@ -70,46 +78,53 @@
        including quotation marks around the phrase, immediately following <b>sub-</b>
        <b>ject:</b>.
 
        including quotation marks around the phrase, immediately following <b>sub-</b>
        <b>ject:</b>.
 

+       If  notmuch is built with <b>Xapian</b> <b>Field</b> <b>Processors</b> (see below) the <b>from:</b>
+       and <b>subject</b> prefix can be also used to restrict the  results  to  those
+       whose  from/subject  value  matches a regular expression (see <b>regex</b>(7))
+       delimited with //.
+
+          notmuch search &apos;from:/bob@.*[.]example[.]com/&apos;
+

        The <b>attachment:</b> prefix can be used to search for specific filenames (or
        extensions) of attachments to email messages.
 
        The <b>attachment:</b> prefix can be used to search for specific filenames (or
        extensions) of attachments to email messages.
 

-       The <b>mimetype:</b> prefix will be used to match text from the  content-types
+       The  <b>mimetype:</b> prefix will be used to match text from the content-types

        of MIME parts within email messages (as specified by the sender).
 
        of MIME parts within email messages (as specified by the sender).
 

-       For  <b>tag:</b>  and <b>is:</b> valid tag values include <b>inbox</b> and <b>unread</b> by default
-       for new messages added by <b>notmuch</b> <b>new</b> as well as any other  tag  values
+       For <b>tag:</b> and <b>is:</b> valid tag values include <b>inbox</b> and <b>unread</b>  by  default
+       for  new  messages added by <b>notmuch</b> <b>new</b> as well as any other tag values

        added manually with <b>notmuch</b> <b>tag</b>.
 
        added manually with <b>notmuch</b> <b>tag</b>.
 

-       For  <b>id:</b>, message ID values are the literal contents of the Message-ID:
+       For <b>id:</b>, message ID values are the literal contents of the  Message-ID:

        header of email messages, but without the &apos;&lt;&apos;, &apos;&gt;&apos; delimiters.
 
        header of email messages, but without the &apos;&lt;&apos;, &apos;&gt;&apos; delimiters.
 

-       The <b>thread:</b> prefix can be used with the thread ID values that are  gen‐
-       erated  internally  by  notmuch  (and do not appear in email messages).
-       These thread ID values can be seen in the first column of  output  from
+       The  <b>thread:</b> prefix can be used with the thread ID values that are gen‐
+       erated internally by notmuch (and do not  appear  in  email  messages).
+       These  thread  ID values can be seen in the first column of output from

        <b>notmuch</b> <b>search</b>
 
        <b>notmuch</b> <b>search</b>
 

-       The  <b>path:</b>  prefix  searches  for email messages that are in particular
+       The <b>path:</b> prefix searches for email messages  that  are  in  particular

        directories within the mail store. The directory must be specified rel‐
        directories within the mail store. The directory must be specified rel‐

-       ative  to  the  top-level  maildir  (and without the leading slash). By
-       default, <b>path:</b> matches messages in the specified  directory  only.  The
-       &quot;/**&quot;  suffix  can be used to match messages in the specified directory
-       and all its subdirectories recursively.  <b>path:&quot;&quot;</b>  matches  messages  in
+       ative to the top-level maildir (and  without  the  leading  slash).  By
+       default,  <b>path:</b>  matches  messages in the specified directory only. The
+       &quot;/**&quot; suffix can be used to match messages in the  specified  directory
+       and  all  its  subdirectories recursively.  <b>path:&quot;&quot;</b> matches messages in

        the root of the mail store and, likewise, <b>path:**</b> matches all messages.
 
        The <b>folder:</b> prefix searches for email messages by maildir or MH folder.
        the root of the mail store and, likewise, <b>path:**</b> matches all messages.
 
        The <b>folder:</b> prefix searches for email messages by maildir or MH folder.

-       For MH-style folders, this is equivalent to <b>path:</b>.  For  maildir,  this
+       For  MH-style  folders,  this is equivalent to <b>path:</b>. For maildir, this

        includes messages in the &quot;new&quot; and &quot;cur&quot; subdirectories. The exact syn‐
        includes messages in the &quot;new&quot; and &quot;cur&quot; subdirectories. The exact syn‐

-       tax for  maildir  folders  depends  on  your  mail  configuration.  For
-       maildir++,  <b>folder:&quot;&quot;</b>  matches  the  inbox folder (which is the root in
-       maildir++), other folder names always start with &quot;.&quot;, and nested  fold‐
-       ers  are separated by &quot;.&quot;s, such as <b>folder:.classes.topology</b>. For &quot;file
+       tax  for  maildir  folders  depends  on  your  mail  configuration. For
+       maildir++, <b>folder:&quot;&quot;</b> matches the inbox folder (which  is  the  root  in
+       maildir++),  other folder names always start with &quot;.&quot;, and nested fold‐
+       ers are separated by &quot;.&quot;s, such as <b>folder:.classes.topology</b>. For  &quot;file

        system&quot; maildir, the inbox is typically <b>folder:INBOX</b> and nested folders
        are separated by slashes, such as <b>folder:classes/topology</b>.
 
        system&quot; maildir, the inbox is typically <b>folder:INBOX</b> and nested folders
        are separated by slashes, such as <b>folder:classes/topology</b>.
 

-       Both  <b>path:</b> and <b>folder:</b> will find a message if <u>any</u> copy of that message
+       Both <b>path:</b> and <b>folder:</b> will find a message if <u>any</u> copy of that  message

        is in the specific directory/folder.
 
        is in the specific directory/folder.
 

-       The <b>date:</b> prefix can be used to restrict the results to  only  messages
+       The  <b>date:</b>  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:
 
        within a particular time range (based on the Date: header) with a range
        syntax of:
 


@@ -122,14 +137,23 @@
 
        &lt;initial-timestamp&gt;..&lt;final-timestamp&gt;
 
 
        &lt;initial-timestamp&gt;..&lt;final-timestamp&gt;
 

-       Each  timestamp  is  a  number representing the number of seconds since
+       Each timestamp is a number representing the  number  of  seconds  since

        1970-01-01 00:00:00 UTC.
 
        1970-01-01 00:00:00 UTC.
 

-       The <b>lastmod:</b> prefix can be used to restrict the result by the  database
+       The  <b>lastmod:</b> prefix can be used to restrict the result by the database

        revision  number  of  when  messages  were  last  modified  (tags  were
        revision  number  of  when  messages  were  last  modified  (tags  were

-       added/removed or filenames changed).  This is usually used in  conjunc‐
-       tion  with  the <b>--uuid</b> argument to <b>notmuch</b> <b>search</b> to find messages that
+       added/removed  or filenames changed).  This is usually used in conjunc‐
+       tion with the <b>--uuid</b> argument to <b>notmuch</b> <b>search</b> to find  messages  that

        have changed since an earlier query.
        have changed since an earlier query.

+
+       The  <b>query:</b>  prefix allows queries to refer to previously saved queries
+       added with <a href='../notmuch-config-1/'>notmuch-config</a>(1). Named queries are only available if  not‐
+       much is built with <b>Xapian</b> <b>Field</b> <b>Processors</b> (see below).
+
+       The   <b>property:</b>   prefix   searches  for  messages  with  a  particular
+       &lt;key&gt;=&lt;value&gt; 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.

 </pre>
 
 <h3> &nbsp; Operators</h3>
 </pre>
 
 <h3> &nbsp; Operators</h3>


@@ -194,25 +218,26 @@
 <pre>
        Xapian  (and  hence  notmuch)  prefixes  are either <b>boolean</b>, supporting
        exact matches like &quot;<u>tag:inbox</u>&quot;  or  <b>probabilistic</b>,  supporting  a  more
 <pre>
        Xapian  (and  hence  notmuch)  prefixes  are either <b>boolean</b>, supporting
        exact matches like &quot;<u>tag:inbox</u>&quot;  or  <b>probabilistic</b>,  supporting  a  more

-       flexible <b>term</b> based searching. The prefixes currently supported by not‐
-       much are as follows.
-
-              ┌───────────────────────────┬────────────────────────────┐
-              │Boolean
-              ├───────────────────────────┼────────────────────────────┤
-              │
-              │
-              │       <b>thread:</b>     <b>folder:</b> │        <b>subject:</b>    <b>attach‐</b> │
-              │       <b>path:</b>               │        <b>ment:</b> <b>mimetype:</b>     │
-              └───────────────────────────┴────────────────────────────┘
+       flexible  <b>term</b>  based searching. Certain <b>special</b> prefixes are processed
+       by notmuch in a way not stricly fitting either  of  Xapian&apos;s  built  in
+       styles. The prefixes currently supported by notmuch are as follows.
+
+       <b>Boolean</b>
+              <b>tag:</b>, <b>id:</b>, <b>thread:</b>, <b>folder:</b>, <b>path:</b>, <b>property:</b>
+
+       <b>Probabilistic</b>
+              <b>to:</b>, <b>attachment:</b>, <b>mimetype:</b>
+
+       <b>Special</b>
+              <b>from:</b>, <b>query:</b>, <b>subject:</b>

 </pre>
 
 <h3> &nbsp; Terms and phrases</h3>
 <pre>
 </pre>
 
 <h3> &nbsp; Terms and phrases</h3>
 <pre>

-       In general Xapian distinguishes between lists  of  terms  and  <b>phrases</b>.
+       In  general  Xapian  distinguishes  between lists of terms and <b>phrases</b>.

        Phrases are indicated by double quotes (but beware you probably need to
        Phrases are indicated by double quotes (but beware you probably need to

-       protect those from your shell) and insist that  those  unstemmed  words
-       occur  in  that  order. One useful, but initially surprising feature is
+       protect  those  from  your shell) and insist that those unstemmed words
+       occur in that order. One useful, but initially  surprising  feature  is

        that the following are equivalant ways to write the same phrase.
 
        · &quot;a list of words&quot;
        that the following are equivalant ways to write the same phrase.
 
        · &quot;a list of words&quot;


@@ -241,11 +266,11 @@
 
 <h2>DATE AND TIME SEARCH</h2>
 <pre>
 
 <h2>DATE AND TIME SEARCH</h2>
 <pre>

-       notmuch  understands a variety of standard and natural ways of express‐
+       notmuch understands a variety of standard and natural ways of  express‐

        ing dates and times, both in absolute terms (&quot;2012-10-24&quot;) and in rela‐
        ing dates and times, both in absolute terms (&quot;2012-10-24&quot;) and in rela‐

-       tive  terms (&quot;yesterday&quot;). Any number of relative terms can be combined
-       (&quot;1 hour 25 minutes&quot;) and an absolute date/time can  be  combined  with
-       relative  terms  to  further adjust it. A non-exhaustive description of
+       tive terms (&quot;yesterday&quot;). Any number of relative terms can be  combined
+       (&quot;1  hour  25  minutes&quot;) and an absolute date/time can be combined with
+       relative terms to further adjust it. A  non-exhaustive  description  of

        the syntax supported for absolute and relative terms is given below.
 </pre>
 
        the syntax supported for absolute and relative terms is given below.
 </pre>
 


@@ -253,23 +278,23 @@
 <pre>
        date:&lt;since&gt;..&lt;until&gt;
 
 <pre>
        date:&lt;since&gt;..&lt;until&gt;
 

-       The above expression  restricts  the  results  to  only  messages  from
+       The  above  expression  restricts  the  results  to  only messages from

        &lt;since&gt; to &lt;until&gt;, based on the Date: header.
 
        &lt;since&gt; to &lt;until&gt;, based on the Date: header.
 

-       &lt;since&gt;  and &lt;until&gt; can describe imprecise times, such as &quot;yesterday&quot;.
-       In this case, &lt;since&gt; is taken as the earliest time it  could  describe
+       &lt;since&gt; and &lt;until&gt; can describe imprecise times, such as  &quot;yesterday&quot;.
+       In  this  case, &lt;since&gt; is taken as the earliest time it could describe

        (the beginning of yesterday) and &lt;until&gt; is taken as the latest time it
        (the beginning of yesterday) and &lt;until&gt; is taken as the latest time it

-       could describe (the end of yesterday). Similarly,  date:january..febru‐
+       could  describe (the end of yesterday). Similarly, date:january..febru‐

        ary matches from the beginning of January to the end of February.
 
        ary matches from the beginning of January to the end of February.
 

-       date:&lt;expr&gt;..!  can be used as a shorthand for date:&lt;expr&gt;..&lt;expr&gt;. The
-       expansion takes place before interpretation,  and  thus,  for  example,
-       date:monday..!  matches  from  the beginning of Monday until the end of
-       Monday. (Note that  entering  date:&lt;expr&gt;  without  &quot;..&quot;,  for  example
-       date:yesterday,  won&apos;t work, as it&apos;s not interpreted as a range expres‐
-       sion at all. Again, use date:yesterday..!)
+       date:&lt;expr&gt;..! can be used as a shorthand for date:&lt;expr&gt;..&lt;expr&gt;.  The
+       expansion  takes  place  before  interpretation, and thus, for example,
+       date:monday..! matches from the beginning of Monday until  the  end  of
+       Monday.   With  <b>Xapian</b>  <b>Field</b>  <b>Processor</b> support (see below), non-range
+       date queries such as date:yesterday will work, but otherwise will  give
+       unexpected results; if in doubt use date:yesterday..!

 
 

-       Currently, we do not support  spaces  in  range  expressions.  You  can
+       Currently,  we  do  not  support  spaces  in range expressions. You can

        replace the spaces with &apos;_&apos;, or (in most cases) &apos;-&apos;, or (in some cases)
        leave  the  spaces out altogether. Examples in this man page use spaces
        for clarity.
        replace the spaces with &apos;_&apos;, or (in most cases) &apos;-&apos;, or (in some cases)
        leave  the  spaces out altogether. Examples in this man page use spaces
        for clarity.


@@ -287,15 +312,15 @@
 
        All refer to past, can be repeated and will be accumulated.
 
 
        All refer to past, can be repeated and will be accumulated.
 

-       Units  can  be  abbreviated to any length, with the otherwise ambiguous
+       Units can be abbreviated to any length, with  the  otherwise  ambiguous

        single m being m for minutes and M for months.
 
        single m being m for minutes and M for months.
 

-       Number can also be written out one,  two,  ...,  ten,  dozen,  hundred.
+       Number  can  also  be  written  out one, two, ..., ten, dozen, hundred.

        Additionally, the unit may be preceded by &quot;last&quot; or &quot;this&quot; (e.g., &quot;last
        week&quot; or &quot;this month&quot;).
 
        Additionally, the unit may be preceded by &quot;last&quot; or &quot;this&quot; (e.g., &quot;last
        week&quot; or &quot;this month&quot;).
 

-       When combined with absolute date and time, the relative date  and  time
-       specification  will  be  relative  from the specified absolute date and
+       When  combined  with absolute date and time, the relative date and time
+       specification will be relative from the  specified  absolute  date  and

        time.
 
        Examples: 5M2d, two weeks
        time.
 
        Examples: 5M2d, two weeks


@@ -354,6 +379,24 @@
        Some time zone codes, e.g. UTC, EET.
 </pre>
 
        Some time zone codes, e.g. UTC, EET.
 </pre>
 

+<h2>XAPIAN FIELD PROCESSORS</h2>
+<pre>
+       Certain  optional  features  of the notmuch query processor rely on the
+       presence of the Xapian field processor API. You can determine  if  your
+       notmuch  was  built  against a sufficiently recent version of Xapian by
+       running
+
+          % notmuch config get built_with.field_processor
+
+       Currently the following features require field processor support:
+
+       · non-range date queries, e.g. &quot;date:today&quot;
+
+       · named queries e.g. &quot;query:my_special_query&quot;
+
+       · regular expression searches, e.g. &quot;subject:/^\[SPAM\]/&quot;
+</pre>
+

 <h2>SEE ALSO</h2>
 <pre>
        <a href='../notmuch-1/'>notmuch</a>(1), <a href='../notmuch-config-1/'>notmuch-config</a>(1), <a href='../notmuch-count-1/'>notmuch-count</a>(1), <a href='../notmuch-dump-1/'>notmuch-dump</a>(1),  <a href='../notmuch-hooks-5/'>not‐</a>
 <h2>SEE ALSO</h2>
 <pre>
        <a href='../notmuch-1/'>notmuch</a>(1), <a href='../notmuch-config-1/'>notmuch-config</a>(1), <a href='../notmuch-count-1/'>notmuch-count</a>(1), <a href='../notmuch-dump-1/'>notmuch-dump</a>(1),  <a href='../notmuch-hooks-5/'>not‐</a>


@@ -368,7 +411,7 @@
 
 <h2>COPYRIGHT</h2>
 <pre>
 
 <h2>COPYRIGHT</h2>
 <pre>

-       2009-2015, Carl Worth and many others
+       2009-2017, Carl Worth and many others

 </pre>
 
 </pre>
 

-<h2>0.21</h2>
+<h2>0.24</h2>