From 4fbbae5c0f03d8f5cf7c68691ca020b04e5acc93 Mon Sep 17 00:00:00 2001 From: Mark Walters Date: Thu, 6 Dec 2012 08:19:17 +0000 Subject: [PATCH] Re: [PATCH v3 5/5] Updating man pages for new S-Expression output format. --- e3/9af7fe3672fae4812b50e47d95663898d4a726 | 287 ++++++++++++++++++++++ 1 file changed, 287 insertions(+) create mode 100644 e3/9af7fe3672fae4812b50e47d95663898d4a726 diff --git a/e3/9af7fe3672fae4812b50e47d95663898d4a726 b/e3/9af7fe3672fae4812b50e47d95663898d4a726 new file mode 100644 index 000000000..e4cc74840 --- /dev/null +++ b/e3/9af7fe3672fae4812b50e47d95663898d4a726 @@ -0,0 +1,287 @@ +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 AB7D5431FB6 + for ; Thu, 6 Dec 2012 00:19:16 -0800 (PST) +X-Virus-Scanned: Debian amavisd-new at olra.theworths.org +X-Spam-Flag: NO +X-Spam-Score: -1.098 +X-Spam-Level: +X-Spam-Status: No, score=-1.098 tagged_above=-999 required=5 + tests=[DKIM_ADSP_CUSTOM_MED=0.001, FREEMAIL_FROM=0.001, + NML_ADSP_CUSTOM_MED=1.2, RCVD_IN_DNSWL_MED=-2.3] 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 FHpxcUrpHbfD for ; + Thu, 6 Dec 2012 00:19:15 -0800 (PST) +Received: from mail2.qmul.ac.uk (mail2.qmul.ac.uk [138.37.6.6]) + (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) + (No client certificate requested) + by olra.theworths.org (Postfix) with ESMTPS id 8ED20431FAE + for ; Thu, 6 Dec 2012 00:19:15 -0800 (PST) +Received: from smtp.qmul.ac.uk ([138.37.6.40]) + by mail2.qmul.ac.uk with esmtp (Exim 4.71) + (envelope-from ) + id 1TgWfp-0002Kp-Rq; Thu, 06 Dec 2012 08:19:14 +0000 +Received: from 93-97-24-31.zone5.bethere.co.uk ([93.97.24.31] helo=localhost) + by smtp.qmul.ac.uk with esmtpsa (TLSv1:AES128-SHA:128) (Exim 4.69) + (envelope-from ) + id 1TgWfp-0007XS-Br; Thu, 06 Dec 2012 08:19:13 +0000 +From: Mark Walters +To: Peter Feigl , 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 +X-Sender-Host-Address: 93.97.24.31 +X-QM-SPAM-Info: Sender has good ham record. :) +X-QM-Body-MD5: 8a87035c31f624a20931b5e7465d847e (of first 20000 bytes) +X-SpamAssassin-Score: -1.7 +X-SpamAssassin-SpamBar: - +X-SpamAssassin-Report: The QM spam filters have analysed this message to + determine if it is + spam. We require at least 5.0 points to mark a message as spam. + This message scored -1.7 points. + Summary of the scoring: + * -2.3 RCVD_IN_DNSWL_MED RBL: Sender listed at http://www.dnswl.org/, + * medium trust + * [138.37.6.40 listed in list.dnswl.org] + * 0.0 FREEMAIL_FROM Sender email is commonly abused enduser mail + provider * (markwalters1009[at]gmail.com) + * 0.6 AWL AWL: From: address is in the auto white-list +X-QM-Scan-Virus: ClamAV says the message is clean +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: Thu, 06 Dec 2012 08:19:16 -0000 + +On Thu, 06 Dec 2012, Peter Feigl 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:), 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 -- 2.26.2