From: Mark Walters <markwalters1009@gmail.com>
To: Peter Feigl <craven@gmx.net>, notmuch@notmuchmail.org
Subject: Re: [PATCH v3 5/5] Updating man pages for new S-Expression output
	format.
In-Reply-To: <1354779189-12231-6-git-send-email-craven@gmx.net>
References: <1354779189-12231-1-git-send-email-craven@gmx.net>
	<1354779189-12231-6-git-send-email-craven@gmx.net>
User-Agent: Notmuch/0.14+81~g9730584 (http://notmuchmail.org) Emacs/23.4.1
	(x86_64-pc-linux-gnu)
Date: Thu, 06 Dec 2012 08:19:17 +0000
Message-ID: <87vccfpp8a.fsf@qmul.ac.uk>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Precedence: list

On Thu, 06 Dec 2012, Peter Feigl <craven@gmx.net> wrote:
> Add sections about the new S-Expression output format (--format=sexp) to
> the notmuch-search, notmuch-reply and notmuch-show man pages.
> ---
>  man/man1/notmuch-reply.1  | 14 ++++++++++----
>  man/man1/notmuch-search.1 | 15 ++++++++-------
>  man/man1/notmuch-show.1   | 36 ++++++++++++++++++++++++++++--------
>  3 files changed, 46 insertions(+), 19 deletions(-)
>
> diff --git a/man/man1/notmuch-reply.1 b/man/man1/notmuch-reply.1
> index d264060..f71d764 100644
> --- a/man/man1/notmuch-reply.1
> +++ b/man/man1/notmuch-reply.1
> @@ -37,7 +37,7 @@ Supported options for
>  include
>  .RS
>  .TP 4
> -.BR \-\-format= ( default | json | headers\-only )
> +.BR \-\-format= ( default | json | sexp | headers\-only )
>  .RS
>  .TP 4
>  .BR default
> @@ -48,6 +48,11 @@ Produces JSON output containing headers for a reply message and the
>  contents of the original message. This output can be used by a client
>  to create a reply message intelligently.
>  .TP
> +.BR sexp
> +Produces S-Expression output containing headers for a reply message and
> +the contents of the original message. This output can be used by a client
> +to create a reply message intelligently.
> +.TP
>  .BR headers\-only
>  Only produces In\-Reply\-To, References, To, Cc, and Bcc headers.
>  .RE
> @@ -74,8 +79,8 @@ user's addresses.
>  
>  Decrypt any MIME encrypted parts found in the selected content
>  (ie. "multipart/encrypted" parts). Status of the decryption will be
> -reported (currently only supported with --format=json) and the
> -multipart/encrypted part will be replaced by the decrypted
> +reported (currently only supported with --format=json and --format=sexp)
> +and the multipart/encrypted part will be replaced by the decrypted
>  content.
>  .RE
>  
> @@ -89,7 +94,8 @@ id:<message-id>), but it can be useful to reply to several messages at
>  once. For example, when a series of patches are sent in a single
>  thread, replying to the entire thread allows for the reply to comment
>  on issues found in multiple patches. The default format supports
> -replying to multiple messages at once, but the JSON format does not.
> +replying to multiple messages at once, but the JSON and S-Expression
> +format does not.

Totally trivial but should be "do not".

MW


