d0/4f4cdf6e85e274a30d666a6b6582066eda4ef6

   1 Return-Path: <nex@nexoid.at>\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 919EE431FBD\r
   6         for <notmuch@notmuchmail.org>; Wed,  5 Dec 2012 23:33:20 -0800 (PST)\r
   7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
   8 X-Amavis-Alert: BAD HEADER SECTION, Duplicate header field: "References"\r
   9 X-Spam-Flag: NO\r
  10 X-Spam-Score: 0.001\r
  11 X-Spam-Level: \r
  12 X-Spam-Status: No, score=0.001 tagged_above=-999 required=5\r
  13         tests=[FREEMAIL_FROM=0.001] autolearn=disabled\r
  14 Received: from olra.theworths.org ([127.0.0.1])\r
  15         by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
  16         with ESMTP id 5dW4bqkAbNC1 for <notmuch@notmuchmail.org>;\r
  17         Wed,  5 Dec 2012 23:33:16 -0800 (PST)\r
  18 Received: from mail.nexoid.at (www.nexoid.at [178.79.130.240])\r
  19         (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits))\r
  20         (No client certificate requested)\r
  21         by olra.theworths.org (Postfix) with ESMTPS id 58632431FBC\r
  22         for <notmuch@notmuchmail.org>; Wed,  5 Dec 2012 23:33:16 -0800 (PST)\r
  23 Received: by mail.nexoid.at (Postfix, from userid 1000)\r
  24         id C0A3C11C111; Thu,  6 Dec 2012 08:33:12 +0100 (CET)\r
  25 From: Peter Feigl <craven@gmx.net>\r
  26 To: notmuch@notmuchmail.org\r
  27 Subject: [PATCH v3 5/5] Updating man pages for new S-Expression output format.\r
  28 Date: Thu,  6 Dec 2012 08:33:09 +0100\r
  29 Message-Id: <1354779189-12231-6-git-send-email-craven@gmx.net>\r
  30 X-Mailer: git-send-email 1.8.0\r
  31 In-Reply-To: <1354779189-12231-1-git-send-email-craven@gmx.net>\r
  32 References: <1354779189-12231-1-git-send-email-craven@gmx.net>\r
  33 In-Reply-To: <1354632382-15609-1-git-send-email-craven@gmx.net>\r
  34 References: <1354632382-15609-1-git-send-email-craven@gmx.net>\r
  35 X-BeenThere: notmuch@notmuchmail.org\r
  36 X-Mailman-Version: 2.1.13\r
  37 Precedence: list\r
  38 List-Id: "Use and development of the notmuch mail system."\r
  39         <notmuch.notmuchmail.org>\r
  40 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
  41         <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
  42 List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
  43 List-Post: <mailto:notmuch@notmuchmail.org>\r
  44 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
  45 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
  46         <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
  47 X-List-Received-Date: Thu, 06 Dec 2012 07:33:20 -0000\r
  48 \r
  49 Add sections about the new S-Expression output format (--format=sexp) to\r
  50 the notmuch-search, notmuch-reply and notmuch-show man pages.\r
  51 ---\r
  52  man/man1/notmuch-reply.1  | 14 ++++++++++----\r
  53  man/man1/notmuch-search.1 | 15 ++++++++-------\r
  54  man/man1/notmuch-show.1   | 36 ++++++++++++++++++++++++++++--------\r
  55  3 files changed, 46 insertions(+), 19 deletions(-)\r
  56 \r
  57 diff --git a/man/man1/notmuch-reply.1 b/man/man1/notmuch-reply.1\r
  58 index d264060..f71d764 100644\r
  59 --- a/man/man1/notmuch-reply.1\r
  60 +++ b/man/man1/notmuch-reply.1\r
  61 @@ -37,7 +37,7 @@ Supported options for\r
  62  include\r
  63  .RS\r
  64  .TP 4\r
  65 -.BR \-\-format= ( default | json | headers\-only )\r
  66 +.BR \-\-format= ( default | json | sexp | headers\-only )\r
  67  .RS\r
  68  .TP 4\r
  69  .BR default\r
  70 @@ -48,6 +48,11 @@ Produces JSON output containing headers for a reply message and the\r
  71  contents of the original message. This output can be used by a client\r
  72  to create a reply message intelligently.\r
  73  .TP\r
  74 +.BR sexp\r
  75 +Produces S-Expression output containing headers for a reply message and\r
  76 +the contents of the original message. This output can be used by a client\r
  77 +to create a reply message intelligently.\r
  78 +.TP\r
  79  .BR headers\-only\r
  80  Only produces In\-Reply\-To, References, To, Cc, and Bcc headers.\r
  81  .RE\r
  82 @@ -74,8 +79,8 @@ user's addresses.\r
  83  \r
  84  Decrypt any MIME encrypted parts found in the selected content\r
  85  (ie. "multipart/encrypted" parts). Status of the decryption will be\r
  86 -reported (currently only supported with --format=json) and the\r
  87 -multipart/encrypted part will be replaced by the decrypted\r
  88 +reported (currently only supported with --format=json and --format=sexp)\r
  89 +and the multipart/encrypted part will be replaced by the decrypted\r
  90  content.\r
  91  .RE\r
  92  \r
  93 @@ -89,7 +94,8 @@ id:<message-id>), but it can be useful to reply to several messages at\r
  94  once. For example, when a series of patches are sent in a single\r
  95  thread, replying to the entire thread allows for the reply to comment\r
  96  on issues found in multiple patches. The default format supports\r
  97 -replying to multiple messages at once, but the JSON format does not.\r
  98 +replying to multiple messages at once, but the JSON and S-Expression\r
  99 +format does not.\r
 100  .RE\r
 101  .RE\r
 102  \r
 103 diff --git a/man/man1/notmuch-search.1 b/man/man1/notmuch-search.1\r
 104 index 6ccd3b8..0aff348 100644\r
 105 --- a/man/man1/notmuch-search.1\r
 106 +++ b/man/man1/notmuch-search.1\r
 107 @@ -25,9 +25,9 @@ Supported options for\r
 108  include\r
 109  .RS 4\r
 110  .TP 4\r
 111 -.BR \-\-format= ( json | text )\r
 112 +.BR \-\-format= ( json | sexp | text )\r
 113  \r
 114 -Presents the results in either JSON or plain-text (default).\r
 115 +Presents the results in either JSON, S-Expressions or plain-text (default).\r
 116  .RE\r
 117  \r
 118  .RS 4\r
 119 @@ -49,7 +49,7 @@ the authors of the thread and the subject.\r
 120  \r
 121  Output the thread IDs of all threads with any message matching the\r
 122  search terms, either one per line (\-\-format=text) or as a JSON array\r
 123 -(\-\-format=json).\r
 124 +(\-\-format=json) or an S-Expression list (\-\-format=sexp).\r
 125  .RE\r
 126  .RS 4\r
 127  .TP 4\r
 128 @@ -57,22 +57,23 @@ search terms, either one per line (\-\-format=text) or as a JSON array\r
 129  \r
 130  Output the message IDs of all messages matching the search terms,\r
 131  either one per line (\-\-format=text) or as a JSON array\r
 132 -(\-\-format=json).\r
 133 +(\-\-format=json) or as an S-Expression list (\-\-format=sexp).\r
 134  .RE\r
 135  .RS 4\r
 136  .TP 4\r
 137  .B files\r
 138  \r
 139  Output the filenames of all messages matching the search terms, either\r
 140 -one per line (\-\-format=text) or as a JSON array (\-\-format=json).\r
 141 +one per line (\-\-format=text) or as a JSON array (\-\-format=json) or\r
 142 +as an S-Expression list (\-\-format=sexp).\r
 143  .RE\r
 144  .RS 4\r
 145  .TP 4\r
 146  .B tags\r
 147  \r
 148  Output all tags that appear on any message matching the search terms,\r
 149 -either one per line (\-\-format=text) or as a JSON array\r
 150 -(\-\-format=json).\r
 151 +either one per line (\-\-format=text) or as a JSON array (\-\-format=json)\r
 152 +or as an S-Expression list (\-\-format=sexp).\r
 153  .RE\r
 154  .RE\r
 155  \r
 156 diff --git a/man/man1/notmuch-show.1 b/man/man1/notmuch-show.1\r
 157 index 4481f21..bd41c48 100644\r
 158 --- a/man/man1/notmuch-show.1\r
 159 +++ b/man/man1/notmuch-show.1\r
 160 @@ -31,12 +31,14 @@ If true,\r
 161  outputs all messages in the thread of any message matching the search\r
 162  terms; if false, it outputs only the matching messages. For\r
 163  .B --format=json\r
 164 +and\r
 165 +.B --format=sexp\r
 166  this defaults to true.  For other formats, this defaults to false.\r
 167  .RE\r
 168  \r
 169  .RS 4\r
 170  .TP 4\r
 171 -.B \-\-format=(text|json|mbox|raw)\r
 172 +.B \-\-format=(text|json|sexp|mbox|raw)\r
 173  \r
 174  .RS 4\r
 175  .TP 4\r
 176 @@ -60,11 +62,29 @@ format is more robust than the text format for automated\r
 177  processing. The nested structure of multipart MIME messages is\r
 178  reflected in nested JSON output. By default JSON output includes all\r
 179  messages in a matching thread; that is, by default,\r
 180 +\r
 181  .B \-\-format=json\r
 182  sets\r
 183  .B "\-\-entire\-thread"\r
 184  The caller can disable this behaviour by setting\r
 185  .B \-\-entire\-thread=false\r
 186 +.RE\r
 187 +.RS 4\r
 188 +.TP 4\r
 189 +.B sexp\r
 190 +\r
 191 +The output is formatted as an S-Expression (sexp). This\r
 192 +format is more robust than the text format for automated\r
 193 +processing. The nested structure of multipart MIME messages is\r
 194 +reflected in nested S-Expression output. By default,\r
 195 +S-Expression output includes all messages in a matching thread;\r
 196 +that is, by default,\r
 197 +\r
 198 +.B \-\-format=sexp\r
 199 +sets\r
 200 +.B "\-\-entire\-thread"\r
 201 +The caller can disable this behaviour by setting\r
 202 +.B \-\-entire\-thread=false\r
 203  \r
 204  .RE\r
 205  .RS 4\r
 206 @@ -113,7 +133,7 @@ message.\r
 207  Output the single decoded MIME part N of a single message.  The search\r
 208  terms must match only a single message.  Message parts are numbered in\r
 209  a depth-first walk of the message MIME structure, and are identified\r
 210 -in the 'json' or 'text' output formats.\r
 211 +in the 'json', 'sexp' or 'text' output formats.\r
 212  .RE\r
 213  \r
 214  .RS 4\r
 215 @@ -123,8 +143,8 @@ in the 'json' or 'text' output formats.\r
 216  Compute and report the validity of any MIME cryptographic signatures\r
 217  found in the selected content (ie. "multipart/signed" parts). Status\r
 218  of the signature will be reported (currently only supported with\r
 219 ---format=json), and the multipart/signed part will be replaced by the\r
 220 -signed data.\r
 221 +--format=json and --format=sexp), and the multipart/signed part\r
 222 +will be replaced by the signed data.\r
 223  .RE\r
 224  \r
 225  .RS 4\r
 226 @@ -133,9 +153,9 @@ signed data.\r
 227  \r
 228  Decrypt any MIME encrypted parts found in the selected content\r
 229  (ie. "multipart/encrypted" parts). Status of the decryption will be\r
 230 -reported (currently only supported with --format=json) and the\r
 231 -multipart/encrypted part will be replaced by the decrypted\r
 232 -content.  Implies --verify.\r
 233 +reported (currently only supported with --format=json and\r
 234 +--format=sexp) and the multipart/encrypted part will be replaced\r
 235 +by the decrypted content.  Implies --verify.\r
 236  .RE\r
 237  \r
 238  .RS 4\r
 239 @@ -166,7 +186,7 @@ If true (the default)\r
 240  includes the bodies of the messages in the output; if false,\r
 241  bodies are omitted.\r
 242  .B --body=false\r
 243 -is only implemented for the json format and it is incompatible with\r
 244 +is only implemented for the json and sexp formats and it is incompatible with\r
 245  .B --part > 0.\r
 246  \r
 247  This is useful if the caller only needs the headers as body-less\r
 248 -- \r
 249 1.8.0\r
 250 \r