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 76222981789d60ff001aa5d1317f2e8d347b6854..82b48c3b942758790017cf4a1e2cf957d637a7f4 100644 (file)
--- 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 dc21096c554a4f435bc4dfda021e041936ab50e1..9bb884712dbb86a6dc245219f2d4495dc3faf464 100644 (file)
--- 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"