manpages updates for release 0.27

diff --git a/manpages.mdwn b/manpages.mdwn
index b677ae100e915f4b550081bcc67486bc0994f8cf..905b0e89e9478ab3839f0f720aafd6ba7155254e 100644 (file)
--- a/manpages.mdwn
+++ b/manpages.mdwn
@@ -24,4 +24,4 @@ The manual pages are licensed under
 [the GNU General Public License](https://www.gnu.org/licenses/gpl.txt),
 either version 3.0 or at your option any later version.
 
 [the GNU General Public License](https://www.gnu.org/licenses/gpl.txt),
 either version 3.0 or at your option any later version.
 

-<h2>0.26</h2>
+<h2>0.27</h2>

diff --git a/manpages/notmuch-1.mdwn b/manpages/notmuch-1.mdwn
index cb5242fc193c315f427a749e9fcb3aa140c43fbb..cfcb031538fd29819297a1c3ddb85d463b20f2a2 100644 (file)
--- a/manpages/notmuch-1.mdwn
+++ b/manpages/notmuch-1.mdwn
@@ -187,4 +187,4 @@
        2009-2018, Carl Worth and many others
 </pre>
 
        2009-2018, Carl Worth and many others
 </pre>
 

-<h2>0.26</h2>
+<h2>0.27</h2>

diff --git a/manpages/notmuch-address-1.mdwn b/manpages/notmuch-address-1.mdwn
index a62ef711dae704a5f90d8f9a423f9fc590fbb1a5..f612e88c3c6c4fdc61f33d676f8bb77b5fb04742 100644 (file)
--- a/manpages/notmuch-address-1.mdwn
+++ b/manpages/notmuch-address-1.mdwn
@@ -130,4 +130,4 @@
        2009-2018, Carl Worth and many others
 </pre>
 
        2009-2018, Carl Worth and many others
 </pre>
 

-<h2>0.26</h2>
+<h2>0.27</h2>

diff --git a/manpages/notmuch-compact-1.mdwn b/manpages/notmuch-compact-1.mdwn
index dada0065057ccee8f3a361671e1dbc48d1b44211..7d84e9bec3cd84f4cf6ba4f815490a03fefbd51a 100644 (file)
--- a/manpages/notmuch-compact-1.mdwn
+++ b/manpages/notmuch-compact-1.mdwn
@@ -64,4 +64,4 @@
        2009-2018, Carl Worth and many others
 </pre>
 
        2009-2018, Carl Worth and many others
 </pre>
 

-<h2>0.26</h2>
+<h2>0.27</h2>

diff --git a/manpages/notmuch-config-1.mdwn b/manpages/notmuch-config-1.mdwn
index 6a91a06416ad6ee0a9d05dce37b8186a5d2a2d0c..3f68efe158c0adf4cfc9b59f420cff4d99d5cd82 100644 (file)
--- a/manpages/notmuch-config-1.mdwn
+++ b/manpages/notmuch-config-1.mdwn
@@ -241,4 +241,4 @@
        2009-2018, Carl Worth and many others
 </pre>
 
        2009-2018, Carl Worth and many others
 </pre>
 

-<h2>0.26</h2>
+<h2>0.27</h2>

diff --git a/manpages/notmuch-count-1.mdwn b/manpages/notmuch-count-1.mdwn
index f28687a39196fe9622a9461a7d9ed81c3956c2d1..828bff9689296d8cf52d47d42a11ae03101043df 100644 (file)
--- a/manpages/notmuch-count-1.mdwn
+++ b/manpages/notmuch-count-1.mdwn
@@ -77,4 +77,4 @@
        2009-2018, Carl Worth and many others
 </pre>
 
        2009-2018, Carl Worth and many others
 </pre>
 

-<h2>0.26</h2>
+<h2>0.27</h2>

diff --git a/manpages/notmuch-dump-1.mdwn b/manpages/notmuch-dump-1.mdwn
index c939daaf033d211bfe9e80bae0c11784c025c114..d86c5c879c5c05908e5fde4dae9d6651718b1c9d 100644 (file)
--- a/manpages/notmuch-dump-1.mdwn
+++ b/manpages/notmuch-dump-1.mdwn
@@ -117,4 +117,4 @@
        2009-2018, Carl Worth and many others
 </pre>
 
        2009-2018, Carl Worth and many others
 </pre>
 

-<h2>0.26</h2>
+<h2>0.27</h2>

diff --git a/manpages/notmuch-emacs-mua-1.mdwn b/manpages/notmuch-emacs-mua-1.mdwn
index a12594a585ef02c696934d3285dd1c67a5127be2..e99c9f6f2ebc981bcabb647dcad2cf9f79d4352c 100644 (file)
--- a/manpages/notmuch-emacs-mua-1.mdwn
+++ b/manpages/notmuch-emacs-mua-1.mdwn
@@ -92,4 +92,4 @@
        2009-2018, Carl Worth and many others
 </pre>
 
        2009-2018, Carl Worth and many others
 </pre>
 

-<h2>0.26</h2>
+<h2>0.27</h2>

diff --git a/manpages/notmuch-hooks-5.mdwn b/manpages/notmuch-hooks-5.mdwn
index f616177ad73ff7cb121e2aa5f2bdaad7c71d994a..e589de21088ecd8e371d178f49de87f6492187eb 100644 (file)
--- a/manpages/notmuch-hooks-5.mdwn
+++ b/manpages/notmuch-hooks-5.mdwn
@@ -66,4 +66,4 @@
        2009-2018, Carl Worth and many others
 </pre>
 
        2009-2018, Carl Worth and many others
 </pre>
 

-<h2>0.26</h2>
+<h2>0.27</h2>

diff --git a/manpages/notmuch-insert-1.mdwn b/manpages/notmuch-insert-1.mdwn
index bf44bdc4b4a1d9ae48eaa07110d6e7a553c186ff..e7b05b62883e284b44bcfe48e7a53d1bb18c8912 100644 (file)
--- a/manpages/notmuch-insert-1.mdwn
+++ b/manpages/notmuch-insert-1.mdwn
@@ -51,22 +51,28 @@
        <b>--no-hooks</b>
               Prevent hooks from being run.
 
        <b>--no-hooks</b>
               Prevent hooks from being run.
 

+       <b>--world-readable</b>
+              When  writing  mail to the mailbox, allow it to be read by users
+              other than the current user.  Note that this does  not  override
+              umask.   By default, delivered mail is only readable by the cur‐
+              rent user.
+

        <b>--decrypt=(true|nostash|auto|false)</b>
               If <b>true</b> and the message is encrypted, try to decrypt the message
        <b>--decrypt=(true|nostash|auto|false)</b>
               If <b>true</b> and the message is encrypted, try to decrypt the message

-              while indexing, stashing any session keys discovered.  If  <b>auto</b>,
-              and  notmuch  already knows about a session key for the message,
-              it will try decrypting using that session key but will  not  try
-              to  access the user&apos;s secret keys.  If decryption is successful,
-              index the cleartext itself.  Either way, the message  is  always
+              while  indexing, stashing any session keys discovered.  If <b>auto</b>,
+              and notmuch already knows about a session key for  the  message,
+              it  will  try decrypting using that session key but will not try
+              to access the user&apos;s secret keys.  If decryption is  successful,
+              index  the  cleartext itself.  Either way, the message is always

               stored to disk in its original form (ciphertext).
 
               stored to disk in its original form (ciphertext).
 

-              <b>nostash</b>  is  the  same  as  <b>true</b>  except  that it will not stash
+              <b>nostash</b> is the same as  <b>true</b>  except  that  it  will  not  stash

               newly-discovered session keys in the database.
 
               Be aware that the index is likely sufficient (and a stashed ses‐
               newly-discovered session keys in the database.
 
               Be aware that the index is likely sufficient (and a stashed ses‐

-              sion  key  is certainly sufficient) to reconstruct the cleartext
+              sion key is certainly sufficient) to reconstruct  the  cleartext

               of the message itself, so please ensure that the notmuch message
               of the message itself, so please ensure that the notmuch message

-              index  is  adequately  protected.  DO  NOT USE <b>--decrypt=true</b> or
+              index is adequately protected.  DO  NOT  USE  <b>--decrypt=true</b>  or

               <b>--decrypt=nostash</b>  without  considering  the  security  of  your
               index.
 
               <b>--decrypt=nostash</b>  without  considering  the  security  of  your
               index.
 


@@ -75,15 +81,15 @@
 
 <h2>EXIT STATUS</h2>
 <pre>
 
 <h2>EXIT STATUS</h2>
 <pre>

-       This  command  returns  exit  status  0  on  successful  mail delivery,
-       non-zero otherwise. The default is to indicate failed mail delivery  on
-       any  errors, including message file delivery to the filesystem, message
-       indexing to Notmuch database, changing tags, and synchronizing tags  to
-       maildir  flags.  The <b>--keep</b> option may be used to settle for successful
+       This command  returns  exit  status  0  on  successful  mail  delivery,
+       non-zero  otherwise. The default is to indicate failed mail delivery on
+       any errors, including message file delivery to the filesystem,  message
+       indexing  to Notmuch database, changing tags, and synchronizing tags to
+       maildir flags. The <b>--keep</b> option may be used to settle  for  successful

        message file delivery.
 
        This command supports the following special exit status code for errors
        message file delivery.
 
        This command supports the following special exit status code for errors

-       most  likely  to be temporary in nature, e.g. failure to get a database
+       most likely to be temporary in nature, e.g. failure to get  a  database

        write lock.
 
        <b>75</b> <b>(EX</b>_<b>TEMPFAIL)</b>
        write lock.
 
        <b>75</b> <b>(EX</b>_<b>TEMPFAIL)</b>


@@ -95,7 +101,7 @@
 
 <h2>SEE ALSO</h2>
 <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>
+       <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>

        <a href='../notmuch-hooks-5/'>much-hooks</a>(5), <a href='../notmuch-reply-1/'>notmuch-reply</a>(1), <a href='../notmuch-restore-1/'>notmuch-restore</a>(1), <a href='../notmuch-search-1/'>notmuch-search</a>(1),
        <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7), <a href='../notmuch-show-1/'>notmuch-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1)
 </pre>
        <a href='../notmuch-hooks-5/'>much-hooks</a>(5), <a href='../notmuch-reply-1/'>notmuch-reply</a>(1), <a href='../notmuch-restore-1/'>notmuch-restore</a>(1), <a href='../notmuch-search-1/'>notmuch-search</a>(1),
        <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7), <a href='../notmuch-show-1/'>notmuch-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1)
 </pre>


