From: Carl Worth <cworth@cworth.org>
Date: Tue, 24 May 2011 18:21:08 +0000 (-0700)
Subject: notmuch show: Update documentation for default --format=raw for --part
X-Git-Tag: debian/0.6_254~129
X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=commitdiff_plain;h=a06889c8d48eff3f3fc76b5cbacc60ce46bd65da

notmuch show: Update documentation for default --format=raw for --part

We recently made the --part option to "notmuch show" trigger a default
format of "raw", (since the previous default of "text" is not often
useful with a single part---especially a non-text part).

Here, we update the documentation to match.
---

diff --git a/notmuch.1 b/notmuch.1
index 76222981..82b48c3b 100644
--- a/notmuch.1
+++ b/notmuch.1
@@ -252,7 +252,7 @@ matched message will be displayed.
 
 .RS 4
 .TP 4
-.B text
+.BR text " (default for messages)"
 
 The default plain-text format has all text-content MIME parts
 decoded. Various components in the output,
@@ -291,12 +291,17 @@ http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
 .RE
 .RS 4
 .TP 4
-.B raw
+.BR raw " (default for a single part, see \-\-part)"
 
-The original, raw content of the email message is displayed.
-Consumers of this format should expect to implement MIME decoding and
-similar functions. This format must only be used with search terms
-matching a single message.
+For a message, the original, raw content of the email message is
+output. Consumers of this format should expect to implement MIME
+decoding and similar functions.
+
+For a single part (\-\-part) the raw part content is output after
+performing any necessary MIME decoding.
+
+The raw format must only be used with search terms matching single
+message.
 .RE
 .RE
 
diff --git a/notmuch.c b/notmuch.c
index dc21096c..9bb88471 100644
--- a/notmuch.c
+++ b/notmuch.c
@@ -241,7 +241,7 @@ static command_t commands[] = {
       "\n"
       "\t--format=(text|json|mbox|raw)\n"
       "\n"
-      "\t\ttext (default)\n"
+      "\t\ttext (default for messages)\n"
       "\n"
       "\t\tThe default plain-text format has all text-content MIME parts\n"
       "\t\tdecoded. Various components in the output, ('message', 'header',\n"
@@ -273,12 +273,17 @@ static command_t commands[] = {
       "\n"
       "\t\thttp://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html\n"
       "\n"
-      "\t\traw\n"
+      "\t\traw (default for a single part, see --part)\n"
       "\n"
-      "\t\tThe original, raw content of the email message is displayed.\n"
-      "\t\tConsumers of this format should expect to implement MIME\n"
-      "\t\tdecoding and similar functions. This format must only\n"
-      "\t\tbe used with search terms matching a single message.\n"
+      "\t\tFor a message, the original, raw content of the email\n"
+      "\t\tmessage is output. Consumers of this format should\n"
+      "\t\texpect to implement MIME decoding and similar functions.\n"
+      "\n"
+      "\t\tFor a single part (--part) the raw part content is output\n"
+      "\t\tafter performing any necessary MIME decoding.\n"
+      "\n"
+      "\t\tThe raw format must only be used with search terms matching\n"
+      "\t\tsingle message.\n"
       "\n"
       "\t--part=N\n"
       "\n"