unofficial mirror of notmuch@notmuchmail.org
 help / color / mirror / code / Atom feed
* [PATCH] man: show: update man page for entire-thread and json.
@ 2012-07-21  6:34 Mark Walters
  2012-07-22 16:36 ` Austin Clements
  0 siblings, 1 reply; 5+ messages in thread
From: Mark Walters @ 2012-07-21  6:34 UTC (permalink / raw)
  To: notmuch

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.
 .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
-- 
1.7.9.1

^ permalink raw reply related	[flat|nested] 5+ messages in thread

* Re: [PATCH] man: show: update man page for entire-thread and json.
  2012-07-21  6:34 [PATCH] man: show: update man page for entire-thread and json Mark Walters
@ 2012-07-22 16:36 ` Austin Clements
  2012-07-24 18:57   ` [PATCH v2] " Mark Walters
  0 siblings, 1 reply; 5+ messages in thread
From: Austin Clements @ 2012-07-22 16:36 UTC (permalink / raw)
  To: Mark Walters; +Cc: notmuch

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

^ permalink raw reply	[flat|nested] 5+ messages in thread

* [PATCH v2] man: show: update man page for entire-thread and json.
  2012-07-22 16:36 ` Austin Clements
@ 2012-07-24 18:57   ` Mark Walters
  2012-07-25  3:12     ` Austin Clements
  2012-07-25 11:21     ` David Bremner
  0 siblings, 2 replies; 5+ messages in thread
From: Mark Walters @ 2012-07-24 18:57 UTC (permalink / raw)
  To: notmuch

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.
---

Update the manpage since --format=json and --entire-thread=false is
now supported. Reworded as Austin suggested.

Best wishes

Mark 

 man/man1/notmuch-show.1 |   21 +++++++++++++--------
 1 files changed, 13 insertions(+), 8 deletions(-)

diff --git a/man/man1/notmuch-show.1 b/man/man1/notmuch-show.1
index 506583a..765b22c 100644
--- a/man/man1/notmuch-show.1
+++ b/man/man1/notmuch-show.1
@@ -24,11 +24,14 @@ Supported options for
 include
 .RS 4
 .TP 4
-.B \-\-entire\-thread
+.B \-\-entire\-thread=(true|false)
 
-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.
+If true,
+.B notmuch show
+outputs all messages in the thread of any message matching the search
+terms; if false, it outputs only the matching messages. For
+.B --format=json
+this defaults to true.  For other formats, this defaults to false.
 .RE
 
 .RS 4
@@ -55,11 +58,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
-- 
1.7.9.1

^ permalink raw reply related	[flat|nested] 5+ messages in thread

* Re: [PATCH v2] man: show: update man page for entire-thread and json.
  2012-07-24 18:57   ` [PATCH v2] " Mark Walters
@ 2012-07-25  3:12     ` Austin Clements
  2012-07-25 11:21     ` David Bremner
  1 sibling, 0 replies; 5+ messages in thread
From: Austin Clements @ 2012-07-25  3:12 UTC (permalink / raw)
  To: Mark Walters, notmuch

LGTM.

On Tue, 24 Jul 2012, Mark Walters <markwalters1009@gmail.com> wrote:
> 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.
> ---
>
> Update the manpage since --format=json and --entire-thread=false is
> now supported. Reworded as Austin suggested.
>
> Best wishes
>
> Mark 
>
>  man/man1/notmuch-show.1 |   21 +++++++++++++--------
>  1 files changed, 13 insertions(+), 8 deletions(-)
>
> diff --git a/man/man1/notmuch-show.1 b/man/man1/notmuch-show.1
> index 506583a..765b22c 100644
> --- a/man/man1/notmuch-show.1
> +++ b/man/man1/notmuch-show.1
> @@ -24,11 +24,14 @@ Supported options for
>  include
>  .RS 4
>  .TP 4
> -.B \-\-entire\-thread
> +.B \-\-entire\-thread=(true|false)
>  
> -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.
> +If true,
> +.B notmuch show
> +outputs all messages in the thread of any message matching the search
> +terms; if false, it outputs only the matching messages. For
> +.B --format=json
> +this defaults to true.  For other formats, this defaults to false.
>  .RE
>  
>  .RS 4
> @@ -55,11 +58,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
> -- 
> 1.7.9.1

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: [PATCH v2] man: show: update man page for entire-thread and json.
  2012-07-24 18:57   ` [PATCH v2] " Mark Walters
  2012-07-25  3:12     ` Austin Clements
@ 2012-07-25 11:21     ` David Bremner
  1 sibling, 0 replies; 5+ messages in thread
From: David Bremner @ 2012-07-25 11:21 UTC (permalink / raw)
  To: Mark Walters, notmuch

Mark Walters <markwalters1009@gmail.com> writes:

> 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.

pushed

d

^ permalink raw reply	[flat|nested] 5+ messages in thread

end of thread, other threads:[~2012-07-25 11:22 UTC | newest]

Thread overview: 5+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2012-07-21  6:34 [PATCH] man: show: update man page for entire-thread and json Mark Walters
2012-07-22 16:36 ` Austin Clements
2012-07-24 18:57   ` [PATCH v2] " Mark Walters
2012-07-25  3:12     ` Austin Clements
2012-07-25 11:21     ` David Bremner

Code repositories for project(s) associated with this public inbox

	https://yhetil.org/notmuch.git/

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).