From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <amdragon@mit.edu>
Received: from localhost (localhost [127.0.0.1])
	by olra.theworths.org (Postfix) with ESMTP id 28AD8431FC3
	for <notmuch@notmuchmail.org>; Sun, 30 Dec 2012 22:42:55 -0800 (PST)
X-Virus-Scanned: Debian amavisd-new at olra.theworths.org
X-Spam-Flag: NO
X-Spam-Score: -0.7
X-Spam-Level: 
X-Spam-Status: No, score=-0.7 tagged_above=-999 required=5
	tests=[RCVD_IN_DNSWL_LOW=-0.7] autolearn=disabled
Received: from olra.theworths.org ([127.0.0.1])
	by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)
	with ESMTP id Gru7nVWGMBCd for <notmuch@notmuchmail.org>;
	Sun, 30 Dec 2012 22:42:53 -0800 (PST)
Received: from dmz-mailsec-scanner-5.mit.edu (DMZ-MAILSEC-SCANNER-5.MIT.EDU
	[18.7.68.34])
	by olra.theworths.org (Postfix) with ESMTP id BBE8F431FAF
	for <notmuch@notmuchmail.org>; Sun, 30 Dec 2012 22:42:52 -0800 (PST)
X-AuditID: 12074422-b7f616d000000e7c-31-50e133ec8b70
Received: from mailhub-auth-1.mit.edu ( [18.9.21.35])
	by dmz-mailsec-scanner-5.mit.edu (Symantec Messaging Gateway) with SMTP
	id 96.D2.03708.CE331E05; Mon, 31 Dec 2012 01:42:52 -0500 (EST)
Received: from outgoing.mit.edu (OUTGOING-AUTH.MIT.EDU [18.7.22.103])
	by mailhub-auth-1.mit.edu (8.13.8/8.9.2) with ESMTP id qBV6goBA028411; 
	Mon, 31 Dec 2012 01:42:50 -0500
Received: from drake.dyndns.org (c-76-21-105-205.hsd1.ca.comcast.net
	[76.21.105.205]) (authenticated bits=0)
	(User authenticated as amdragon@ATHENA.MIT.EDU)
	by outgoing.mit.edu (8.13.6/8.12.4) with ESMTP id qBV6glis009883
	(version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NOT);
	Mon, 31 Dec 2012 01:42:49 -0500 (EST)
Received: from amthrax by drake.dyndns.org with local (Exim 4.77)
	(envelope-from <amdragon@mit.edu>)
	id 1TpZ5C-0000in-9F; Mon, 31 Dec 2012 01:42:46 -0500
From: Austin Clements <amdragon@MIT.EDU>
To: notmuch@notmuchmail.org
Subject: [PATCH v4 5/5] man: Update notmuch-dump(1) and notmuch-restore(1)
Date: Mon, 31 Dec 2012 01:42:42 -0500
Message-Id: <1356936162-2589-6-git-send-email-amdragon@mit.edu>
X-Mailer: git-send-email 1.7.10.4
In-Reply-To: <1356936162-2589-1-git-send-email-amdragon@mit.edu>
References: <1356936162-2589-1-git-send-email-amdragon@mit.edu>
X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFnrOIsWRmVeSWpSXmKPExsUixCmqrPvG+GGAwcb/vBY3WrsZLZqmO1us
	nstjcf3mTGaLNyvnsTqweuycdZfd4/DXhSwet+6/Zvd4tuoWs8eWQ++ZA1ijuGxSUnMyy1KL
	9O0SuDLuXjrOUrBTsGLKoRamBsaNfF2MnBwSAiYSe+7cYIawxSQu3FvP1sXIxSEksI9R4sX1
	GcwQzgZGiSMPH0FlLjJJrL00E8qZyyixe/sJRpB+NgENiW37l4PZIgLSEjvvzmYFKWIWaGKU
	uLZpLhtIQljAS6LrxSd2EJtFQFXiUuNzVhCbV8Be4vynBVCHKEp0P5sAVs8p4CCx89ksFhBb
	CKhm997zjBMY+RcwMqxilE3JrdLNTczMKU5N1i1OTszLSy3SNdXLzSzRS00p3cQICkN2F6Ud
	jD8PKh1iFOBgVOLh3fD/QYAQa2JZcWXuIUZJDiYlUV4vg4cBQnxJ+SmVGYnFGfFFpTmpxYcY
	JTiYlUR432oB5XhTEiurUovyYVLSHCxK4rzXUm76CwmkJ5akZqemFqQWwWRlODiUJHitjIAa
	BYtS01Mr0jJzShDSTBycIMN5gIbbgNTwFhck5hZnpkPkTzHqcjS8vPGUUYglLz8vVUqc1xik
	SACkKKM0D24OLH28YhQHekuYVxKkigeYeuAmvQJawgS0RIvhAciSkkSElFQDo39+/Onb72/Z
	vgk/tmXZVh/3NLb71vy2cSu/u05t1jc09Vip9dH96pnD0wVe87ek1nUvOmd8YeWqa/wa026t
	iXx4+NW7mol516Q7Oi031/TGmlWw3l10U/THzAU1szv1tBin9OXadnpZSz3SlFoaH+p2+d2R
	KRc9rN4INTBKzllYsS2hJbuYX4mlOCPRUIu5qDgRAEotscj6AgAA