@@ -110,4 +116,4 @@
        2009-2018, Carl Worth and many others
 </pre>
 
        2009-2018, Carl Worth and many others
 </pre>
 

-<h2>0.26</h2>
+<h2>0.27</h2>

diff --git a/manpages/notmuch-new-1.mdwn b/manpages/notmuch-new-1.mdwn
index 345f510b7ae4ed27aee68178deb1b715a08ffc75..2c64aadc967844807d7e71fb98aa86aa2cae97de 100644 (file)
--- a/manpages/notmuch-new-1.mdwn
+++ b/manpages/notmuch-new-1.mdwn
@@ -59,6 +59,11 @@
               index.
 
               See also <b>index.decrypt</b> in <a href='../notmuch-config-1/'>notmuch-config</a>(1).
               index.
 
               See also <b>index.decrypt</b> in <a href='../notmuch-config-1/'>notmuch-config</a>(1).

+
+       <b>--full-scan</b>
+              By  default  notmuch-new  uses  directory   modification   times
+              (mtimes)  to  optimize the scanning of directories for new mail.
+              This option turns that optimization off.

 </pre>
 
 <h2>EXIT STATUS</h2>
 </pre>
 
 <h2>EXIT STATUS</h2>


@@ -87,4 +92,4 @@
        2009-2018, Carl Worth and many others
 </pre>
 
        2009-2018, Carl Worth and many others
 </pre>
 

