From db81b31c56d87912f5c8e8265b079c2fcfcb5c37 Mon Sep 17 00:00:00 2001 From: Carl Worth Date: Thu, 5 Nov 2009 10:45:40 -0800 Subject: [PATCH] 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. --- notmuch.1 | 51 +++++++++++++++++++++++++++++++++++++++++++-------- notmuch.c | 8 +++++--- 2 files changed, 48 insertions(+), 11 deletions(-) diff --git a/notmuch.1 b/notmuch.1 index 08bcf147..75820710 100644 --- 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 - 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 +indicate user-supplied values): + + from: + + to: + + subject: tag: + id: + thread: +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 " " +.BR show " ..." -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:" 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 b6fbef41..b20b4065 100644 --- 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 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 indicate user-\n" + "\t\tsupplied values):\n\n" "\t\t\tfrom:\n" "\t\t\tto:\n" "\t\t\tsubject:\n" -- 2.43.0