01/5d71defb7efb5adfda3dca179c9f810715b6a7

   1 Return-Path: <m.walters@qmul.ac.uk>\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 D6D03431FB6\r
   6         for <notmuch@notmuchmail.org>; Fri, 18 Apr 2014 12:23:57 -0700 (PDT)\r
   7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
   8 X-Spam-Flag: NO\r
   9 X-Spam-Score: -1.098\r
  10 X-Spam-Level: \r
  11 X-Spam-Status: No, score=-1.098 tagged_above=-999 required=5\r
  12         tests=[DKIM_ADSP_CUSTOM_MED=0.001, FREEMAIL_FROM=0.001,\r
  13         NML_ADSP_CUSTOM_MED=1.2, RCVD_IN_DNSWL_MED=-2.3] 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 QS+epAFk+cSY for <notmuch@notmuchmail.org>;\r
  17         Fri, 18 Apr 2014 12:23:48 -0700 (PDT)\r
  18 Received: from mail2.qmul.ac.uk (mail2.qmul.ac.uk [138.37.6.6])\r
  19         (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits))\r
  20         (No client certificate requested)\r
  21         by olra.theworths.org (Postfix) with ESMTPS id 0CA22431FAF\r
  22         for <notmuch@notmuchmail.org>; Fri, 18 Apr 2014 12:23:47 -0700 (PDT)\r
  23 Received: from smtp.qmul.ac.uk ([138.37.6.40])\r
  24         by mail2.qmul.ac.uk with esmtp (Exim 4.71)\r
  25         (envelope-from <m.walters@qmul.ac.uk>)\r
  26         id 1WbENv-0006er-U2; Fri, 18 Apr 2014 20:23:42 +0100\r
  27 Received: from 94.196.126.238.threembb.co.uk ([94.196.126.238] helo=localhost)\r
  28         by smtp.qmul.ac.uk with esmtpsa (TLSv1:AES128-SHA:128) (Exim 4.71)\r
  29         (envelope-from <m.walters@qmul.ac.uk>)\r
  30         id 1WbENu-0001Mx-Gw; Fri, 18 Apr 2014 20:23:39 +0100\r
  31 From: Mark Walters <markwalters1009@gmail.com>\r
  32 To: Austin Clements <amdragon@MIT.EDU>, notmuch@notmuchmail.org\r
  33 Subject: Re: [PATCH 1/4] doc: Clarify notmuch show --format=raw description\r
  34 In-Reply-To: <1397834332-25175-2-git-send-email-amdragon@mit.edu>\r
  35 References: <1397834332-25175-1-git-send-email-amdragon@mit.edu>\r
  36         <1397834332-25175-2-git-send-email-amdragon@mit.edu>\r
  37 User-Agent: Notmuch/0.15.2+615~g78e3a93 (http://notmuchmail.org) Emacs/23.4.1\r
  38         (x86_64-pc-linux-gnu)\r
  39 Date: Fri, 18 Apr 2014 20:23:29 +0100\r
  40 Message-ID: <87lhv2h26m.fsf@qmul.ac.uk>\r
  41 MIME-Version: 1.0\r
  42 Content-Type: text/plain; charset=us-ascii\r
  43 X-Sender-Host-Address: 94.196.126.238\r
  44 X-QM-Geographic: According to ripencc,\r
  45         this message was delivered by a machine in Britain (UK) (GB).\r
  46 X-QM-SPAM-Info: Sender has good ham record.  :)\r
  47 X-QM-Body-MD5: e36223e3c6ba0d2ff1b732c0c6ce3690 (of first 20000 bytes)\r
  48 X-SpamAssassin-Score: 0.0\r
  49 X-SpamAssassin-SpamBar: /\r
  50 X-SpamAssassin-Report: The QM spam filters have analysed this message to\r
  51         determine if it is\r
  52         spam. We require at least 5.0 points to mark a message as spam.\r
  53         This message scored 0.0 points. Summary of the scoring: \r
  54         * 0.0 FREEMAIL_FROM Sender email is commonly abused enduser mail\r
  55         provider *      (markwalters1009[at]gmail.com)\r
  56 X-QM-Scan-Virus: ClamAV says the message is clean\r
  57 X-BeenThere: notmuch@notmuchmail.org\r
  58 X-Mailman-Version: 2.1.13\r
  59 Precedence: list\r
  60 List-Id: "Use and development of the notmuch mail system."\r
  61         <notmuch.notmuchmail.org>\r
  62 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
  63         <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
  64 List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
  65 List-Post: <mailto:notmuch@notmuchmail.org>\r
  66 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
  67 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
  68         <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
  69 X-List-Received-Date: Fri, 18 Apr 2014 19:23:58 -0000\r
  70 \r
  71 \r
  72 On Fri, 18 Apr 2014, Austin Clements <amdragon@MIT.EDU> wrote:\r
  73 > In addition to being generally more precise, this is explicit that\r
  74 > there is no charset conversion.\r
  75 > ---\r
  76 >  doc/man1/notmuch-show.rst | 36 ++++++++++++++++++++----------------\r
  77 >  1 file changed, 20 insertions(+), 16 deletions(-)\r
  78 >\r
  79 > diff --git a/doc/man1/notmuch-show.rst b/doc/man1/notmuch-show.rst\r
  80 > index bad868b..2c0f64c 100644\r
  81 > --- a/doc/man1/notmuch-show.rst\r
  82 > +++ b/doc/man1/notmuch-show.rst\r
  83 > @@ -76,22 +76,26 @@ Supported options for **show** include\r
  84 >  \r
  85 >           http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html\r
  86 >  \r
  87 > -        **raw** (default for a single part, see --part)\r
  88 > -            For a message or an attached message part, the original, raw\r
  89 > -            content of the email message is output. Consumers of this\r
  90 > -            format should expect to implement MIME decoding and similar\r
  91 > -            functions.\r
  92 > -\r
  93 > -            For a single part (--part) the raw part content is output\r
  94 > -            after performing any necessary MIME decoding. Note that\r
  95 > -            messages with a simple body still have two parts: part 0 is\r
  96 > -            the whole message and part 1 is the body.\r
  97 > -\r
  98 > -            For a multipart part, the part headers and body (including\r
  99 > -            all child parts) is output.\r
 100 > -\r
 101 > -            The raw format must only be used with search terms matching\r
 102 > -            single message.\r
 103 > +        **raw** (default if --part is given)\r
 104 > +            Write the raw bytes of the given MIME part of a message to\r
 105 > +            standard out. For this format, it is an error to specify a\r
 106 > +            query that matches more than one message.\r
 107 > +\r
 108 > +            If the specified part is a leaf part, this outputs the\r
 109 > +            body of the part after performing content transfer\r
 110 > +            decoding (but no charset conversion). This is suitable for\r
 111 > +            saving attachments, for example.\r
 112 > +\r
 113 > +            For a multipart or message part, the output includes the\r
 114 > +            part headers as well as the body (including all child\r
 115 > +            parts). No decoding is performed because multipart and\r
 116 > +            message parts cannot have non-trivial content transfer\r
 117 > +            encoding. Consumers of this may need to implement MIME\r
 118 > +            decoding and similar functions.\r
 119 > +\r
 120 > +            Note that even a message with a simple body has two parts:\r
 121 > +            part 0 is the whole message and part 1 is the body of the\r
 122 > +            message.\r
 123 \r
 124 Generally this looks good. I wonder whether the paragraph above could be\r
 125 expanded slightly: my (quite possibly flawed) understanding is that\r
 126 simple messages don't need to be MIME encoded (at least some messages\r
 127 don't contain any mention of MIME). If this is correct then I think it\r
 128 would be worth clarifying that this paragraph applies even to non-MIME\r
 129 encoded messages.\r
 130 \r
 131 Best wishes\r
 132 \r
 133 Mark\r
 134 \r
 135 \r
 136 \r
 137 >  \r
 138 >      ``--format-version=N``\r
 139 >          Use the specified structured output format version. This is\r
 140 > -- \r
 141 > 1.9.1\r
 142 >\r
 143 > _______________________________________________\r
 144 > notmuch mailing list\r
 145 > notmuch@notmuchmail.org\r
 146 > http://notmuchmail.org/mailman/listinfo/notmuch\r