-<h2>0.26</h2>
+<h2>0.27</h2>

diff --git a/manpages/notmuch-properties-7.mdwn b/manpages/notmuch-properties-7.mdwn
index 45af3a3425205aac528e92967504262a05df962c..eb7537c78e388ff177c4be39e10e3ce4d29623aa 100644 (file)
--- a/manpages/notmuch-properties-7.mdwn
+++ b/manpages/notmuch-properties-7.mdwn
@@ -126,4 +126,4 @@
        2009-2018, Carl Worth and many others
 </pre>
 
        2009-2018, Carl Worth and many others
 </pre>
 

-<h2>0.26</h2>
+<h2>0.27</h2>

diff --git a/manpages/notmuch-reindex-1.mdwn b/manpages/notmuch-reindex-1.mdwn
index 2ca91bec82c7209dd2d1741bd423d25adae9237d..a6beb8d9a1d128245d5ac2f6b86b821e690f8f22 100644 (file)
--- a/manpages/notmuch-reindex-1.mdwn
+++ b/manpages/notmuch-reindex-1.mdwn
@@ -47,12 +47,41 @@
               See also <b>index.decrypt</b> in <a href='../notmuch-config-1/'>notmuch-config</a>(1).
 </pre>
 
               See also <b>index.decrypt</b> in <a href='../notmuch-config-1/'>notmuch-config</a>(1).
 </pre>
 

