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.
Date: Thu, 06 Dec 2012 08:19:17 +0000 [thread overview]
Message-ID: <87vccfpp8a.fsf@qmul.ac.uk> (raw)
In-Reply-To: <1354779189-12231-6-git-send-email-craven@gmx.net>
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
next prev parent reply other threads:[~2012-12-06 8:19 UTC|newest]
Thread overview: 38+ messages / expand[flat|nested] mbox.gz Atom feed top
2012-11-30 8:29 [PATCH 1/3] Adding an S-expression structured output printer Peter Feigl
2012-11-30 8:29 ` [PATCH 2/3] Use the S-Expression structured printer for notmuch search Peter Feigl
2012-11-30 18:04 ` Jani Nikula
2012-11-30 8:29 ` [PATCH 3/3] Use the S-Expression structured printer in notmuch show and notmuch reply Peter Feigl
2012-11-30 19:06 ` Jani Nikula
2012-11-30 8:34 ` [PATCH 1/3] Adding an S-expression structured output printer Peter Feigl
2012-11-30 17:26 ` Jani Nikula
2012-11-30 19:11 ` Jani Nikula
2012-12-01 9:59 ` Mark Walters
2012-12-01 11:34 ` Tomi Ollila
2012-12-01 12:24 ` Mark Walters
2012-12-01 13:29 ` Tomi Ollila
2012-12-01 13:45 ` Mark Walters
2012-12-01 14:26 ` Mark Walters
2012-12-01 15:46 ` Mark Walters
2012-12-01 15:18 ` Austin Clements
2012-12-01 16:14 ` Mark Walters
2012-12-04 14:46 ` [PATCH v2 0/5] New output format sexp (Lisp S-Expressions) Peter Feigl
2012-12-04 17:07 ` Jani Nikula
2012-12-06 7:33 ` [PATCH v3 " Peter Feigl
2012-12-06 8:22 ` Mark Walters
2012-12-07 2:54 ` Jameson Graef Rollins
2012-12-06 7:33 ` [PATCH v3 1/5] Adding an S-expression structured output printer Peter Feigl
2012-12-06 7:33 ` [PATCH v3 2/5] Rename the -json printer functions in notmuch-reply and notmuch-show to generic -sprinter functions Peter Feigl
2012-12-06 7:33 ` [PATCH v3 3/5] Use the S-Expression structured printer in notmuch-show, notmuch-reply and notmuch-search Peter Feigl
2012-12-06 7:33 ` [PATCH v3 4/5] Adding tests for --format=sexp Peter Feigl
2012-12-06 8:18 ` Mark Walters
2012-12-06 7:33 ` [PATCH v3 5/5] Updating man pages for new S-Expression output format Peter Feigl
2012-12-06 8:19 ` Mark Walters [this message]
2012-12-04 14:46 ` [PATCH v2 1/5] Adding an S-expression structured output printer Peter Feigl
2012-12-04 19:14 ` Austin Clements
2012-12-04 14:46 ` [PATCH v2 2/5] Rename the -json printer functions in notmuch-reply and notmuch-show to generic -sprinter functions Peter Feigl
2012-12-04 19:18 ` Austin Clements
2012-12-04 14:46 ` [PATCH v2 3/5] Use the S-Expression structured printer in notmuch-show, notmuch-reply and notmuch-search Peter Feigl
2012-12-04 19:22 ` Austin Clements
2012-12-04 14:46 ` [PATCH v2 4/5] Adding tests for --format=sexp Peter Feigl
2012-12-04 19:24 ` Austin Clements
2012-12-04 14:46 ` [PATCH v2 5/5] Updating man pages for new S-Expression output format Peter Feigl
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://notmuchmail.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87vccfpp8a.fsf@qmul.ac.uk \
--to=markwalters1009@gmail.com \
--cc=craven@gmx.net \
--cc=notmuch@notmuchmail.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).