[PATCH v3 5/5] Updating man pages for new S-Expression output format.
Mark Walters
markwalters1009 at gmail.com
Thu Dec 6 00:19:17 PST 2012
On Thu, 06 Dec 2012, Peter Feigl <craven at 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 at notmuchmail.org
> http://notmuchmail.org/mailman/listinfo/notmuch
More information about the notmuch
mailing list