From 9f0accb6aa1be3aa3a00e564b1091f875cf45e80 Mon Sep 17 00:00:00 2001
From: Carl Worth <cworth@cworth.org>
Date: Thu, 19 Aug 2010 17:12:52 -0700
Subject: [PATCH] notmuch show: Add documentation of --format=mbox

Shame on me for adding a feature without documenting it at the same
time.
---
 notmuch.1 | 23 +++++++++++++++++++----
 notmuch.c | 28 +++++++++++++++++++++-------
 2 files changed, 40 insertions(+), 11 deletions(-)

diff --git a/notmuch.1 b/notmuch.1
index 86830f4b..3ec9c55c 100644
--- a/notmuch.1
+++ b/notmuch.1
@@ -201,13 +201,13 @@ matched message will be displayed.
 
 .RS 4
 .TP 4
-.B \-\-format=(json|text)
+.B \-\-format=(text|json|mbox)
 
 .RS 4
 .TP 4
 .B text
 
-The default plain-text format  has  text-content  MIME parts
+The default plain-text format has all text-content MIME parts
 decoded. Various components in the output,
 .RB ( message ", " header ", " body ", " attachment ", and MIME " part ),
 will be delimited by easily-parsed markers. Each marker consists of a
@@ -220,12 +220,27 @@ or close the component.
 .TP 4
 .B json
 
-Format output as Javascript Object Notation (JSON). JSON output always
-includes all messages in a matching thread; in effect
+The output is formatted with Javascript Object Notation (JSON). This
+format is more robust than the text format for automated
+processing. JSON output always includes all messages in a matching
+thread; in effect
 .B \-\-format=json
 implies
 .B \-\-entire\-thread
 
+.RE
+.RS 4
+.TP 4
+.B mbox
+
+All matching messages are output in the traditional, Unix mbox format
+with each message being prefixed by a line beginning with "From " and
+a blank line separating each message. Lines in the message content
+beginning with "From " (preceded by zero or more '>' characters) have
+an additional '>' character added. This reversible escaping
+is termed "mboxrd" format and described in detail here:
+http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
+
 .RE
 A common use of
 .B notmuch show
diff --git a/notmuch.c b/notmuch.c
index 13e2612d..f6b8c139 100644
--- a/notmuch.c
+++ b/notmuch.c
@@ -189,12 +189,12 @@ command_t commands[] = {
       "\t\tall messages in the same thread as any matched\n"
       "\t\tmessage will be displayed.\n"
       "\n"
-      "\t--format=(json|text)\n"
+      "\t--format=(text|json|mbox)\n"
       "\n"
-      "\t\ttext\t(default)\n"
+      "\t\ttext (default)\n"
       "\n"
-      "\t\tThe plain-text has all text-content MIME parts decoded.\n"
-      "\t\tVarious components in the output, ('message', 'header',\n"
+      "\t\tThe default plain-text format has all text-content MIME parts\n"
+      "\t\tdecoded. Various components in the output, ('message', 'header',\n"
       "\t\t'body', 'attachment', and MIME 'part') are delimited by\n"
       "\t\teasily-parsed markers. Each marker consists of a Control-L\n"
       "\t\tcharacter (ASCII decimal 12), the name of the marker, and\n"
@@ -203,9 +203,23 @@ command_t commands[] = {
       "\n"
       "\t\tjson\n"
       "\n"
-      "\t\tFormat output as Javascript Object Notation (JSON).\n"
-      "\t\tJSON output always includes all messages in a matching,\n"
-      "\t\tthread i.e. '--format=json' implies '--entire-thread'\n"
+      "\t\tThe output is formatted with Javascript Object Notation\n"
+      "\t\t(JSON). This format is more robust than the text format\n"
+      "\t\tfor automated processing. JSON output always includes all\n"
+      "\t\tmessages in a matching thread; in effect '--format=json'\n"
+      "\t\timplies '--entire-thread'\n"
+      "\n"
+      "\t\tmbox\n"
+      "\n"
+      "\t\tAll matching messages are output in the traditional, Unix\n"
+      "\t\tmbox format with each message being prefixed by a line\n"
+      "\t\tbeginning with 'From ' and a blank line separating each\n"
+      "\t\tmessage. Lines in the message content beginning with 'From '\n"
+      "\t\t(preceded by zero or more '>' characters) have an additional\n"
+      "\t\t'>' character added. This reversible escaping is termed\n"
+      "\t\t\"mboxrd\" format and described in detail here:\n"
+      "\n"
+      "\t\thttp://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html\n"
       "\n"
       "\tA common use of \"notmuch show\" is to display a single\n"
       "\tthread of email messages. For this, use a search term of\n"
-- 
2.43.0