+<h2>EXAMPLES</h2>
+<pre>
+       A user just received an encrypted message without indexing its  cleart‐
+       ext.   After  reading it (via <b>notmuch</b> <b>show</b> <b>--decrypt=true</b>), they decide
+       that they want to index its cleartext so that they can easily  find  it
+       later and read it without having to have access to their secret keys:
+
+          notmuch reindex --decrypt=true id:1234567@example.com
+
+       A  user  wants  to  change their policy going forward to start indexing
+       cleartext.  But they also want indexed access to the cleartext  of  all
+       previously-received  encrypted  messages.   Some  messages  might  have
+       already been indexed in the clear (as in the example above).  They  can
+       ask notmuch to just reindex the not-yet-indexed messages:
+
+          notmuch config set index.decrypt true
+          notmuch reindex tag:encrypted and not property:index.decryption=success
+
+       Later,  the user changes their mind, and wants to stop indexing cleart‐
+       ext (perhaps their threat model has changed, or their  trust  in  their
+       index store has been shaken).  They also want to clear all of their old
+       cleartext from the index.  Note that they compact the  database  after‐
+       ward as a workaround for <u>https://trac.xapian.org/ticket/742</u>:
+
+          notmuch config set index.decrypt false
+          notmuch reindex property:index.decryption=success
+          notmuch compact
+</pre>
+

 <h2>SEE ALSO</h2>
 <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>
-       <a href='../notmuch-hooks-5/'>much-hooks</a>(5),   <a href='../notmuch-insert-1/'>notmuch-insert</a>(1),  <a href='../notmuch-new-1/'>notmuch-new</a>(1),  <a href='../notmuch-reply-1/'>notmuch-reply</a>(1),
-       <a href='../notmuch-restore-1/'>notmuch-restore</a>(1),  <a href='../notmuch-search-1/'>notmuch-search</a>(1),  <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7),  <a href='../notmuch-show-1/'>not‐</a>
-       <a href='../notmuch-show-1/'>much-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1)
+       <a href='../notmuch-1/'>notmuch</a>(1),  <a href='../notmuch-compact-1/'>notmuch-compact</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/'>notmuch-hooks</a>(5),  <a href='../notmuch-insert-1/'>notmuch-insert</a>(1),  <a href='../notmuch-new-1/'>notmuch-new</a>(1),
+       <a href='../notmuch-reply-1/'>notmuch-reply</a>(1),     <a href='../notmuch-restore-1/'>notmuch-restore</a>(1),    <a href='../notmuch-search-1/'>notmuch-search</a>(1),    <a href='../notmuch-search-terms-7/'>not‐</a>
+       <a href='../notmuch-search-terms-7/'>much-search-terms</a>(7), <a href='../notmuch-show-1/'>notmuch-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1)

 </pre>
 
 <h2>AUTHOR</h2>
 </pre>
 
 <h2>AUTHOR</h2>


@@ -65,4 +94,4 @@
        2009-2018, Carl Worth and many others
 </pre>
 
        2009-2018, Carl Worth and many others
 </pre>
 

-<h2>0.26</h2>
+<h2>0.27</h2>

diff --git a/manpages/notmuch-reply-1.mdwn b/manpages/notmuch-reply-1.mdwn
index ff43d2868f7fb6f66dc2451898c91b081350eb1a..30910bc406aa239282d228106686dff7cbd428cf 100644 (file)
--- a/manpages/notmuch-reply-1.mdwn
+++ b/manpages/notmuch-reply-1.mdwn
@@ -129,4 +129,4 @@
        2009-2018, Carl Worth and many others
 </pre>
 
        2009-2018, Carl Worth and many others
 </pre>
 

-<h2>0.26</h2>
+<h2>0.27</h2>

diff --git a/manpages/notmuch-restore-1.mdwn b/manpages/notmuch-restore-1.mdwn
index 1b22757c80d7d5e9608b9d8a4c8190415fe8100b..b4ae210eeca4b2d6172c9802138b3405465f8b43 100644 (file)
--- a/manpages/notmuch-restore-1.mdwn
+++ b/manpages/notmuch-restore-1.mdwn
@@ -102,4 +102,4 @@
        2009-2018, Carl Worth and many others
 </pre>
 
        2009-2018, Carl Worth and many others
 </pre>
 

-<h2>0.26</h2>
+<h2>0.27</h2>

diff --git a/manpages/notmuch-search-1.mdwn b/manpages/notmuch-search-1.mdwn
index b7ba7dba80094de47fa930190be7c418a080069a..4adb33bdf0d4e91cdff6fd9bdd0189c26f7c06ac 100644 (file)
--- a/manpages/notmuch-search-1.mdwn
+++ b/manpages/notmuch-search-1.mdwn
@@ -147,9 +147,9 @@
        message having multiple filenames.
 
           % notmuch search date:today.. and tag:bad-news
        message having multiple filenames.
 
           % notmuch search date:today.. and tag:bad-news