Cc: tomi.ollila@iki.fi
X-BeenThere: notmuch@notmuchmail.org
X-Mailman-Version: 2.1.13
Precedence: list
List-Id: "Use and development of the notmuch mail system."
	<notmuch.notmuchmail.org>
List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,
	<mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>
List-Archive: <http://notmuchmail.org/pipermail/notmuch>
List-Post: <mailto:notmuch@notmuchmail.org>
List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>
List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,
	<mailto:notmuch-request@notmuchmail.org?subject=subscribe>
X-List-Received-Date: Mon, 31 Dec 2012 06:42:55 -0000

Describe the new batch-tag format.  For notmuch-restore, rather than
half-heartedly duplicating the description, we now cite notmuch-dump.
---
 man/man1/notmuch-dump.1    |   11 +++++++----
 man/man1/notmuch-restore.1 |    6 ++----
 2 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/man/man1/notmuch-dump.1 b/man/man1/notmuch-dump.1
index 770b00f..7bd6def 100644
--- a/man/man1/notmuch-dump.1
+++ b/man/man1/notmuch-dump.1
@@ -64,13 +64,16 @@ and tags containing whitespace or non-\fBascii\fR(7) characters.
 Each line has the form
 
 .RS 4
-.RI "+<" "encoded-tag" "> " "" "+<" "encoded-tag" "> ... -- " "" " id:<" encoded-message-id >
+.RI "+<" "encoded-tag" "> " "" "+<" "encoded-tag" "> ... -- " "" " id:<" quoted-message-id >
 
-where encoded means that every byte not matching the regex
+Tags are hex-encoded by replacing every byte not matching the regex
 .B [A-Za-z0-9@=.,_+-]
-is replace by
+with
 .B %nn
-where nn is the two digit hex encoding.
+where nn is the two digit hex encoding.  The message ID is a valid Xapian
+query, quoted using Xapian boolean term quoting rules: if the ID contains
+whitespace or a close paren or starts with a double quote, it must be
+enclosed in double quotes and double quotes inside the ID must be doubled.
 The astute reader will notice this is a special case of the batch input
 format for \fBnotmuch-tag\fR(1); note that the single message-id query is
 mandatory for \fBnotmuch-restore\fR(1).
diff --git a/man/man1/notmuch-restore.1 b/man/man1/notmuch-restore.1
index 6bba628..78fef52 100644
--- a/man/man1/notmuch-restore.1
+++ b/man/man1/notmuch-restore.1
@@ -57,10 +57,8 @@ sup calls them).
 The
 .B batch-tag
 dump format is intended to more robust against malformed message-ids
-and tags containing whitespace or non-\fBascii\fR(7) characters.  This
-format hex-escapes all characters those outside of a small character
-set, intended to be suitable for e.g. pathnames in most UNIX-like
-systems.
+and tags containing whitespace or non-\fBascii\fR(7) characters.  See
+\fBnotmuch-dump\fR(1) for details on this format.
 
 .B "notmuch restore"
 updates the maildir flags according to tag changes if the
-- 
1.7.10.4