>  .RE
>  .RE
>  
> diff --git a/man/man1/notmuch-search.1 b/man/man1/notmuch-search.1
> index 6ccd3b8..0aff348 100644
> --- a/man/man1/notmuch-search.1
> +++ b/man/man1/notmuch-search.1
> @@ -25,9 +25,9 @@ Supported options for
>  include
>  .RS 4
>  .TP 4
> -.BR \-\-format= ( json | text )
> +.BR \-\-format= ( json | sexp | text )
>  
> -Presents the results in either JSON or plain-text (default).
> +Presents the results in either JSON, S-Expressions or plain-text (default).
>  .RE
>  
>  .RS 4
> @@ -49,7 +49,7 @@ the authors of the thread and the subject.
>  
>  Output the thread IDs of all threads with any message matching the
>  search terms, either one per line (\-\-format=text) or as a JSON array
> -(\-\-format=json).
> +(\-\-format=json) or an S-Expression list (\-\-format=sexp).
>  .RE
>  .RS 4
>  .TP 4
> @@ -57,22 +57,23 @@ search terms, either one per line (\-\-format=text) or as a JSON array
>  
>  Output the message IDs of all messages matching the search terms,
>  either one per line (\-\-format=text) or as a JSON array
> -(\-\-format=json).
> +(\-\-format=json) or as an S-Expression list (\-\-format=sexp).
>  .RE
>  .RS 4
>  .TP 4
>  .B files
>  
>  Output the filenames of all messages matching the search terms, either
> -one per line (\-\-format=text) or as a JSON array (\-\-format=json).
> +one per line (\-\-format=text) or as a JSON array (\-\-format=json) or
> +as an S-Expression list (\-\-format=sexp).
>  .RE
>  .RS 4
>  .TP 4
>  .B tags
>  
>  Output all tags that appear on any message matching the search terms,
> -either one per line (\-\-format=text) or as a JSON array
> -(\-\-format=json).
> +either one per line (\-\-format=text) or as a JSON array (\-\-format=json)
> +or as an S-Expression list (\-\-format=sexp).
>  .RE
>  .RE
>  
> diff --git a/man/man1/notmuch-show.1 b/man/man1/notmuch-show.1
> index 4481f21..bd41c48 100644
> --- a/man/man1/notmuch-show.1
> +++ b/man/man1/notmuch-show.1
> @@ -31,12 +31,14 @@ If true,
>  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
> +and
> +.B --format=sexp
>  this defaults to true.  For other formats, this defaults to false.
>  .RE
>  
>  .RS 4
>  .TP 4
> -.B \-\-format=(text|json|mbox|raw)
> +.B \-\-format=(text|json|sexp|mbox|raw)
>  
>  .RS 4
>  .TP 4
> @@ -60,11 +62,29 @@ format is more robust than the text format for automated
>  processing. The nested structure of multipart MIME messages is
>  reflected in nested JSON output. By default JSON output includes all
>  messages in a matching thread; that is, by default,
> +
>  .B \-\-format=json
>  sets
>  .B "\-\-entire\-thread"
>  The caller can disable this behaviour by setting
>  .B \-\-entire\-thread=false
> +.RE
> +.RS 4
> +.TP 4
> +.B sexp
> +
> +The output is formatted as an S-Expression (sexp). This
> +format is more robust than the text format for automated
> +processing. The nested structure of multipart MIME messages is
> +reflected in nested S-Expression output. By default,
> +S-Expression output includes all messages in a matching thread;
> +that is, by default,
> +
> +.B \-\-format=sexp
> +sets
> +.B "\-\-entire\-thread"
> +The caller can disable this behaviour by setting
> +.B \-\-entire\-thread=false
>  
>  .RE
>  .RS 4
> @@ -113,7 +133,7 @@ message.
>  Output the single decoded MIME part N of a single message.  The search
>  terms must match only a single message.  Message parts are numbered in
>  a depth-first walk of the message MIME structure, and are identified
> -in the 'json' or 'text' output formats.
> +in the 'json', 'sexp' or 'text' output formats.
>  .RE
>  
>  .RS 4
> @@ -123,8 +143,8 @@ in the 'json' or 'text' output formats.
>  Compute and report the validity of any MIME cryptographic signatures
>  found in the selected content (ie. "multipart/signed" parts). Status
>  of the signature will be reported (currently only supported with
> ---format=json), and the multipart/signed part will be replaced by the
> -signed data.
> +--format=json and --format=sexp), and the multipart/signed part
> +will be replaced by the signed data.
>  .RE
>  
>  .RS 4
> @@ -133,9 +153,9 @@ signed data.
>  
>  Decrypt any MIME encrypted parts found in the selected content
>  (ie. "multipart/encrypted" parts). Status of the decryption will be
> -reported (currently only supported with --format=json) and the
> -multipart/encrypted part will be replaced by the decrypted
> -content.  Implies --verify.
> +reported (currently only supported with --format=json and
> +--format=sexp) and the multipart/encrypted part will be replaced
> +by the decrypted content.  Implies --verify.
>  .RE
>  
>  .RS 4
> @@ -166,7 +186,7 @@ If true (the default)
>  includes the bodies of the messages in the output; if false,
>  bodies are omitted.
>  .B --body=false
> -is only implemented for the json format and it is incompatible with
> +is only implemented for the json and sexp formats and it is incompatible with
>  .B --part > 0.
>  
>  This is useful if the caller only needs the headers as body-less
> -- 
> 1.8.0
>
> _______________________________________________
> notmuch mailing list
> notmuch@notmuchmail.org
> http://notmuchmail.org/mailman/listinfo/notmuch