-          thread:0000000000063c10 Today [1/1] Some Persun; To the bone (inbox unread)
-          thread:0000000000063c25 Today [1/1(2)] Ann Other; Bears (inbox unread)
-          thread:0000000000063c00 Today [1/1] A Thurd; Bites, stings, sad feelings (inbox unread)
+          thread:0000000000063c10 Today [1/1] Some Persun; To the bone (bad-news inbox unread)
+          thread:0000000000063c25 Today [1/1(2)] Ann Other; Bears (bad-news inbox unread)
+          thread:0000000000063c00 Today [1/1] A Thurd; Bites, stings, sad feelings (bad-news unread)

 </pre>
 
 <h2>EXIT STATUS</h2>
 </pre>
 
 <h2>EXIT STATUS</h2>


@@ -179,4 +179,4 @@
        2009-2018, Carl Worth and many others
 </pre>
 
        2009-2018, Carl Worth and many others
 </pre>
 

-<h2>0.26</h2>
+<h2>0.27</h2>

diff --git a/manpages/notmuch-search-terms-7.mdwn b/manpages/notmuch-search-terms-7.mdwn
index 0259d42a486a33bb2c7cb16696e13b7aa3a4fdb0..e6b87a36e581f87ef010622d04e01959d13eb8b3 100644 (file)
--- a/manpages/notmuch-search-terms-7.mdwn
+++ b/manpages/notmuch-search-terms-7.mdwn
@@ -45,7 +45,7 @@
        results  to  those  whose  value  matches  a  regular  expression  (see
        <b>regex</b>(7)) delimited with //, for example:
 
        results  to  those  whose  value  matches  a  regular  expression  (see
        <b>regex</b>(7)) delimited with //, for example:
 

-          notmuch search &apos;from:/bob@.*[.]example[.]com/&apos;
+          notmuch search &apos;from:&quot;/bob@.*[.]example[.]com/&quot;&apos;

 
        <b>from:&lt;name-or-address&gt;</b> <b>or</b> <b>from:/&lt;regex&gt;/</b>
               The  <b>from:</b>  prefix  is  used to match the name or address of the
 
        <b>from:&lt;name-or-address&gt;</b> <b>or</b> <b>from:/&lt;regex&gt;/</b>
               The  <b>from:</b>  prefix  is  used to match the name or address of the


@@ -86,50 +86,65 @@
               messages).  These thread ID values can be seen in the first col‐
               umn of output from <b>notmuch</b> <b>search</b>
 
               messages).  These thread ID values can be seen in the first col‐
               umn of output from <b>notmuch</b> <b>search</b>
 

