From: Daniel Kahn Gillmor <dkg@fifthhorseman.net>
To: Notmuch Mail <notmuch@notmuchmail.org>
Subject: [PATCH v6 04/14] doc: add notmuch-properties(7)
Date: Tue, 17 Oct 2017 15:09:58 -0400 [thread overview]
Message-ID: <20171017191008.8742-5-dkg@fifthhorseman.net> (raw)
In-Reply-To: <20171017191008.8742-1-dkg@fifthhorseman.net>
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.
---
doc/conf.py | 4 +++
doc/index.rst | 1 +
doc/man1/notmuch-dump.rst | 5 ++--
doc/man1/notmuch-restore.rst | 4 ++-
doc/man1/notmuch.rst | 1 +
doc/man7/notmuch-properties.rst | 53 +++++++++++++++++++++++++++++++++++++++
doc/man7/notmuch-search-terms.rst | 4 ++-
7 files changed, 68 insertions(+), 4 deletions(-)
create mode 100644 doc/man7/notmuch-properties.rst
diff --git a/doc/conf.py b/doc/conf.py
index 0e65413d..c7013bec 100644
--- 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 aa6c9f40..4440d93a 100644
--- 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 883e454d..7bc57d29 100644
--- 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 1cfaaaed..b578af1f 100644
--- 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 5e994746..358f42e8 100644
--- 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
index 00000000..ffaa2418
--- /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 c602eadb..637f7777 100644
--- 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)**,
--
2.14.2
next prev parent reply other threads:[~2017-10-17 19:10 UTC|newest]
Thread overview: 24+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-10-17 19:09 cleartext indexing, revision 6 Daniel Kahn Gillmor
2017-10-17 19:09 ` [PATCH v6 01/14] crypto: move into libnotmuch_util Daniel Kahn Gillmor
2017-10-17 19:09 ` [PATCH v6 02/14] crypto: make shared crypto code behave library-like Daniel Kahn Gillmor
2017-10-17 19:09 ` [PATCH v6 03/14] index: implement notmuch_indexopts_t with try_decrypt Daniel Kahn Gillmor
2017-10-19 11:44 ` David Bremner
2017-10-17 19:09 ` Daniel Kahn Gillmor [this message]
2017-10-19 18:21 ` [PATCH v6 04/14] doc: add notmuch-properties(7) Daniel Kahn Gillmor
2017-10-17 19:09 ` [PATCH v6 05/14] properties: add notmuch_message_remove_all_properties_with_prefix() Daniel Kahn Gillmor
2017-10-17 19:10 ` [PATCH v6 06/14] reindex: drop all properties named with prefix "index." Daniel Kahn Gillmor
2017-10-19 11:52 ` David Bremner
2017-10-20 5:24 ` Daniel Kahn Gillmor
2017-10-19 11:54 ` David Bremner
2017-10-20 5:17 ` Daniel Kahn Gillmor
2017-10-17 19:10 ` [PATCH v6 07/14] crypto: index encrypted parts when indexopts try_decrypt is set Daniel Kahn Gillmor
2017-10-17 19:10 ` [PATCH v6 08/14] config: store index.try_default in the database Daniel Kahn Gillmor
2017-10-17 19:10 ` [PATCH v6 09/14] config: define new option index.try_decrypt Daniel Kahn Gillmor
2017-10-17 19:10 ` [PATCH v6 10/14] cli: set up shared command-line arguments for indexing Daniel Kahn Gillmor
2017-10-20 10:49 ` David Bremner
2017-10-17 19:10 ` [PATCH v6 11/14] tests: emacs_fcc_message: allow passing --arguments to notmuch new Daniel Kahn Gillmor
2017-10-17 19:10 ` [PATCH v6 12/14] cli/new: add --try-decrypt=(true|false) Daniel Kahn Gillmor
2017-10-17 19:10 ` [PATCH v6 13/14] cli/insert: " Daniel Kahn Gillmor
2017-10-20 10:57 ` David Bremner
2017-10-17 19:10 ` [PATCH v6 14/14] cli/reindex: " Daniel Kahn Gillmor
2017-10-20 11:14 ` cleartext indexing, revision 6 David Bremner
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://notmuchmail.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20171017191008.8742-5-dkg@fifthhorseman.net \
--to=dkg@fifthhorseman.net \
--cc=notmuch@notmuchmail.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://yhetil.org/notmuch.git/
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).