[PATCH v2 5/5] man: Update notmuch-dump(1) and notmuch-restore(1)

diff --git a/3e/2f9a6ec773d95dc0de4b65904555df91ac38b7 b/3e/2f9a6ec773d95dc0de4b65904555df91ac38b7
new file mode 100644 (file)
index 0000000..f36ba0a
--- /dev/null
+++ b/3e/2f9a6ec773d95dc0de4b65904555df91ac38b7
@@ -0,0 +1,124 @@
+Return-Path: <amdragon@mit.edu>\r
+X-Original-To: notmuch@notmuchmail.org\r
+Delivered-To: notmuch@notmuchmail.org\r
+Received: from localhost (localhost [127.0.0.1])\r
+       by olra.theworths.org (Postfix) with ESMTP id 6EECC431FB6\r
+       for <notmuch@notmuchmail.org>; Tue, 25 Dec 2012 19:49:07 -0800 (PST)\r
+X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
+X-Spam-Flag: NO\r
+X-Spam-Score: -0.7\r
+X-Spam-Level: \r
+X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5\r
+       tests=[RCVD_IN_DNSWL_LOW=-0.7] autolearn=disabled\r
+Received: from olra.theworths.org ([127.0.0.1])\r
+       by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
+       with ESMTP id SB6n4hlUr+Jp for <notmuch@notmuchmail.org>;\r
+       Tue, 25 Dec 2012 19:49:03 -0800 (PST)\r
+Received: from dmz-mailsec-scanner-1.mit.edu (DMZ-MAILSEC-SCANNER-1.MIT.EDU\r
+       [18.9.25.12])\r
+       by olra.theworths.org (Postfix) with ESMTP id 47EBF431FBD\r
+       for <notmuch@notmuchmail.org>; Tue, 25 Dec 2012 19:49:00 -0800 (PST)\r
+X-AuditID: 1209190c-b7fa86d000001d37-85-50da73ab5ccc\r
+Received: from mailhub-auth-1.mit.edu ( [18.9.21.35])\r
+       by dmz-mailsec-scanner-1.mit.edu (Symantec Messaging Gateway) with SMTP\r
+       id 36.51.07479.BA37AD05; Tue, 25 Dec 2012 22:48:59 -0500 (EST)\r
+Received: from outgoing.mit.edu (OUTGOING-AUTH.MIT.EDU [18.7.22.103])\r
+       by mailhub-auth-1.mit.edu (8.13.8/8.9.2) with ESMTP id qBQ3muBG023722; \r
+       Tue, 25 Dec 2012 22:48:56 -0500\r
+Received: from drake.dyndns.org (c-76-21-105-205.hsd1.ca.comcast.net\r
+       [76.21.105.205]) (authenticated bits=0)\r
+       (User authenticated as amdragon@ATHENA.MIT.EDU)\r
+       by outgoing.mit.edu (8.13.6/8.12.4) with ESMTP id qBQ3mrnW013185\r
+       (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NOT);\r
+       Tue, 25 Dec 2012 22:48:55 -0500 (EST)\r
+Received: from amthrax by drake.dyndns.org with local (Exim 4.77)\r
+       (envelope-from <amdragon@mit.edu>)\r
+       id 1Tnhz9-0002z4-1j; Tue, 25 Dec 2012 22:48:51 -0500\r
+From: Austin Clements <amdragon@MIT.EDU>\r
+To: notmuch@notmuchmail.org\r
+Subject: [PATCH v2 5/5] man: Update notmuch-dump(1) and notmuch-restore(1)\r
+Date: Tue, 25 Dec 2012 22:48:43 -0500\r
+Message-Id: <1356493723-11085-6-git-send-email-amdragon@mit.edu>\r
+X-Mailer: git-send-email 1.7.10.4\r
+In-Reply-To: <1356493723-11085-1-git-send-email-amdragon@mit.edu>\r
+References: <1356493723-11085-1-git-send-email-amdragon@mit.edu>\r
+X-Brightmail-Tracker:\r
+ H4sIAAAAAAAAA+NgFrrNIsWRmVeSWpSXmKPExsUixCmqrLu6+FaAwZ3vAhY3WrsZLZqmO1us\r
+       nstjcf3mTGYHFo+ds+6ye9y6/5rd49mqW8weWw69Zw5gieKySUnNySxLLdK3S+DKuHvpOEvB\r
+       TsGKKYdamBoYN/J1MXJySAiYSHTs38kOYYtJXLi3nq2LkYtDSGAfo8T2FW9ZIZwNjBLXH39j\r
+       hnAuMkn0Tr3HBOHMZZS4umAvE0g/m4CGxLb9yxlBbBEBaYmdd2ezgtjMAnkSDx9tBdshLOAl\r
+       ce/gc7A4i4CqRMelF8wgNq+Ag8SvE/eh7lCU6H42AegODg5OAUeJnQ/qQMJCQCUTH55nmsDI\r
+       v4CRYRWjbEpulW5uYmZOcWqybnFyYl5eapGuoV5uZoleakrpJkZwuEny7GB8c1DpEKMAB6MS\r
+       Dy/Hr5sBQqyJZcWVuYcYJTmYlER5txfcChDiS8pPqcxILM6ILyrNSS0+xCjBwawkwuv8Eaic\r
+       NyWxsiq1KB8mJc3BoiTOeznlpr+QQHpiSWp2ampBahFMVoaDQ0mC910R0FDBotT01Iq0zJwS\r
+       hDQTByfIcB6g4TdBaniLCxJzizPTIfKnGHU5Gl7eeMooxJKXn5cqJc57AaRIAKQoozQPbg4s\r
+       TbxiFAd6S5h3D0gVDzDFwE16BbSECWhJLN8NkCUliQgpqQZGiTBBo9V6NZcuXZMSZanT+9C+\r
+       kaux5dC2980Llr82qrze/OX8Co9dfCbyy30franvfCe2W6/2+ONzHMvlH8Q9jo/f9G8ZV+uk\r
+       9vyI6qX1QlmX0nme6i4VWnqF+6V71OHr34vFc45/vSK6e+vLNTaqKR5+3U1SrW8v7F/47d6h\r
+       le8/W1/WF5ZOV2Ipzkg01GIuKk4EANFpoN3uAgAA\r
+X-BeenThere: notmuch@notmuchmail.org\r
+X-Mailman-Version: 2.1.13\r
+Precedence: list\r
+List-Id: "Use and development of the notmuch mail system."\r
+       <notmuch.notmuchmail.org>\r
+List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
+       <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
+List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
+List-Post: <mailto:notmuch@notmuchmail.org>\r
+List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
+List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
+       <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
+X-List-Received-Date: Wed, 26 Dec 2012 03:49:08 -0000\r
+\r
+Describe the new batch-tag format.  For notmuch-restore, rather than\r
+half-heartedly duplicating the description, we now cite notmuch-dump.\r
+---\r
+ man/man1/notmuch-dump.1    |   11 +++++++----\r
+ man/man1/notmuch-restore.1 |    6 ++----\r
+ 2 files changed, 9 insertions(+), 8 deletions(-)\r
+\r
+diff --git a/man/man1/notmuch-dump.1 b/man/man1/notmuch-dump.1\r
+index 770b00f..7bd6def 100644\r
+--- a/man/man1/notmuch-dump.1\r
++++ b/man/man1/notmuch-dump.1\r
+@@ -64,13 +64,16 @@ and tags containing whitespace or non-\fBascii\fR(7) characters.\r
+ Each line has the form\r
+ \r
+ .RS 4\r
+-.RI "+<" "encoded-tag" "> " "" "+<" "encoded-tag" "> ... -- " "" " id:<" encoded-message-id >\r
++.RI "+<" "encoded-tag" "> " "" "+<" "encoded-tag" "> ... -- " "" " id:<" quoted-message-id >\r
+ \r
+-where encoded means that every byte not matching the regex\r
++Tags are hex-encoded by replacing every byte not matching the regex\r
+ .B [A-Za-z0-9@=.,_+-]\r
+-is replace by\r
++with\r
+ .B %nn\r
+-where nn is the two digit hex encoding.\r
++where nn is the two digit hex encoding.  The message ID is a valid Xapian\r
++query, quoted using Xapian boolean term quoting rules: if the ID contains\r
++whitespace or a close paren or starts with a double quote, it must be\r
++enclosed in double quotes and double quotes inside the ID must be doubled.\r
+ The astute reader will notice this is a special case of the batch input\r
+ format for \fBnotmuch-tag\fR(1); note that the single message-id query is\r
+ mandatory for \fBnotmuch-restore\fR(1).\r
+diff --git a/man/man1/notmuch-restore.1 b/man/man1/notmuch-restore.1\r
+index 6bba628..78fef52 100644\r
+--- a/man/man1/notmuch-restore.1\r
++++ b/man/man1/notmuch-restore.1\r
+@@ -57,10 +57,8 @@ sup calls them).\r
+ The\r
+ .B batch-tag\r
+ dump format is intended to more robust against malformed message-ids\r
+-and tags containing whitespace or non-\fBascii\fR(7) characters.  This\r
+-format hex-escapes all characters those outside of a small character\r
+-set, intended to be suitable for e.g. pathnames in most UNIX-like\r
+-systems.\r
++and tags containing whitespace or non-\fBascii\fR(7) characters.  See\r
++\fBnotmuch-dump\fR(1) for details on this format.\r
+ \r
+ .B "notmuch restore"\r
+ updates the maildir flags according to tag changes if the\r
+-- \r
+1.7.10.4\r
+\r