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 8C3FD6DE0FE6 for ; Fri, 20 Oct 2017 19:26:03 -0700 (PDT) X-Virus-Scanned: Debian amavisd-new at cworth.org X-Spam-Flag: NO X-Spam-Score: -0.022 X-Spam-Level: X-Spam-Status: No, score=-0.022 tagged_above=-999 required=5 tests=[AWL=-0.022] 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 3rloXqrosM9Z for ; Fri, 20 Oct 2017 19:26:03 -0700 (PDT) Received: from che.mayfirst.org (che.mayfirst.org [162.247.75.118]) by arlo.cworth.org (Postfix) with ESMTP id 84DF16DE0941 for ; Fri, 20 Oct 2017 19:25:59 -0700 (PDT) Received: from fifthhorseman.net (ool-6c3a0662.static.optonline.net [108.58.6.98]) by che.mayfirst.org (Postfix) with ESMTPSA id 07F90F9A1 for ; Fri, 20 Oct 2017 22:25:58 -0400 (EDT) Received: by fifthhorseman.net (Postfix, from userid 1000) id 30C0B20CD9; Fri, 20 Oct 2017 22:25:54 -0400 (EDT) From: Daniel Kahn Gillmor To: Notmuch Mail Subject: [PATCH 02/12] doc: add notmuch-properties(7) Date: Fri, 20 Oct 2017 22:25:39 -0400 Message-Id: <20171021022549.2724-3-dkg@fifthhorseman.net> X-Mailer: git-send-email 2.14.2 In-Reply-To: <20171021022549.2724-1-dkg@fifthhorseman.net> References: <20171021022549.2724-1-dkg@fifthhorseman.net> 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: Sat, 21 Oct 2017 02:26:03 -0000 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..8654077c --- /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 = 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