85/18bbb9fc1413c2ab503eea03b7d13123e190e5

   1 Return-Path: <bremner@tethera.net>\r
   2 X-Original-To: notmuch@notmuchmail.org\r
   3 Delivered-To: notmuch@notmuchmail.org\r
   4 Received: from localhost (localhost [127.0.0.1])\r
   5         by olra.theworths.org (Postfix) with ESMTP id 0FAE44143AB\r
   6         for <notmuch@notmuchmail.org>; Sat, 14 Jan 2012 17:40:56 -0800 (PST)\r
   7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
   8 X-Spam-Flag: NO\r
   9 X-Spam-Score: -2.3\r
  10 X-Spam-Level: \r
  11 X-Spam-Status: No, score=-2.3 tagged_above=-999 required=5\r
  12         tests=[RCVD_IN_DNSWL_MED=-2.3] autolearn=disabled\r
  13 Received: from olra.theworths.org ([127.0.0.1])\r
  14         by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
  15         with ESMTP id ZpbHcXGIaKUJ for <notmuch@notmuchmail.org>;\r
  16         Sat, 14 Jan 2012 17:40:53 -0800 (PST)\r
  17 Received: from tempo.its.unb.ca (tempo.its.unb.ca [131.202.1.21])\r
  18         (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits))\r
  19         (No client certificate requested)\r
  20         by olra.theworths.org (Postfix) with ESMTPS id E45BD41438E\r
  21         for <notmuch@notmuchmail.org>; Sat, 14 Jan 2012 17:40:51 -0800 (PST)\r
  22 Received: from zancas.localnet\r
  23         (fctnnbsc36w-156034076032.pppoe-dynamic.High-Speed.nb.bellaliant.net\r
  24         [156.34.76.32]) (authenticated bits=0)\r
  25         by tempo.its.unb.ca (8.13.8/8.13.8) with ESMTP id q0F1efBU008574\r
  26         (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NO);\r
  27         Sat, 14 Jan 2012 21:40:44 -0400\r
  28 Received: from bremner by zancas.localnet with local (Exim 4.77)\r
  29         (envelope-from <bremner@tethera.net>)\r
  30         id 1RmF5N-000431-MG; Sat, 14 Jan 2012 21:40:41 -0400\r
  31 From: David Bremner <david@tethera.net>\r
  32 To: notmuch@notmuchmail.org\r
  33 Subject: [PATCH v3 08/10] notmuch-{dump,\r
  34         restore}.1: document new format options\r
  35 Date: Sat, 14 Jan 2012 21:40:22 -0400\r
  36 Message-Id: <1326591624-15493-9-git-send-email-david@tethera.net>\r
  37 X-Mailer: git-send-email 1.7.7.3\r
  38 In-Reply-To: <1326591624-15493-1-git-send-email-david@tethera.net>\r
  39 References: <874nwxbkhr.fsf@zancas.localnet>\r
  40         <1326591624-15493-1-git-send-email-david@tethera.net>\r
  41 Cc: David Bremner <bremner@debian.org>\r
  42 X-BeenThere: notmuch@notmuchmail.org\r
  43 X-Mailman-Version: 2.1.13\r
  44 Precedence: list\r
  45 List-Id: "Use and development of the notmuch mail system."\r
  46         <notmuch.notmuchmail.org>\r
  47 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
  48         <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
  49 List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
  50 List-Post: <mailto:notmuch@notmuchmail.org>\r
  51 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
  52 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
  53         <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
  54 X-List-Received-Date: Sun, 15 Jan 2012 01:40:56 -0000\r
  55 \r
  56 From: David Bremner <bremner@debian.org>\r
  57 \r
  58 More or less arbitrarily, notmuch-dump.1 gets the more detailed\r
  59 description of the format.\r
  60 ---\r
  61  man/man1/notmuch-dump.1    |   59 ++++++++++++++++++++++++++++++++++++++++++-\r
  62  man/man1/notmuch-restore.1 |   60 ++++++++++++++++++++++++++++++++++++++-----\r
  63  2 files changed, 111 insertions(+), 8 deletions(-)\r
  64 \r
  65 diff --git a/man/man1/notmuch-dump.1 b/man/man1/notmuch-dump.1\r
  66 index 9ccf35d..f4f7964 100644\r
  67 --- a/man/man1/notmuch-dump.1\r
  68 +++ b/man/man1/notmuch-dump.1\r
  69 @@ -5,7 +5,8 @@ notmuch-dump \- Creates a plain-text dump of the tags of each message.\r
  70  .SH SYNOPSIS\r
  71  \r
  72  .B "notmuch dump"\r
  73 -.RI "[ <" filename "> ] [--]"\r
  74 +.RI "[ <" filename "> ]"\r
  75 +.RB  [ "\-\-format=(sup|notmuch)"  "] [--]"\r
  76  .RI "[ <" search-term ">...]"\r
  77  \r
  78  .SH DESCRIPTION\r
  79 @@ -20,6 +21,62 @@ recreated from the messages themselves.  The output of notmuch dump is\r
  80  therefore the only critical thing to backup (and much more friendly to\r
  81  incremental backup than the native database files.)\r
  82  \r
  83 +.TP 4\r
  84 +.B \-\-format=(sup|notmuch)\r
  85 +\r
  86 +Notmuch restore supports two plain text dump formats, both with one message-id\r
  87 +per line, followed by a list of tags.\r
  88 +\r
  89 +.RS 4\r
  90 +.TP 4\r
  91 +.B sup\r
  92 +\r
  93 +The\r
  94 +.B sup\r
  95 +dump file format is specifically chosen to be\r
  96 +compatible with the format of files produced by sup-dump.\r
  97 +So if you've previously been using sup for mail, then the\r
  98 +.B "notmuch restore"\r
  99 +command provides you a way to import all of your tags (or labels as\r
 100 +sup calls them).\r
 101 +Each line has the following form\r
 102 +\r
 103 +.RS 4\r
 104 +.RI < message-id >\r
 105 +.B (\r
 106 +.RI < tag "> ..."\r
 107 +.B )\r
 108 +\r
 109 +with zero or more tags are separated by spaces. Note that (malformed)\r
 110 +message-ids may contained arbitrary non-null characters. Note also\r
 111 +that tags with spaces will not be correctly restored with this format.\r
 112 +\r
 113 +.RE\r
 114 +\r
 115 +.RE\r
 116 +.RS 4\r
 117 +.TP 4\r
 118 +.B notmuch\r
 119 +\r
 120 +The\r
 121 +.B notmuch\r
 122 +dump format is intended to more robust against malformed message-ids\r
 123 +and tags containing whitespace or non-\fBascii\fR(7) characters.\r
 124 +Each line has the form\r
 125 +\r
 126 +.RS 4\r
 127 +.RI < encoded-message-id "> <" encoded-tag "> ..."\r
 128 +\r
 129 +where encoded means that every byte not matching the regex\r
 130 +.B [A-Za-z0-9+-_@=.:,]\r
 131 +is replace by\r
 132 +.B %nn\r
 133 +where nn is the two digit hex encoding.\r
 134 +\r
 135 +\r
 136 +.RE\r
 137 +\r
 138 +\r
 139  With no search terms, a dump of all messages in the database will be\r
 140  generated.  A "--" argument instructs notmuch that the\r
 141  remaining arguments are search terms.\r
 142 diff --git a/man/man1/notmuch-restore.1 b/man/man1/notmuch-restore.1\r
 143 index 2191df0..3fb0e99 100644\r
 144 --- a/man/man1/notmuch-restore.1\r
 145 +++ b/man/man1/notmuch-restore.1\r
 146 @@ -5,7 +5,7 @@ notmuch-restore \- Restores the tags from the given file (see notmuch dump).\r
 147  .SH SYNOPSIS\r
 148  \r
 149  .B "notmuch restore"\r
 150 -.RB [ "--accumulate" ]\r
 151 +.RI  [  options "...]"\r
 152  .RI "[ <" filename "> ]"\r
 153  \r
 154  .SH DESCRIPTION\r
 155 @@ -15,21 +15,67 @@ Restores the tags from the given file (see\r
 156  \r
 157  The input is read from the given filename, if any, or from stdin.\r
 158  \r
 159 -Note: The dump file format is specifically chosen to be\r
 160 +\r
 161 +Supported options for\r
 162 +.B restore\r
 163 +include\r
 164 +.RS 4\r
 165 +.TP 4\r
 166 +.B \-\-accumulate\r
 167 +\r
 168 +The union of the existing and new tags is applied, instead of\r
 169 +replacing each message's tags as they are read in from the dump file.\r
 170 +\r
 171 +.RE\r
 172 +.RS 4\r
 173 +.TP 4\r
 174 +.B \-\-format=(sup|notmuch|auto)\r
 175 +\r
 176 +Notmuch restore supports two plain text dump formats, with one message-id\r
 177 +per line, followed by a list of tags.\r
 178 +For details of the actual formats, see \fBnotmuch-dump\fR(1).\r
 179 +\r
 180 +.RS 4\r
 181 +.TP 4\r
 182 +.B sup\r
 183 +\r
 184 +The\r
 185 +.B sup\r
 186 +dump file format is specifically chosen to be\r
 187  compatible with the format of files produced by sup-dump.\r
 188  So if you've previously been using sup for mail, then the\r
 189  .B "notmuch restore"\r
 190  command provides you a way to import all of your tags (or labels as\r
 191  sup calls them).\r
 192  \r
 193 -The --accumulate switch causes the union of the existing and new tags to be\r
 194 -applied, instead of replacing each message's tags as they are read in from the\r
 195 -dump file.\r
 196 +.RE\r
 197 +.RS 4\r
 198 +.TP 4\r
 199 +.B notmuch\r
 200  \r
 201 -See \fBnotmuch-search-terms\fR(7)\r
 202 -for details of the supported syntax for <search-terms>.\r
 203 +The\r
 204 +.B notmuch\r
 205 +dump format is intended to more robust against malformed message-ids\r
 206 +and tags containing whitespace or non-\fBascii\fR(7) characters.  This\r
 207 +format hex-escapes all characters those outside of a small character\r
 208 +set, intended to be suitable for e.g. pathnames in most UNIX-like\r
 209 +systems.\r
 210  \r
 211  .RE\r
 212 +\r
 213 +.RS 4\r
 214 +.TP 4\r
 215 +.B auto\r
 216 +\r
 217 +This option (the default) tries to guess the format from the\r
 218 +input. For correctly formed input in either supported format, this\r
 219 +heuristic, based the fact that notmuch format contains no parentheses,\r
 220 +should be accurate.\r
 221 +\r
 222 +.RE\r
 223 +\r
 224 +.RE\r
 225 +\r
 226  .SH SEE ALSO\r
 227  \r
 228  \fBnotmuch\fR(1), \fBnotmuch-config\fR(1), \fBnotmuch-count\fR(1),\r
 229 -- \r
 230 1.7.7.3\r
 231 \r