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.
 
 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>
 
        tag:<tag>

+

        id:<message-id>
        id:<message-id>

+

        thread:<thread-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
 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
 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
 .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\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"
       "\t\t\tfrom:<name-or-address>\n"
       "\t\t\tto:<name-or-address>\n"
       "\t\t\tsubject:<word-or-quoted-phrase>\n"