Add documentation for the recently added folder-based searching.

[notmuch] / notmuch.c

diff --git a/notmuch.c b/notmuch.c
index 0eea5e11f20c49af89587aaddaa171fd6361c7c0..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\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"
     "\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"
     "\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"
     "\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\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"
       "\t--sort=(newest-first|oldest-first)\n"
       "\n"
       "\t\tPresent results in either chronological order\n"


@@ -189,12 +228,12 @@ command_t commands[] = {
       "\t\tall messages in the same thread as any matched\n"
       "\t\tmessage will be displayed.\n"
       "\n"
       "\t\tall messages in the same thread as any matched\n"
       "\t\tmessage will be displayed.\n"
       "\n"

-      "\t--format=(json|text)\n"
+      "\t--format=(text|json|mbox|raw)\n"

       "\n"
       "\n"

-      "\t\ttext\t(default)\n"
+      "\t\ttext (default)\n"

       "\n"
       "\n"

-      "\t\tThe plain-text has all text-content MIME parts decoded.\n"
-      "\t\tVarious components in the output, ('message', 'header',\n"
+      "\t\tThe default plain-text format has all text-content MIME parts\n"
+      "\t\tdecoded. Various components in the output, ('message', 'header',\n"

       "\t\t'body', 'attachment', and MIME 'part') are delimited by\n"
       "\t\teasily-parsed markers. Each marker consists of a Control-L\n"
       "\t\tcharacter (ASCII decimal 12), the name of the marker, and\n"
       "\t\t'body', 'attachment', and MIME 'part') are delimited by\n"
       "\t\teasily-parsed markers. Each marker consists of a Control-L\n"
       "\t\tcharacter (ASCII decimal 12), the name of the marker, and\n"


@@ -203,9 +242,30 @@ command_t commands[] = {
       "\n"
       "\t\tjson\n"
       "\n"
       "\n"
       "\t\tjson\n"
       "\n"

-      "\t\tFormat output as Javascript Object Notation (JSON).\n"
-      "\t\tJSON output always includes all messages in a matching,\n"
-      "\t\tthread i.e. '--output=json' implies '--entire-thread'\n"
+      "\t\tThe output is formatted with Javascript Object Notation\n"
+      "\t\t(JSON). This format is more robust than the text format\n"
+      "\t\tfor automated processing. JSON output always includes all\n"
+      "\t\tmessages in a matching thread; in effect '--format=json'\n"
+      "\t\timplies '--entire-thread'\n"
+      "\n"
+      "\t\tmbox\n"
+      "\n"
+      "\t\tAll matching messages are output in the traditional, Unix\n"
+      "\t\tmbox format with each message being prefixed by a line\n"
+      "\t\tbeginning with 'From ' and a blank line separating each\n"
+      "\t\tmessage. Lines in the message content beginning with 'From '\n"
+      "\t\t(preceded by zero or more '>' characters) have an additional\n"
+      "\t\t'>' character added. This reversible escaping is termed\n"
+      "\t\t\"mboxrd\" format and described in detail here:\n"
+      "\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"
       "\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"


@@ -307,6 +367,31 @@ command_t commands[] = {
       "\tby the \"--format=json\" option of \"notmuch show\". If the\n"
       "\tmessage specified by the search terms does not include a\n"
       "\tpart with the specified \"id\" there will be no output." },
       "\tby the \"--format=json\" option of \"notmuch show\". If the\n"
       "\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|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\n"
+      "\n"
+      "\t\tdatabase.path\n"
+      "\t\tuser.name\n"
+      "\t\tuser.primary_email\n"
+      "\t\tuser.other_email\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.",
     { "help", notmuch_help_command,
       "[<command>]",
       "This message, or more detailed help for the named command.",