Update notmuch man page with recently-added documentation.

It would be nice to have this documentation live in a single place,
but for now, this is what we get.

diff --git a/notmuch.1 b/notmuch.1
index 08bcf147ca35f6500e912b06ea115d04297b0998..758207105352bf32e3e7c7f65faf2c8eaecf18ae 100644 (file)
--- a/notmuch.1
+++ b/notmuch.1
@@ -112,13 +112,33 @@ The output consists of one line per thread, giving a thread ID, the
 date of the oldest matched message in the thread, and the subject from
 that message.
 
-Currently, the supported search terms are as follows, (where
-<brackets> indicate user-supplied values):
+Currently, in addition to free text (and quoted phrases) which match
+terms appearing anywhere within an email, the following prefixes can
+be used to search specific portions of an email, (where <brackets>
+indicate user-supplied values):
+
+       from:<name-or-address>
+
+       to:<name-or-address>
+
+       subject:<word-or-quoted-phrase>
 
        tag:<tag>
+
        id:<message-id>
+
        thread:<thread-id>
 
+The from: prefix is used to match the name or address of the sender of
+an email message.
+
+The to: prefix is used to match the names or addresses of any
+recipient of an email message, (whether To, Cc, or Bcc).
+
+Any term prefixed with subject: will match only text from
+the subject of an email. Quoted phrases are supported when
+searching with: subject:\"this is a phrase\".
+
 Valid tag values include
 .BR inbox " and " unread
 by default for new messages added by
@@ -147,15 +167,30 @@ operators, but will have to be protected from interpretation by the
 shell, (such as by putting quotation marks around any parenthesized
 expression).
 .TP
-.BR show " <thread-ID>"
+.BR show " <search-term>..."
 
-Show the thread with the given thread ID.
+Shows all messages matching the search terms.
 
-Displays each message in the thread on stdout.
+See the documentation of
+.B search
+for details of the supported syntax of search terms.
 
-Thread ID values are given as the first column in the output of the
-"notmuch search" command. These are the random-looking strings of 32
-characters.
+A common use of
+.B notmuch show
+is to display a single thread of email messages. For this, use a
+search term of "thread:<thread-id>" as can be seen in the first
+column of output from the
+.B notmuch search
+command.
+
+All messages will be displayed in date order. The output format is
+plain-text, with 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
+Control-L character (ASCII decimal 12), the name of the marker, and
+then either an opening or closing brace, ('{' or '}'), to either open
+or close the component.
 .RE
 
 The

diff --git a/notmuch.c b/notmuch.c
index b6fbef41b1e2738069a7d7964bc3d4592592be29..b20b4065005630dfc3c5bc2d374516a819f77c33 100644 (file)
--- a/notmuch.c
+++ b/notmuch.c
@@ -1467,9 +1467,11 @@ command_t commands[] = {
       "\t\tNote that the individual mail messages will be matched\n"
       "\t\tagainst the search terms, but the results will be the\n"
       "\t\tthreads containing the matched messages.\n\n"
-      "\t\tCurrently, in addition to free text (and quoted phrases\n"
-      "\t\tthe following prefixed search terms are supported, (where\n"
-      "\t\t<brackets> indicate user-supplied values):\n\n"
+      "\t\tCurrently, in addition to free text (and quoted phrases)\n"
+      "\t\twhich match terms appearing anywhere within an email,\n"
+      "\t\tthe following prefixes can be used to search specific\n"
+      "\t\tportions of an email, (where <brackets> indicate user-\n"
+      "\t\tsupplied values):\n\n"
       "\t\t\tfrom:<name-or-address>\n"
       "\t\t\tto:<name-or-address>\n"
       "\t\t\tsubject:<word-or-quoted-phrase>\n"