From 9f0accb6aa1be3aa3a00e564b1091f875cf45e80 Mon Sep 17 00:00:00 2001 From: Carl Worth 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"