--- /dev/null
+Return-Path: <bremner@pivot.cs.unb.ca>\r
+X-Original-To: notmuch@notmuchmail.org\r
+Delivered-To: notmuch@notmuchmail.org\r
+Received: from localhost (localhost [127.0.0.1])\r
+ by olra.theworths.org (Postfix) with ESMTP id 0FC53431FBC\r
+ for <notmuch@notmuchmail.org>; Thu, 31 Dec 2009 09:41:43 -0800 (PST)\r
+X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
+Received: from olra.theworths.org ([127.0.0.1])\r
+ by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
+ with ESMTP id sfuUgftz6xd0 for <notmuch@notmuchmail.org>;\r
+ Thu, 31 Dec 2009 09:41:41 -0800 (PST)\r
+Received: from pivot.cs.unb.ca (pivot.cs.unb.ca [131.202.240.57])\r
+ by olra.theworths.org (Postfix) with ESMTP id 75A11431FAE\r
+ for <notmuch@notmuchmail.org>; Thu, 31 Dec 2009 09:41:41 -0800 (PST)\r
+Received: from\r
+ fctnnbsc30w-142167182194.pppoe-dynamic.high-speed.nb.bellaliant.net\r
+ ([142.167.182.194] helo=rocinante.cs.unb.ca)\r
+ by pivot.cs.unb.ca with esmtpsa (TLS1.0:RSA_AES_256_CBC_SHA1:32)\r
+ (Exim 4.69) (envelope-from <bremner@pivot.cs.unb.ca>)\r
+ id 1NQP1o-0000hB-0p; Thu, 31 Dec 2009 13:41:40 -0400\r
+Received: from bremner by rocinante.cs.unb.ca with local (Exim 4.71)\r
+ (envelope-from <bremner@rocinante.cs.unb.ca>)\r
+ id 1NQOzv-0006Xr-Av; Thu, 31 Dec 2009 13:39:43 -0400\r
+From: david@tethera.net\r
+To: notmuch@notmuchmail.org\r
+Date: Thu, 31 Dec 2009 13:39:29 -0400\r
+Message-Id: <1262281169-24909-1-git-send-email-david@tethera.net>\r
+X-Mailer: git-send-email 1.6.5\r
+X-Sender-Verified: bremner@pivot.cs.unb.ca\r
+Cc: David Bremner <bremner@unb.ca>\r
+Subject: [notmuch] [PATCH] notmuch.pod: pod version of documentation,\r
+ converted by rman, massaged by hand.\r
+X-BeenThere: notmuch@notmuchmail.org\r
+X-Mailman-Version: 2.1.12\r
+Precedence: list\r
+List-Id: "Use and development of the notmuch mail system."\r
+ <notmuch.notmuchmail.org>\r
+List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
+ <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
+List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
+List-Post: <mailto:notmuch@notmuchmail.org>\r
+List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
+List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
+ <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
+X-List-Received-Date: Thu, 31 Dec 2009 17:41:43 -0000\r
+\r
+From: David Bremner <bremner@unb.ca>\r
+\r
+Some places I deleted a bit of the continuity text introducing a\r
+command because I didn't see how to make it work with the slightly\r
+more structured layout.\r
+---\r
+\r
+The idea here is to be able to generate the online help and the man page from one source.\r
+\r
+To generate a man page:\r
+ \r
+ pod2man notmuch.pod > notmuch.1\r
+\r
+To generate help for a specific notmuch subcommand\r
+\r
+ podselect -section 'Commands/subcommand.*' notmuch.pod | pod2text -c\r
+\r
+In principle the output from podselect could be compiled into notmuch.\r
+I'm not sure if the terminal escape codes are a good idea or not for\r
+that application, but they make pretty output.\r
+\r
+podselect and pod2man are included with perl 5.10.0; I'm not sure\r
+before that.\r
+\r
+ notmuch.pod | 344 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++\r
+ 1 files changed, 344 insertions(+), 0 deletions(-)\r
+ create mode 100644 notmuch.pod\r
+\r
+diff --git a/notmuch.pod b/notmuch.pod\r
+new file mode 100644\r
+index 0000000..680b5af\r
+--- /dev/null\r
++++ b/notmuch.pod\r
+@@ -0,0 +1,344 @@\r
++=head1 Name\r
++notmuch - thread-based email index, search, and tagging\r
++\r
++=head1 Synopsis\r
++\r
++=over \r
++\r
++=item B<notmuch> I<command> [I<args> ...]\r
++\r
++=back\r
++\r
++=head1 Description\r
++\r
++Notmuch is a command-line based\r
++program for indexing, searching, reading, and tagging large collections\r
++of email messages. \r
++ The quickest way to get started with Notmuch is to simply\r
++invoke the B<notmuch> command with no arguments, which will interactively\r
++guide you through the process of indexing your mail.\r
++\r
++=head1 Note\r
++\r
++While the command-line\r
++program B<notmuch> provides powerful functionality, it does not provide the\r
++most convenient interface for that functionality. More sophisticated interfaces\r
++are expected to be built on top of either the command-line interface, or\r
++more likely, on top of the notmuch library interface. See http://notmuchmail.org\r
++for more about alternate interfaces to notmuch.\r
++\r
++=head1 Commands\r
++\r
++=head2 setup\r
++\r
++Interactively sets up notmuch for first use. The setup command will\r
++prompt for your full name, your primary email address, any alternate\r
++email addresses you use, and the directory containing your email\r
++archives. Your answers will be written to a configuration file in\r
++${NOTMUCH_CONFIG} (if set) or ${HOME}/.notmuch-config . This\r
++configuration file will be created with descriptive comments, making\r
++it easy to edit by hand later to change the configuration. Or you can\r
++run B<notmuch setup> again to change the configuration.\r
++\r
++The mail directory you specify can contain any number of\r
++sub-directories and should primarily contain only files with\r
++individual email messages (eg. maildir or mh archives are perfect). If\r
++there are other, non-email files (such as indexes maintained by other\r
++email programs) then notmuch will do its best to detect those and\r
++ignore them.\r
++\r
++Mail storage that uses mbox format, (where one mbox file contains many\r
++messages), will not work with notmuch. If that's how your mail is\r
++currently stored, it is recommended you first convert it to maildir\r
++format with a utility such as mb2md before running B<notmuch setup>\r
++\r
++Invoking B<notmuch> with no command argument will run B<setup> if the\r
++setup command has not previously been completed.\r
++\r
++=head2 new\r
++\r
++Find and import any new messages to the database. The B<new> command\r
++scans all sub-directories of the database, performing full-text\r
++indexing on new messages that are found. Each new message will\r
++automatically be tagged with both the B<inbox> and B<unread> tags.\r
++You should run B<notmuch new> once after first running B<notmuch setup> to create the initial database. The first run may take a long\r
++time if you have a significant amount of mail (several hundred\r
++thousand messages or more). Subsequently, you should run B<notmuch\r
++new> whenever new mail is delivered and you wish to incorporate it\r
++into the database. These subsequent runs will be much quicker than\r
++the initial run.\r
++\r
++Note:\r
++B<notmuch new> runs (other than the first run) will skip any read-only directories,\r
++so you can use that to mark directories that will not receive any new mail\r
++(and make B<notmuch new> even faster). \r
++Invoking B<notmuch> with no command argument\r
++will run B<new> if B<notmuch setup> has previously been completed, but B<notmuch\r
++new> has not previously been run. \r
++Several of the notmuch commands accept\r
++search terms with a common syntax. See the B<SEARCH SYNTAX> section below for\r
++more details on the supported syntax. \r
++The B<search> and B<show> commands are\r
++used to query the email database. \r
++\r
++=head2 search [options...] <search-term>... \r
++\r
++Search for\r
++messages matching the given search terms, and display as results the threads\r
++containing the matched messages. \r
++The output consists of one line per thread,\r
++giving a thread ID, the date of the newest (or oldest, depending on the\r
++sort option) matched message in the thread, the number of matched messages\r
++and total messages in the thread, the names of all participants in the\r
++thread, and the subject of the newest (or oldest) message. \r
++Supported options\r
++for B<search> include \r
++\r
++=over\r
++\r
++=item B<--sort=>(B<newest-first>|B<oldest-first>) \r
++\r
++This option can be used\r
++to present results in either chronological order (B<oldest-first>) or reverse\r
++chronological order (B<newest-first>). \r
++Note: The thread order will be distinct\r
++between these two options (beyond being simply reversed). When sorting by\r
++B<oldest-first> the threads will be sorted by the oldest message in each thread,\r
++but when sorting by B<newest-first> the threads will be sorted by the newest\r
++message in each thread. \r
++By default, results will be displayed in reverse\r
++chronological order, (that is, the newest results will be displayed first).\r
++\r
++=back\r
++\r
++See the B<SEARCH SYNTAX> section below for details of the supported syntax\r
++for B<search-terms>. \r
++\r
++=head2 show [options...] <search-term>... \r
++\r
++Shows all messages matching\r
++the search terms. \r
++The messages will be grouped and sorted based on the\r
++threading (all replies to a particular message will appear immediately\r
++after that message in date order). The output is not indented by default,\r
++but depth tags are printed so that proper indentation can be performed\r
++by a post-processor (such as the emacs interface to notmuch). \r
++Supported\r
++options for B<show> include \r
++\r
++=over \r
++\r
++=item B<--entire-thread> \r
++\r
++By default only those messages that\r
++match the search terms will be displayed. With this option, all messages\r
++in the same thread as any matched message will be displayed. \r
++\r
++=back\r
++\r
++The output\r
++format is plain-text, with all text-content MIME parts decoded. Various\r
++components in the output, (B<message>, B<header>, B<body>, B<attachment>, and MIME\r
++B<part>), will be delimited by easily-parsed markers. Each marker consists of\r
++a Control-L character (ASCII decimal 12), the name of the marker, and then\r
++either an opening or closing brace, ('{' or '}'), to either open or close the\r
++component. \r
++\r
++A common use of B<notmuch show> is to display a single thread of\r
++email messages. For this, use a search term of "thread:<thread-id>" as can\r
++be seen in the first column of output from the B<notmuch search> command. \r
++\r
++See the B<SEARCH SYNTAX> section below for details of the supported syntax\r
++for <search-terms>. \r
++The B<reply> command is useful for preparing a template for\r
++an email reply. \r
++\r
++=head2 reply [options...] <search-term>... \r
++\r
++Constructs a reply template\r
++for a set of messages. \r
++To make replying to email easier, B<notmuch reply>\r
++takes an existing set of messages and constructs a suitable mail template.\r
++The Reply-to header (if any, otherwise From:) is used for the To: address.\r
++Vales from the To: and Cc: headers are copied, but not including any of\r
++the current user's email addresses (as configured in primary_mail or other_email\r
++in the .notmuch-config file) in the recipient list \r
++It also builds a suitable\r
++new subject, including Re: at the front (if not already present), and adding\r
++the message IDs of the messages being replied to to the References list\r
++and setting the In-Reply-To: field correctly. \r
++Finally, the original contents\r
++of the emails are quoted by prefixing each line with '> ' and included in\r
++the body. \r
++The resulting message template is output to stdout. \r
++Supported\r
++options for B<reply> include \r
++\r
++=over\r
++\r
++=item B<--format=>(B<default>|B<headers-only>) \r
++\r
++=over\r
++\r
++=item B<default> \r
++\r
++Includes\r
++subject and quoted message body. \r
++\r
++=item B<headers-only> \r
++\r
++Only produces In-Reply-To, References,\r
++To, Cc, and Bcc headers. \r
++See the B<SEARCH SYNTAX> section below for details\r
++of the supported syntax for <search-terms>. \r
++\r
++=back\r
++\r
++=back\r
++\r
++Note: It is most common to use\r
++B<notmuch reply> with a search string matching a single message, (such as\r
++id:<message-id>), but it can be useful to reply to several messages at once.\r
++For example, when a series of patches are sent in a single thread, replying\r
++to the entire thread allows for the reply to comment on issue found in\r
++multiple patches. \r
++\r
++=head2 tag +<tag>|-<tag> [...] [--] <search-term>... \r
++\r
++Add/remove tags for all\r
++messages matching the search terms. \r
++Tags prefixed by '+' are added while\r
++those prefixed by '-' are removed. For each message, tag removal is performed\r
++before tag addition. \r
++The beginning of I<search-terms> is recognized by the\r
++first argument that begins with neither '+' nor '-'. Support for an initial search\r
++term beginning with '+' or '-' is provided by allowing the user to specify a\r
++"--" argument to separate the tags from the search terms. \r
++See the B<SEARCH SYNTAX> section below for details of the supported syntax for I<search-terms>.\r
++The B<dump> and B<restore> commands can be used to create a textual dump of\r
++email tags for backup purposes, and to restore from that dump \r
++\r
++=head2 dump [<filename>]\r
++\r
++Creates a plain-text dump of the tags of each message. \r
++The output is to\r
++the given filename, if any, or to stdout. \r
++These tags are the only data\r
++in the notmuch database that can't be recreated from the messages themselves.\r
++The output of notmuch dump is therefore the only critical thing to backup\r
++(and much more friendly to incremental backup than the native database\r
++files.) \r
++\r
++=head2 restore <filename> \r
++\r
++Restores the tags from the given file (see B<notmuch dump>. \r
++Note: The dump file format is specifically chosen to be compatible\r
++with the format of files produced by sup-dump. So if you've previously been\r
++using sup for mail, then the B<notmuch restore> command provides you a way\r
++to import all of your tags (or labels as sup calls them).\r
++\r
++\r
++=head1 Search Syntax\r
++\r
++Several\r
++notmuch commands accept a common syntax for search terms. \r
++The search terms\r
++can consist of free-form text (and quoted phrases) which will match all\r
++messages that contain all of the given terms/phrases in the body, the subject,\r
++or any of the sender or recipient headers. \r
++\r
++In addition to free text, the\r
++following prefixes can be used to force terms to match against specific\r
++portions of an email, (where <brackets> indicate user-supplied values): \r
++\r
++=over\r
++\r
++=begin text\r
++\r
++ from:<name-or-address> \r
++ to:<name-or-address> \r
++ subject:<word-or-quoted-phrase> \r
++ attachment:<word> \r
++ tag:<tag> \r
++ id:<message-id> \r
++ thread:<thread-id> \r
++\r
++=end text\r
++\r
++=back\r
++\r
++The B<from:> prefix is used to match the name or address of the sender\r
++of an email message. The B<to:> prefix is used to match the names or\r
++addresses of any recipient of an email message, (whether To, Cc, or\r
++Bcc). Any term prefixed with B<subject:> will match only text from\r
++the subject of an email.\r
++\r
++Searching for a phrase in the subject is supported by including quotation\r
++marks around the phrase, immediately following B<subject:>. \r
++\r
++The B<attachment:>\r
++prefix can be used to search for specific filenames (or extensions) of\r
++attachments to email messages. \r
++\r
++For B<tag:>, valid tag values include B<inbox>\r
++and B<unread> by default for new messages added by B<notmuch new> as well as\r
++any other tag values added manually with B<notmuch tag>. \r
++\r
++For B<id:>, message\r
++ID values are the literal contents of the Message-ID: header of email messages,\r
++but without the '<', '>' delimiters. \r
++\r
++The B<thread:> prefix can be used with the\r
++thread ID values that are generated internally by notmuch (and do not appear\r
++in email messages). These thread ID values can be seen in the first column\r
++of output from B<notmuch search> \r
++\r
++In addition to individual terms, multiple\r
++terms can be combined with Boolean operators ( B<and>, B<or>, B<not> , etc.). Each\r
++term in the query will be implicitly connected by a logical AND if no explicit\r
++operator is provided, (except that terms with a common prefix will be implicitly\r
++combined with OR until we get Xapian defect #402 fixed). \r
++Parentheses can\r
++also be used to control the combination of the Boolean operators, but will\r
++have to be protected from interpretation by the shell, (such as by putting\r
++quotation marks around any parenthesized expression). \r
++\r
++Finally, results\r
++can be restricted to only messages within a particular time range, (based\r
++on the Date: header) with a syntax of: \r
++\r
++=over\r
++\r
++<initial-timestamp>..<final-timestamp> \r
++\r
++=back\r
++\r
++Each timestamp is a number representing the number of seconds since\r
++1970-01-01 00:00:00 UTC. This is not the most convenient means of\r
++expressing date ranges, but until notmuch is fixed to accept a more\r
++convenient form, one can use the date program to construct\r
++timestamps. For example, with the bash shell the folowing syntax would\r
++specify a date range to return messages from 2009-10-01 until the\r
++current time:\r
++\r
++=over \r
++\r
++text $(date +%s -d 2009-10-01)..$(date +%s) \r
++\r
++=back\r
++\r
++=head1 See Also \r
++\r
++The emacs-based interface to notmuch (available\r
++as B<notmuch.el> in the Notmuch distribution). \r
++\r
++The notmuch website: L<http://notmuchmail.org>\r
++\r
++=head1 Contact \r
++\r
++Feel free to send questions, comments, or kudos to the notmuch mailing\r
++list <notmuch@notmuchmail.org> . Subscription is not required before\r
++posting, but is available from the notmuchmail.org website. \r
++\r
++Real-time interaction with the Notmuch community is available via IRC\r
++(server: irc.freenode.net, channel: #notmuch).\r
+\ No newline at end of file\r
+-- \r
+1.6.5\r
+\r
projects / notmuch-archives.git / commitdiff