From: Austin Clements Date: Sun, 22 Jul 2012 16:36:28 +0000 (+2000) Subject: Re: [PATCH] man: show: update man page for entire-thread and json. X-Git-Url: http://git.tremily.us/gitweb.cgi?a=commitdiff_plain;h=beae62c1715806ea6b747b9a416107a4f2d65fb8;p=notmuch-archives.git Re: [PATCH] man: show: update man page for entire-thread and json. --- diff --git a/56/d4529cac683dd0b3459ff0d5c75daa7dffd343 b/56/d4529cac683dd0b3459ff0d5c75daa7dffd343 new file mode 100644 index 000000000..846889723 --- /dev/null +++ b/56/d4529cac683dd0b3459ff0d5c75daa7dffd343 @@ -0,0 +1,138 @@ +Return-Path: +X-Original-To: notmuch@notmuchmail.org +Delivered-To: notmuch@notmuchmail.org +Received: from localhost (localhost [127.0.0.1]) + by olra.theworths.org (Postfix) with ESMTP id 4CDB1431FAF + for ; Sun, 22 Jul 2012 09:36:32 -0700 (PDT) +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 uWR2QAkWfEMn for ; + Sun, 22 Jul 2012 09:36:31 -0700 (PDT) +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 A39FD431FAE + for ; Sun, 22 Jul 2012 09:36:31 -0700 (PDT) +X-AuditID: 12074422-b7f1f6d00000090b-5a-500c2c0f20b6 +Received: from mailhub-auth-4.mit.edu ( [18.7.62.39]) + by dmz-mailsec-scanner-5.mit.edu (Symantec Messaging Gateway) with SMTP + id E0.1E.02315.F0C2C005; Sun, 22 Jul 2012 12:36:31 -0400 (EDT) +Received: from outgoing.mit.edu (OUTGOING-AUTH.MIT.EDU [18.7.22.103]) + by mailhub-auth-4.mit.edu (8.13.8/8.9.2) with ESMTP id q6MGaUSd009081; + Sun, 22 Jul 2012 12:36:31 -0400 +Received: from awakening.csail.mit.edu (awakening.csail.mit.edu [18.26.4.91]) + (authenticated bits=0) + (User authenticated as amdragon@ATHENA.MIT.EDU) + by outgoing.mit.edu (8.13.6/8.12.4) with ESMTP id q6MGaTtk006761 + (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NOT); + Sun, 22 Jul 2012 12:36:30 -0400 (EDT) +Received: from amthrax by awakening.csail.mit.edu with local (Exim 4.77) + (envelope-from ) + id 1Ssz8u-0007M5-V7; Sun, 22 Jul 2012 12:36:29 -0400 +Date: Sun, 22 Jul 2012 12:36:28 -0400 +From: Austin Clements +To: Mark Walters +Subject: Re: [PATCH] man: show: update man page for entire-thread and json. +Message-ID: <20120722163628.GE31834@mit.edu> +References: <1342852448-8917-1-git-send-email-markwalters1009@gmail.com> +MIME-Version: 1.0 +Content-Type: text/plain; charset=us-ascii +Content-Disposition: inline +In-Reply-To: <1342852448-8917-1-git-send-email-markwalters1009@gmail.com> +User-Agent: Mutt/1.5.21 (2010-09-15) +X-Brightmail-Tracker: + H4sIAAAAAAAAA+NgFupjleLIzCtJLcpLzFFi42IRYrdT1+XX4QkwaNrCbbF6Lo/F9ZszmR2Y + PHbOusvu8WzVLeYApigum5TUnMyy1CJ9uwSujA3v/rAXXBKquLloFXsD4wS+LkZODgkBE4n+ + tUtYIGwxiQv31rN1MXJxCAnsY5SYd/MhI4SzgVFi0b3XzBDOSSaJOQ1PoZwljBLrL89jBeln + EVCVWPrhDRuIzSagIbFt/3JGEFtEQEfi9qEF7CA2s4C0xLffzUxdjBwcwgLeEjsmC4OEeYFK + Nm/aygxiCwl4SBztX8sCEReUODnzCQtEq5bEjX8vwVpBxiz/xwES5hTwlPg2fRtYq6iAisSU + k9vYJjAKzULSPQtJ9yyE7gWMzKsYZVNyq3RzEzNzilOTdYuTE/PyUot0TfVyM0v0UlNKNzGC + g9pFaQfjz4NKhxgFOBiVeHgN3bkDhFgTy4orcw8xSnIwKYny7tXkCRDiS8pPqcxILM6ILyrN + SS0+xCjBwawkwnv5OlA5b0piZVVqUT5MSpqDRUmc91rKTX8hgfTEktTs1NSC1CKYrAwHh5IE + b7Y20FDBotT01Iq0zJwShDQTByfIcB6g4Y0gNbzFBYm5xZnpEPlTjLoc1x7eusUoxJKXn5cq + Jc4bC1IkAFKUUZoHNweWjF4xigO9JczbBVLFA0xkcJNeAS1hAloincUFsqQkESEl1cA4965E + v9Zzp7OTjr/cEGj4QJJz2uvU8wlzb9x0XVx0NWVeoc91jSJZvn6hk9qyZz9OO9P92bPzutiL + 5ylK9V/CvN5cyTbZPHnPhWMvVBOfmmQcTL6WdGKzlsqiTVMc2ouiNPX2Gh7kmN598laE/wRH + 1ZjVl698elTdJpL06my+2bedtTd/djqcVmIpzkg01GIuKk4EABkgYJkhAwAA +Cc: notmuch@notmuchmail.org +X-BeenThere: notmuch@notmuchmail.org +X-Mailman-Version: 2.1.13 +Precedence: list +List-Id: "Use and development of the notmuch mail system." + +List-Unsubscribe: , + +List-Archive: +List-Post: +List-Help: +List-Subscribe: , + +X-List-Received-Date: Sun, 22 Jul 2012 16:36:32 -0000 + +Quoth Mark Walters on Jul 21 at 7:34 am: +> Previously in notmuch show --format=json implied --entire-thread. This +> is still the default but it is now possible to disable this. Update +> the manpage to reflect this. +> --- +> +> I didn't update the manpage in the recent patch series. This corrects +> that omission. (Less cumbersome wording gratefully received) +> +> Best wishes +> +> Mark man/man1/notmuch-show.1 | 16 +++++++++------- +> 1 files changed, 9 insertions(+), 7 deletions(-) +> +> diff --git a/man/man1/notmuch-show.1 b/man/man1/notmuch-show.1 +> index b51a54c..5fa590e 100644 +> --- a/man/man1/notmuch-show.1 +> +++ b/man/man1/notmuch-show.1 +> @@ -26,9 +26,9 @@ include +> .TP 4 +> .B \-\-entire\-thread +> +> -By default only those messages that match the search terms will be +> -displayed. With this option, all messages in the same thread as any +> -matched message will be displayed. +> +By default (except when format=json) only those messages that match +> +the search terms will be displayed. With this option, all messages in +> +the same thread as any matched message will be displayed. + +I think stating this in terms of defaults that aren't really defaults +is what makes this cumbersome. What about something like + +.B \-\-entire\-thread=(true|false) + +If true, +.B notmuch show +returns all messages in the thread of any message matching the search +terms, rather than returning only the matching messages. For +.B --format=json +this defaults to true. For other formats, this defaults to false. + +> .RE +> +> .RS 4 +> @@ -55,11 +55,13 @@ be nested. +> The output is formatted with Javascript Object Notation (JSON). This +> format is more robust than the text format for automated +> processing. The nested structure of multipart MIME messages is +> -reflected in nested JSON output. JSON output always includes all +> -messages in a matching thread; in effect +> +reflected in nested JSON output. By default JSON output includes all +> +messages in a matching thread; that is, by default, +> .B \-\-format=json +> -implies +> -.B \-\-entire\-thread +> +sets +> +.B "\-\-entire\-thread" +> +The caller can disable this behaviour by setting +> +.B \-\-entire\-thread=false +> +> .RE +> .RS 4