From: Peter Feigl Date: Thu, 6 Dec 2012 21:12:15 +0000 (+0100) Subject: [PATCH v5 5/5] Updating man pages for new S-Expression output format. X-Git-Url: http://git.tremily.us/gitweb.cgi?a=commitdiff_plain;h=7fce189d7f961614b98634e70e16118ae12d89f3;p=notmuch-archives.git [PATCH v5 5/5] Updating man pages for new S-Expression output format. --- diff --git a/64/e5790c85042b303174d28c5a399dbe2e73f972 b/64/e5790c85042b303174d28c5a399dbe2e73f972 new file mode 100644 index 000000000..6a0413471 --- /dev/null +++ b/64/e5790c85042b303174d28c5a399dbe2e73f972 @@ -0,0 +1,247 @@ +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 E156C431FC0 + for ; Thu, 6 Dec 2012 13:12:26 -0800 (PST) +X-Virus-Scanned: Debian amavisd-new at olra.theworths.org +X-Spam-Flag: NO +X-Spam-Score: 0.001 +X-Spam-Level: +X-Spam-Status: No, score=0.001 tagged_above=-999 required=5 + tests=[FREEMAIL_FROM=0.001] 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 TUC46tsBC0lZ for ; + Thu, 6 Dec 2012 13:12:25 -0800 (PST) +Received: from mail.nexoid.at (www.nexoid.at [178.79.130.240]) + (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) + (No client certificate requested) + by olra.theworths.org (Postfix) with ESMTPS id 35EE6431FB6 + for ; Thu, 6 Dec 2012 13:12:25 -0800 (PST) +Received: by mail.nexoid.at (Postfix, from userid 1000) + id 4441311C10F; Thu, 6 Dec 2012 22:12:23 +0100 (CET) +From: Peter Feigl +To: notmuch@notmuchmail.org +Subject: [PATCH v5 5/5] Updating man pages for new S-Expression output format. +Date: Thu, 6 Dec 2012 22:12:15 +0100 +Message-Id: <1354828335-18151-6-git-send-email-craven@gmx.net> +X-Mailer: git-send-email 1.8.0 +In-Reply-To: <1354828335-18151-1-git-send-email-craven@gmx.net> +References: <1354828335-18151-1-git-send-email-craven@gmx.net> +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 21:12:27 -0000 + +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..fa04c9e 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 ++formats do not. + .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 +