+       <b>thread:{&lt;notmuch</b> <b>query&gt;}</b>
+              If notmuch is built with <b>Xapian</b> <b>Field</b>  <b>Processors</b>  (see  below),
+              threads may be searched for indirectly by providing an arbitrary
+              notmuch query in <b>{}</b>. For example, the following returns  threads
+              containing  a  message from mallory and one (not necessarily the
+              same message) with Subject containing the word &quot;crypto&quot;.
+
+                 % notmuch search &apos;thread:&quot;{from:mallory}&quot; and thread:&quot;{subject:crypto}&quot;&apos;
+
+              The performance of such queries can vary wildly.  To  understand
+              this, the user should think of the query <b>thread:{&lt;something&gt;}</b> as
+              expanding to all of the thread IDs which match <b>&lt;something&gt;</b>; not‐
+              much then performs a second search using the expanded query.
+

        <b>path:&lt;directory-path&gt;</b> <b>or</b> <b>path:&lt;directory-path&gt;/**</b> <b>or</b> <b>path:/&lt;regex&gt;/</b>
               The <b>path:</b> prefix searches for email messages that are in partic‐
        <b>path:&lt;directory-path&gt;</b> <b>or</b> <b>path:&lt;directory-path&gt;/**</b> <b>or</b> <b>path:/&lt;regex&gt;/</b>
               The <b>path:</b> prefix searches for email messages that are in partic‐

-              ular  directories  within  the mail store. The directory must be
-              specified relative to the top-level  maildir  (and  without  the
+              ular directories within the mail store. The  directory  must  be
+              specified  relative  to  the  top-level maildir (and without the

               leading slash). By default, <b>path:</b> matches messages in the speci‐
               leading slash). By default, <b>path:</b> matches messages in the speci‐

-              fied directory only. The &quot;/**&quot; suffix can be used to match  mes‐
-              sages  in  the  specified  directory  and all its subdirectories
-              recursively. <b>path:&quot;&quot;</b> matches messages in the root  of  the  mail
+              fied  directory only. The &quot;/**&quot; suffix can be used to match mes‐
+              sages 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.
 
               store and, likewise, <b>path:**</b> matches all messages.
 

-              <b>path:</b>  will find a message if <u>any</u> copy of that message is in the
+              <b>path:</b> will find a message if <u>any</u> copy of that message is in  the

               specific directory.
 
        <b>folder:&lt;maildir-folder&gt;</b> <b>or</b> <b>folder:/&lt;regex&gt;/</b>
               specific directory.
 
        <b>folder:&lt;maildir-folder&gt;</b> <b>or</b> <b>folder:/&lt;regex&gt;/</b>

-              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
+              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 includes messages in the &quot;new&quot; and &quot;cur&quot; subdirec‐
               maildir, this includes messages in the &quot;new&quot; and &quot;cur&quot; subdirec‐

-              tories.  The  exact  syntax  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
+              tories. The exact syntax 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 folders 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>.
 
               always start with &quot;.&quot;, and nested folders 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>.
 

-              <b>folder:</b>  will  find  a message if <u>any</u> copy of that message is in
+              <b>folder:</b> will find a message if <u>any</u> copy of that  message  is  in

               the specific folder.
 
        <b>date:&lt;since&gt;..&lt;until&gt;</b> <b>or</b> <b>date:&lt;date&gt;</b>
               the specific folder.
 
        <b>date:&lt;since&gt;..&lt;until&gt;</b> <b>or</b> <b>date:&lt;date&gt;</b>

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

-              See <b>DATE</b> <b>AND</b> <b>TIME</b> <b>SEARCH</b> below for details on the range  expres‐
+              See  <b>DATE</b> <b>AND</b> <b>TIME</b> <b>SEARCH</b> below for details on the range expres‐

               sion, and supported syntax for &lt;since&gt; and &lt;until&gt; date and time
               expressions.
 
               sion, and supported syntax for &lt;since&gt; and &lt;until&gt; date and time
               expressions.
 

-              The time range can also be specified  using  timestamps  with  a
-              syntax of:
+              The  time  range  can also be specified using timestamps without
+              including the date prefix using a syntax of:

 
               &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 1970-01-01 00:00:00 UTC.
+              Each timestamp is a number representing the  number  of  seconds
+              since  1970-01-01 00:00:00 UTC. Specifying a time range this way
+              is considered legacy and predates the date prefix.

 
        <b>lastmod:&lt;initial-revision&gt;..&lt;final-revision&gt;</b>
               The <b>lastmod:</b> prefix can be used to restrict the  result  by  the
 
        <b>lastmod:&lt;initial-revision&gt;..&lt;final-revision&gt;</b>
               The <b>lastmod:</b> prefix can be used to restrict the  result  by  the


@@ -260,13 +275,32 @@
        will not.
 </pre>
 
        will not.
 </pre>
 

+<h3> &nbsp; Quoting</h3>
+<pre>
+       Double  quotes  are  also  used  by the notmuch query parser to protect
+       boolean terms, regular expressions, or subqueries containing spaces  or
+       other special characters, e.g.
+
+          tag:&quot;a tag&quot;
+
+          folder:&quot;/^.*/(Junk|Spam)$/&quot;
+
+          thread:&quot;{from:mallory and date:2009}&quot;
+
+       As  with  phrases, you need to protect the double quotes from the shell
+       e.g.
+
+          % notmuch search &apos;folder:&quot;/^.*/(Junk|Spam)$/&quot;&apos;
+          % notmuch search &apos;thread:&quot;{from:mallory and date:2009}&quot; and thread:{to:mallory}&apos;
+</pre>
+

 <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>
 


@@ -274,15 +308,21 @@
 <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.
 

+       If specifying a time range using timestamps  in  conjunction  with  the
+       date  prefix,  each  timestamp must be preceded by @ (ASCII hex 40). As
+       above, each timestamp is a number representing the  number  of  seconds
+       since 1970-01-01 00:00:00 UTC. For example:
+          date:@&lt;initial-timestamp&gt;..@&lt;final-timestamp&gt;
+

        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
        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


@@ -391,6 +431,8 @@
        · named queries e.g. &quot;query:my_special_query&quot;
 
        · regular expression searches, e.g. &quot;subject:/^\[SPAM\]/&quot;
        · named queries e.g. &quot;query:my_special_query&quot;
 
        · regular expression searches, e.g. &quot;subject:/^\[SPAM\]/&quot;

+
+       · thread subqueries, e.g. &quot;thread:{from:bob}&quot;

 </pre>
 
 <h2>SEE ALSO</h2>
 </pre>
 
 <h2>SEE ALSO</h2>


@@ -411,4 +453,4 @@
        2009-2018, Carl Worth and many others
 </pre>
 
        2009-2018, Carl Worth and many others
 </pre>
 

-<h2>0.26</h2>
+<h2>0.27</h2>

