Add documentation for the recently added folder-based searching.

[notmuch] / notmuch.c

diff --git a/notmuch.c b/notmuch.c
index f9acfa36aa23ef7dc88abdfdefd577085b792acb..c028aeb9aced5f9ab7a65946c46ef9c659ee7e50 100644 (file)
--- a/notmuch.c
+++ b/notmuch.c
@@ -58,6 +58,7 @@ static const char search_terms_help[] =
     "\t\ttag:<tag> (or is:<tag>)\n"
     "\t\tid:<message-id>\n"
     "\t\tthread:<thread-id>\n"
+    "\t\tfolder:<directory-path>\n"
     "\n"
     "\tThe from: prefix is used to match the name or address of\n"
     "\tthe sender of an email message.\n"
@@ -82,6 +83,11 @@ static const char search_terms_help[] =
     "\tmessages). These thread ID values can be seen in the first\n"
     "\tcolumn of output from \"notmuch search\".\n"
     "\n"
+    "\tThe folder: prefix can be used to search for email message\n"
+    "\tfiles that are contained within particular directories within\n"
+    "\tthe mail store. Only the directory components below the top-level\n"
+    "\tmail database path are available to be searched.\n"
+    "\n"
     "\tIn addition to individual terms, multiple terms can be\n"
     "\tcombined with Boolean operators (\"and\", \"or\", \"not\", etc.).\n"
     "\tEach term in the query will be implicitly connected by a\n"
@@ -165,6 +171,39 @@ command_t commands[] = {
       "\t\tPresents the results in either JSON or\n"
       "\t\tplain-text (default)\n"
       "\n"
+      "\t--output=(summary|threads|messages|files|tags)\n"
+      "\n"
+      "\t\tsummary (default)\n"
+      "\n"
+      "\t\tOutput a summary of each thread with any message matching the\n"
+      "\t\tsearch terms. The summary includes the thread ID, date, the\n"
+      "\t\tnumber of messages in the thread (both the number matched and\n"
+      "\t\tthe total number), the authors of the thread and the subject.\n"
+      "\n"
+      "\t\tthreads\n"
+      "\n"
+      "\t\tOutput the thread IDs of all threads with any message matching\n"
+      "\t\tthe search terms, either one per line (--format=text) or as a\n"
+      "\t\tJSON array (--format=json).\n"
+      "\n"
+      "\t\tmessages\n"
+      "\n"
+      "\t\tOutput the message IDs of all messages matching the search\n"
+      "\t\tterms, either one per line (--format=text) or as a JSON array\n"
+      "\t\t(--format=json).\n"
+      "\n"
+      "\t\tfiles\n"
+      "\n"
+      "\t\tOutput the filenames of all messages matching the search\n"
+      "\t\tterms, either one per line (--format=text) or as a JSON array\n"
+      "\t\t(--format=json).\n"
+      "\n"
+      "\t\ttags\n"
+      "\n"
+      "\t\tOutput all tags that appear on any message matching the search\n"
+      "\t\tterms, either one per line (--format=text) or as a JSON array\n"
+      "\t\t(--format=json).\n"
+      "\n"
       "\t--sort=(newest-first|oldest-first)\n"
       "\n"
       "\t\tPresent results in either chronological order\n"
@@ -189,7 +228,7 @@ command_t commands[] = {
       "\t\tall messages in the same thread as any matched\n"
       "\t\tmessage will be displayed.\n"
       "\n"
-      "\t--format=(text|json|mbox)\n"
+      "\t--format=(text|json|mbox|raw)\n"
       "\n"
       "\t\ttext (default)\n"
       "\n"
@@ -221,6 +260,13 @@ command_t commands[] = {
       "\n"
       "\t\thttp://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html\n"
       "\n"
+      "\t\traw\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"
+      "\n"
       "\tA common use of \"notmuch show\" is to display a single\n"
       "\tthread of email messages. For this, use a search term of\n"
       "\t\"thread:<thread-id>\" as can be seen in the first column\n"
@@ -322,19 +368,30 @@ command_t commands[] = {
       "\tmessage specified by the search terms does not include a\n"
       "\tpart with the specified \"id\" there will be no output." },
     { "config", notmuch_config_command,
-      "get <section>.<item>",
-      "Get settings from the notmuch configuration file.",
+      "[get|set] <section>.<item> [value ...]",
+      "Get or set settings in the notmuch configuration file.",
+      "    config get <section>.<item>\n"
+      "\n"
       "\tThe value of the specified configuration item is printed\n"
       "\tto stdout. If the item has multiple values, each value\n"
       "\tis separated by a newline character.\n"
       "\n"
-      "\tAvailable configuration items include at least"
+      "\tAvailable configuration items include at least\n"
       "\n"
       "\t\tdatabase.path\n"
       "\t\tuser.name\n"
       "\t\tuser.primary_email\n"
       "\t\tuser.other_email\n"
-      "\t\tnew.tags\n" },
+      "\t\tnew.tags\n"
+      "\n"
+      "    config set <section>.<item> [value ...]\n"
+      "\n"
+      "\tThe specified configuration item is set to the given value.\n"
+      "\tTo specify a multiple-value item, provide each value as\n"
+      "\ta separate command-line argument.\n"
+      "\n"
+      "\tIf no values are provided, the specified configuration item\n"
+      "\twill be removed from the configuration file." },
     { "help", notmuch_help_command,
       "[<command>]",
       "This message, or more detailed help for the named command.",