From 5dd59d2a5e41320eb494cfdf39c3370c4a2beda4 Mon Sep 17 00:00:00 2001 From: David Bremner Date: Thu, 23 Jan 2014 09:02:47 -0400 Subject: [PATCH] man: update notmuch-dump man page for new default. Actually the previous default was not documented explicitely. I moved the batch-tag section first because it seemed that the formats were previously documented in order default, other. --- man/man1/notmuch-dump.1 | 54 +++++++++++++++++++++-------------------- 1 file changed, 28 insertions(+), 26 deletions(-) diff --git a/man/man1/notmuch-dump.1 b/man/man1/notmuch-dump.1 index 0c52d1b7..16e72eb0 100644 --- a/man/man1/notmuch-dump.1 +++ b/man/man1/notmuch-dump.1 @@ -26,6 +26,34 @@ incremental backup than the native database files.) Notmuch restore supports two plain text dump formats, both with one message-id per line, followed by a list of tags. +.RS 4 +.TP 4 +.B batch-tag + +The default +.B batch-tag +dump format is intended to more robust against malformed message-ids +and tags containing whitespace or non-\fBascii\fR(7) characters. +Each line has the form + +.RS 4 +.RI "+<" "encoded-tag" "> " "" "+<" "encoded-tag" "> ... -- " "" " id:<" quoted-message-id > + +Tags are hex-encoded by replacing every byte not matching the regex +.B [A-Za-z0-9@=.,_+-] +with +.B %nn +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). + +.RE +.RE + .RS 4 .TP 4 .B sup @@ -52,32 +80,6 @@ that tags with spaces will not be correctly restored with this format. .RE -.RE -.RS 4 -.TP 4 -.B batch-tag - -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. -Each line has the form - -.RS 4 -.RI "+<" "encoded-tag" "> " "" "+<" "encoded-tag" "> ... -- " "" " id:<" quoted-message-id > - -Tags are hex-encoded by replacing every byte not matching the regex -.B [A-Za-z0-9@=.,_+-] -with -.B %nn -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). - .RE -- 2.43.0