diff --git a/manpages/notmuch-show-1.mdwn b/manpages/notmuch-show-1.mdwn
index 4902b5acffdd090b0c3609e4fec8c0f43980d4dc..39f18455ed3b7317d28420f2b82ada0d36047f65 100644 (file)
--- a/manpages/notmuch-show-1.mdwn
+++ b/manpages/notmuch-show-1.mdwn
@@ -110,7 +110,7 @@
               supported with --format=json and --format=sexp), and the  multi‐
               part/signed part will be replaced by the signed data.
 
               supported with --format=json and --format=sexp), and the  multi‐
               part/signed part will be replaced by the signed data.
 

-       <b>--decrypt=(false|auto|true)</b>
+       <b>--decrypt=(false|auto|true|stash)</b>

               If  <b>true</b>, decrypt any MIME encrypted parts found in the selected
               content  (i.e.  &quot;multipart/encrypted&quot;  parts).  Status  of   the
               decryption  will  be  reported  (currently  only  supported with
               If  <b>true</b>, decrypt any MIME encrypted parts found in the selected
               content  (i.e.  &quot;multipart/encrypted&quot;  parts).  Status  of   the
               decryption  will  be  reported  (currently  only  supported with


@@ -118,50 +118,81 @@
               the  multipart/encrypted  part will be replaced by the decrypted
               content.
 
               the  multipart/encrypted  part will be replaced by the decrypted
               content.
 

-              If <b>auto</b>, and a session key is already  known  for  the  message,
-              then  it  will  be decrypted, but notmuch will not try to access
+              <b>stash</b> behaves like <b>true</b>, but upon successful decryption it  will
+              also  stash the message&apos;s session key in the database, and index
+              the cleartext of the message, enabling automatic  decryption  in
+              the future.
+
+              If  <b>auto</b>,  and  a  session key is already known for the message,
+              then it will be decrypted, but notmuch will not  try  to  access

               the user&apos;s keys.
 
               Use <b>false</b> to avoid even automatic decryption.
 
               the user&apos;s keys.
 
               Use <b>false</b> to avoid even automatic decryption.
 

-              Non-automatic decryption expects a functioning  <b>gpg-agent</b>(1)  to
-              provide any needed credentials. Without one, the decryption will
+              Non-automatic  decryption  (<b>stash</b>  or  <b>true</b>, in the absence of a
+              stashed session key) expects a functioning <b>gpg-agent</b>(1) to  pro‐
+              vide  any  needed  credentials. Without one, the decryption will

               fail.
 
               fail.
 

-              Note: <b>true</b> implies --verify.
+              Note: setting either <b>true</b> or <b>stash</b> here implies <b>--verify</b>.
+
+              Here is a table that summarizes each of these policies:
+
+                       ┌──────────────┬───────┬──────┬──────┬───────┐
+                       │              │ false │ auto │ true │ stash │
+                       ├──────────────┼───────┼──────┼──────┼───────┤
+                       │Show  cleart‐ │       │ X    │ X    │ X     │
+                       │ext  if  ses‐ │       │      │      │       │
+                       │sion  key  is │       │      │      │       │
+                       │already known │       │      │      │       │
+                       ├──────────────┼───────┼──────┼──────┼───────┤
+                       │Use    secret │       │      │ X    │ X     │
+                       │keys to  show │       │      │      │       │
+                       │cleartext     │       │      │      │       │
+                       ├──────────────┼───────┼──────┼──────┼───────┤
+                       │Stash     any │       │      │      │ X     │
+                       │newly  recov‐ │       │      │      │       │
+                       │ered  session │       │      │      │       │
+                       │keys,   rein‐ │       │      │      │       │
+                       │dexing   mes‐ │       │      │      │       │
+                       │sage if found │       │      │      │       │
+                       └──────────────┴───────┴──────┴──────┴───────┘
+
+              Note: <b>--decrypt=stash</b> requires write  access  to  the  database.
+              Otherwise, <b>notmuch</b> <b>show</b> operates entirely in read-only mode.

 
               Default: <b>auto</b>
 
        <b>--exclude=(true|false)</b>
               Specify whether to omit threads only matching search.tag_exclude
               from the search results (the default) or not. In either case the
 
               Default: <b>auto</b>
 
        <b>--exclude=(true|false)</b>
               Specify whether to omit threads only matching search.tag_exclude
               from the search results (the default) or not. In either case the

-              excluded message will be marked with the  exclude  flag  (except
+              excluded  message  will  be marked with the exclude flag (except

               when output=mbox when there is nowhere to put the flag).
 
               If  --entire-thread  is  specified  then  complete  threads  are
               when output=mbox when there is nowhere to put the flag).
 
               If  --entire-thread  is  specified  then  complete  threads  are

-              returned regardless (with  the  excluded  flag  being  set  when
-              appropriate)  but threads that only match in an excluded message
+              returned  regardless  (with  the  excluded  flag  being set when
+              appropriate) but threads that only match in an excluded  message

               are not returned when <b>--exclude=true.</b>
 
               The default is <b>--exclude=true.</b>
 
        <b>--body=(true|false)</b>
               are not returned when <b>--exclude=true.</b>
 
               The default is <b>--exclude=true.</b>
 
        <b>--body=(true|false)</b>

-              If true (the default) <b>notmuch</b> <b>show</b> includes the  bodies  of  the
-              messages   in   the   output;  if  false,  bodies  are  omitted.
-              <b>--body=false</b> is only implemented for the json and  sexp  formats
+              If  true  (the  default) <b>notmuch</b> <b>show</b> includes the bodies of the
+              messages  in  the  output;  if  false,   bodies   are   omitted.
+              <b>--body=false</b>  is  only implemented for the json and sexp formats

               and it is incompatible with <b>--part</b> <b>&gt;</b> <b>0.</b>
 
               This is useful if the caller only needs the headers as body-less
               output is much faster and substantially smaller.
 
        <b>--include-html</b>
               and it is incompatible with <b>--part</b> <b>&gt;</b> <b>0.</b>
 
               This is useful if the caller only needs the headers as body-less
               output is much faster and substantially smaller.
 
        <b>--include-html</b>

-              Include &quot;text/html&quot; parts as part of the output (currently  only
-              supported  with  --format=json  and  --format=sexp). By default,
-              unless  <b>--part=N</b>  is  used  to  select  a   specific   part   or
+              Include  &quot;text/html&quot; parts as part of the output (currently only
+              supported with --format=json  and  --format=sexp).  By  default,
+              unless   <b>--part=N</b>   is   used  to  select  a  specific  part  or

               <b>--include-html</b> is used to include all &quot;text/html&quot; parts, no part
               with content type &quot;text/html&quot; is included in the output.
 
               <b>--include-html</b> is used to include all &quot;text/html&quot; parts, no part
               with content type &quot;text/html&quot; is included in the output.
 

-       A common use of <b>notmuch</b> <b>show</b> is to display a  single  thread  of  email
+       A  common  use  of  <b>notmuch</b> <b>show</b> is to display a single thread of email

        messages. For this, use a search term of &quot;thread:&lt;thread-id&gt;&quot; as can be
        seen in the first column of output from the <b>notmuch</b> <b>search</b> command.
 </pre>
        messages. For this, use a search term of &quot;thread:&lt;thread-id&gt;&quot; as can be
        seen in the first column of output from the <b>notmuch</b> <b>search</b> command.
 </pre>


@@ -177,8 +208,8 @@
 
 <h2>SEE ALSO</h2>
 <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>
-       <a href='../notmuch-hooks-5/'>much-hooks</a>(5),   <a href='../notmuch-insert-1/'>notmuch-insert</a>(1),  <a href='../notmuch-new-1/'>notmuch-new</a>(1),  <a href='../notmuch-reply-1/'>notmuch-reply</a>(1),
+       <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>
+       <a href='../notmuch-hooks-5/'>much-hooks</a>(5),  <a href='../notmuch-insert-1/'>notmuch-insert</a>(1),  <a href='../notmuch-new-1/'>notmuch-new</a>(1),   <a href='../notmuch-reply-1/'>notmuch-reply</a>(1),

        <a href='../notmuch-restore-1/'>notmuch-restore</a>(1),  <a href='../notmuch-search-1/'>notmuch-search</a>(1),  <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7),  <a href='../notmuch-tag-1/'>not‐</a>
        <a href='../notmuch-tag-1/'>much-tag</a>(1)
 </pre>
        <a href='../notmuch-restore-1/'>notmuch-restore</a>(1),  <a href='../notmuch-search-1/'>notmuch-search</a>(1),  <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7),  <a href='../notmuch-tag-1/'>not‐</a>
        <a href='../notmuch-tag-1/'>much-tag</a>(1)
 </pre>


@@ -193,4 +224,4 @@
        2009-2018, Carl Worth and many others
 </pre>
 
        2009-2018, Carl Worth and many others
 </pre>
 

-<h2>0.26</h2>
+<h2>0.27</h2>

diff --git a/manpages/notmuch-tag-1.mdwn b/manpages/notmuch-tag-1.mdwn
index 354ce463352cb9da47f5d6b6b63fb085221cdfe8..45d9e5509b7ec8b4ffd93484583811b60a4b1ed1 100644 (file)
--- a/manpages/notmuch-tag-1.mdwn
+++ b/manpages/notmuch-tag-1.mdwn
@@ -116,4 +116,4 @@
        2009-2018, Carl Worth and many others
 </pre>
 
        2009-2018, Carl Worth and many others
 </pre>
 

-<h2>0.26</h2>
+<h2>0.27</h2>