doc: add notmuch-properties(7)

We will want a user-facing place to record details about the use of
notmuch properties shortly.  This establishes a new manual page for
that purpose.

diff --git a/doc/conf.py b/doc/conf.py
index 0e65413d917aec68b71c8314b280e7f729de661a..c7013bece1df5bad288d6b1a9c6c7d73e9feac2b 100644 (file)
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -99,6 +99,10 @@ man_pages = [
      u'incorporate new mail into the notmuch database',
      [notmuch_authors], 1),
 
+    ('man7/notmuch-properties', 'notmuch-properties',
+     u'notmuch message property conventions and documentation',
+     [notmuch_authors], 7),
+
     ('man1/notmuch-reindex', 'notmuch-reindex',
      u're-index matching messages',
      [notmuch_authors], 1),

diff --git a/doc/index.rst b/doc/index.rst
index aa6c9f40462c5c89afae747041ddbf9075a4e157..4440d93aad285ba1d3da14d692ba9f54c47af3c6 100644 (file)
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -18,6 +18,7 @@ Contents:
    man5/notmuch-hooks
    man1/notmuch-insert
    man1/notmuch-new
+   man7/notmuch-properties
    man1/notmuch-reindex
    man1/notmuch-reply
    man1/notmuch-restore

diff --git a/doc/man1/notmuch-dump.rst b/doc/man1/notmuch-dump.rst
index 883e454d5cb4aab180614bb334202dafce04fdf0..7bc57d29468250e9a11e51ea5e7ce49a5ecde7d7 100644 (file)
--- a/doc/man1/notmuch-dump.rst
+++ b/doc/man1/notmuch-dump.rst
@@ -85,8 +85,8 @@ Supported options for **dump** include
 
         Output per-message (key,value) metadata.  Each line starts
         with "#= ", followed by a message id, and a space separated
-        list of key=value pairs.  Ids, keys and values are hex
-        encoded if needed.
+        list of key=value pairs.  Ids, keys and values are hex encoded
+        if needed.  See **notmuch-properties(7)** for more details.
 
       **tags**
 
@@ -116,6 +116,7 @@ SEE ALSO
 **notmuch-hooks(5)**,
 **notmuch-insert(1)**,
 **notmuch-new(1)**,
+**notmuch-properties(7)**,
 **notmuch-reply(1)**,
 **notmuch-restore(1)**,
 **notmuch-search(1)**,

diff --git a/doc/man1/notmuch-restore.rst b/doc/man1/notmuch-restore.rst
index 1cfaaaed401e8b77745407deeb78a8ed624c1aeb..b578af1fbf19ca6b5afdb479cac1ecdf2645a214 100644 (file)
--- a/doc/man1/notmuch-restore.rst
+++ b/doc/man1/notmuch-restore.rst
@@ -65,7 +65,8 @@ Supported options for **restore** include
           Restore per-message (key,value) metadata.  Each line starts
           with "#= ", followed by a message id, and a space separated
           list of key=value pairs.  Ids, keys and values are hex
-          encoded if needed.
+          encoded if needed.  See **notmuch-properties(7)** for more
+          details.
 
         **tags**
 
@@ -96,6 +97,7 @@ SEE ALSO
 **notmuch-hooks(5)**,
 **notmuch-insert(1)**,
 **notmuch-new(1)**,
+**notmuch-properties(7)**,
 **notmuch-reply(1)**,
 **notmuch-search(1)**,
 **notmuch-search-terms(7)**,

diff --git a/doc/man1/notmuch.rst b/doc/man1/notmuch.rst
index 5e99474600087dfe37d1c102d5ffa62e2ae109eb..358f42e8d5bef9335a9649839b0e73289ddadc61 100644 (file)
--- a/doc/man1/notmuch.rst
+++ b/doc/man1/notmuch.rst
@@ -169,6 +169,7 @@ SEE ALSO
 **notmuch-hooks(5)**,
 **notmuch-insert(1)**,
 **notmuch-new(1)**,
+**notmuch-properties(7)**,
 **notmuch-reindex(1)**,
 **notmuch-reply(1)**,
 **notmuch-restore(1)**,

diff --git a/doc/man7/notmuch-properties.rst b/doc/man7/notmuch-properties.rst
new file mode 100644 (file)
index 0000000..8654077
--- /dev/null
+++ b/doc/man7/notmuch-properties.rst
@@ -0,0 +1,53 @@
+==================
+notmuch-properties
+==================
+
+SYNOPSIS
+========
+
+**notmuch** **count** **property:**\ <*key*>=<*value*>
+
+**notmuch** **search** **property:**\ <*key*>=<*value*>
+
+**notmuch** **show** **property:**\ <*key*>=<*value*>
+
+**notmuch** **reindex** **property:**\ <*key*>=<*value*>
+
+**notmuch** **tag** +<*tag*> **property:**\ <*key*>=<*value*>
+
+
+**notmuch** **dump** **--include=properties**
+
+**notmuch** **restore** **--include=properties**
+
+DESCRIPTION
+===========
+
+Several notmuch commands can search for, modify, add or remove
+properties associated with specific messages.  Properties are
+key/value pairs, and a message can have more than one key/value pair
+for the same key.
+
+While users can select based on a specific property in their search
+terms with the prefix **property:**, the notmuch command-line
+interface does not provide mechanisms for modifying properties
+directly to the user.
+
+Instead, message properties are expected to be set and used
+programmatically, according to logic in notmuch itself, or in
+extensions to it.
+
+Extensions to notmuch which make use of properties are encouraged to
+report the specific properties used to the upstream notmuch project,
+as a way of avoiding collisions in the property namespace.
+
+SEE ALSO
+========
+
+**notmuch(1)**,
+**notmuch-dump(1)**,
+**notmuch-insert(1)**,
+**notmuch-new(1)**,
+**notmuch-reindex(1)**,
+**notmuch-restore(1)**,
+***notmuch-search-terms(7)**

diff --git a/doc/man7/notmuch-search-terms.rst b/doc/man7/notmuch-search-terms.rst
index c602eadbe01b2dccfbcba02788c77b93f6135737..637f7777dd932f6c027f966797654f09f4538e04 100644 (file)
--- a/doc/man7/notmuch-search-terms.rst
+++ b/doc/man7/notmuch-search-terms.rst
@@ -159,7 +159,8 @@ below).
 The **property:** prefix searches for messages with a particular
 <key>=<value> 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.
+present on a given message with several different values.  See
+**notmuch-properties(7)** for more details.
 
 Operators
 ---------
@@ -429,6 +430,7 @@ SEE ALSO
 **notmuch-insert(1)**,
 **notmuch-new(1)**,
 **notmuch-reindex(1)**,
+**notmuch-properties(1)**,
 ***notmuch-reply(1)**,
 **notmuch-restore(1)**,
 **notmuch-search(1)**,