Return-Path: X-Original-To: notmuch@notmuchmail.org Delivered-To: notmuch@notmuchmail.org Received: from localhost (localhost [127.0.0.1]) by olra.theworths.org (Postfix) with ESMTP id 0FC53431FBC for ; Thu, 31 Dec 2009 09:41:43 -0800 (PST) X-Virus-Scanned: Debian amavisd-new at olra.theworths.org Received: from olra.theworths.org ([127.0.0.1]) by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id sfuUgftz6xd0 for ; Thu, 31 Dec 2009 09:41:41 -0800 (PST) Received: from pivot.cs.unb.ca (pivot.cs.unb.ca [131.202.240.57]) by olra.theworths.org (Postfix) with ESMTP id 75A11431FAE for ; Thu, 31 Dec 2009 09:41:41 -0800 (PST) Received: from fctnnbsc30w-142167182194.pppoe-dynamic.high-speed.nb.bellaliant.net ([142.167.182.194] helo=rocinante.cs.unb.ca) by pivot.cs.unb.ca with esmtpsa (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.69) (envelope-from ) id 1NQP1o-0000hB-0p; Thu, 31 Dec 2009 13:41:40 -0400 Received: from bremner by rocinante.cs.unb.ca with local (Exim 4.71) (envelope-from ) id 1NQOzv-0006Xr-Av; Thu, 31 Dec 2009 13:39:43 -0400 From: david@tethera.net To: notmuch@notmuchmail.org Date: Thu, 31 Dec 2009 13:39:29 -0400 Message-Id: <1262281169-24909-1-git-send-email-david@tethera.net> X-Mailer: git-send-email 1.6.5 X-Sender-Verified: bremner@pivot.cs.unb.ca Cc: David Bremner Subject: [notmuch] [PATCH] notmuch.pod: pod version of documentation, converted by rman, massaged by hand. X-BeenThere: notmuch@notmuchmail.org X-Mailman-Version: 2.1.12 Precedence: list List-Id: "Use and development of the notmuch mail system." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 31 Dec 2009 17:41:43 -0000 From: David Bremner Some places I deleted a bit of the continuity text introducing a command because I didn't see how to make it work with the slightly more structured layout. --- The idea here is to be able to generate the online help and the man page from one source. To generate a man page: pod2man notmuch.pod > notmuch.1 To generate help for a specific notmuch subcommand podselect -section 'Commands/subcommand.*' notmuch.pod | pod2text -c In principle the output from podselect could be compiled into notmuch. I'm not sure if the terminal escape codes are a good idea or not for that application, but they make pretty output. podselect and pod2man are included with perl 5.10.0; I'm not sure before that. notmuch.pod | 344 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 344 insertions(+), 0 deletions(-) create mode 100644 notmuch.pod diff --git a/notmuch.pod b/notmuch.pod new file mode 100644 index 0000000..680b5af --- /dev/null +++ b/notmuch.pod @@ -0,0 +1,344 @@ +=head1 Name +notmuch - thread-based email index, search, and tagging + +=head1 Synopsis + +=over + +=item B I [I ...] + +=back + +=head1 Description + +Notmuch is a command-line based +program for indexing, searching, reading, and tagging large collections +of email messages. + The quickest way to get started with Notmuch is to simply +invoke the B command with no arguments, which will interactively +guide you through the process of indexing your mail. + +=head1 Note + +While the command-line +program B provides powerful functionality, it does not provide the +most convenient interface for that functionality. More sophisticated interfaces +are expected to be built on top of either the command-line interface, or +more likely, on top of the notmuch library interface. See http://notmuchmail.org +for more about alternate interfaces to notmuch. + +=head1 Commands + +=head2 setup + +Interactively sets up notmuch for first use. The setup command will +prompt for your full name, your primary email address, any alternate +email addresses you use, and the directory containing your email +archives. Your answers will be written to a configuration file in +${NOTMUCH_CONFIG} (if set) or ${HOME}/.notmuch-config . This +configuration file will be created with descriptive comments, making +it easy to edit by hand later to change the configuration. Or you can +run B again to change the configuration. + +The mail directory you specify can contain any number of +sub-directories and should primarily contain only files with +individual email messages (eg. maildir or mh archives are perfect). If +there are other, non-email files (such as indexes maintained by other +email programs) then notmuch will do its best to detect those and +ignore them. + +Mail storage that uses mbox format, (where one mbox file contains many +messages), will not work with notmuch. If that's how your mail is +currently stored, it is recommended you first convert it to maildir +format with a utility such as mb2md before running B + +Invoking B with no command argument will run B if the +setup command has not previously been completed. + +=head2 new + +Find and import any new messages to the database. The B command +scans all sub-directories of the database, performing full-text +indexing on new messages that are found. Each new message will +automatically be tagged with both the B and B tags. +You should run B once after first running B to create the initial database. The first run may take a long +time if you have a significant amount of mail (several hundred +thousand messages or more). Subsequently, you should run B whenever new mail is delivered and you wish to incorporate it +into the database. These subsequent runs will be much quicker than +the initial run. + +Note: +B runs (other than the first run) will skip any read-only directories, +so you can use that to mark directories that will not receive any new mail +(and make B even faster). +Invoking B with no command argument +will run B if B has previously been completed, but B has not previously been run. +Several of the notmuch commands accept +search terms with a common syntax. See the B section below for +more details on the supported syntax. +The B and B commands are +used to query the email database. + +=head2 search [options...] ... + +Search for +messages matching the given search terms, and display as results the threads +containing the matched messages. +The output consists of one line per thread, +giving a thread ID, the date of the newest (or oldest, depending on the +sort option) matched message in the thread, the number of matched messages +and total messages in the thread, the names of all participants in the +thread, and the subject of the newest (or oldest) message. +Supported options +for B include + +=over + +=item B<--sort=>(B|B) + +This option can be used +to present results in either chronological order (B) or reverse +chronological order (B). +Note: The thread order will be distinct +between these two options (beyond being simply reversed). When sorting by +B the threads will be sorted by the oldest message in each thread, +but when sorting by B the threads will be sorted by the newest +message in each thread. +By default, results will be displayed in reverse +chronological order, (that is, the newest results will be displayed first). + +=back + +See the B section below for details of the supported syntax +for B. + +=head2 show [options...] ... + +Shows all messages matching +the search terms. +The messages will be grouped and sorted based on the +threading (all replies to a particular message will appear immediately +after that message in date order). The output is not indented by default, +but depth tags are printed so that proper indentation can be performed +by a post-processor (such as the emacs interface to notmuch). +Supported +options for B include + +=over + +=item B<--entire-thread> + +By default only those messages that +match the search terms will be displayed. With this option, all messages +in the same thread as any matched message will be displayed. + +=back + +The output +format is plain-text, with all text-content MIME parts decoded. Various +components in the output, (B, B

, B, B, and MIME +B), 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. + +A common use of B 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 command. + +See the B section below for details of the supported syntax +for . +The B command is useful for preparing a template for +an email reply. + +=head2 reply [options...] ... + +Constructs a reply template +for a set of messages. +To make replying to email easier, B +takes an existing set of messages and constructs a suitable mail template. +The Reply-to header (if any, otherwise From:) is used for the To: address. +Vales from the To: and Cc: headers are copied, but not including any of +the current user's email addresses (as configured in primary_mail or other_email +in the .notmuch-config file) in the recipient list +It also builds a suitable +new subject, including Re: at the front (if not already present), and adding +the message IDs of the messages being replied to to the References list +and setting the In-Reply-To: field correctly. +Finally, the original contents +of the emails are quoted by prefixing each line with '> ' and included in +the body. +The resulting message template is output to stdout. +Supported +options for B include + +=over + +=item B<--format=>(B|B) + +=over + +=item B + +Includes +subject and quoted message body. + +=item B + +Only produces In-Reply-To, References, +To, Cc, and Bcc headers. +See the B section below for details +of the supported syntax for . + +=back + +=back + +Note: It is most common to use +B with a search string matching a single message, (such as +id:), but it can be useful to reply to several messages at once. +For example, when a series of patches are sent in a single thread, replying +to the entire thread allows for the reply to comment on issue found in +multiple patches. + +=head2 tag +|- [...] [--] ... + +Add/remove tags for all +messages matching the search terms. +Tags prefixed by '+' are added while +those prefixed by '-' are removed. For each message, tag removal is performed +before tag addition. +The beginning of I is recognized by the +first argument that begins with neither '+' nor '-'. Support for an initial search +term beginning with '+' or '-' is provided by allowing the user to specify a +"--" argument to separate the tags from the search terms. +See the B section below for details of the supported syntax for I. +The B and B commands can be used to create a textual dump of +email tags for backup purposes, and to restore from that dump + +=head2 dump [] + +Creates a plain-text dump of the tags of each message. +The output is to +the given filename, if any, or to stdout. +These tags are the only data +in the notmuch database that can't be recreated from the messages themselves. +The output of notmuch dump is therefore the only critical thing to backup +(and much more friendly to incremental backup than the native database +files.) + +=head2 restore + +Restores the tags from the given file (see B. +Note: The dump file format is specifically chosen to be compatible +with the format of files produced by sup-dump. So if you've previously been +using sup for mail, then the B command provides you a way +to import all of your tags (or labels as sup calls them). + + +=head1 Search Syntax + +Several +notmuch commands accept a common syntax for search terms. +The search terms +can consist of free-form text (and quoted phrases) which will match all +messages that contain all of the given terms/phrases in the body, the subject, +or any of the sender or recipient headers. + +In addition to free text, the +following prefixes can be used to force terms to match against specific +portions of an email, (where indicate user-supplied values): + +=over + +=begin text + + from: + to: + subject: + attachment: + tag: + id: + thread: + +=end text + +=back + +The B prefix is used to match the name or address of the sender +of an email message. The B 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 B will match only text from +the subject of an email. + +Searching for a phrase in the subject is supported by including quotation +marks around the phrase, immediately following B. + +The B +prefix can be used to search for specific filenames (or extensions) of +attachments to email messages. + +For B, valid tag values include B +and B by default for new messages added by B as well as +any other tag values added manually with B. + +For B, message +ID values are the literal contents of the Message-ID: header of email messages, +but without the '<', '>' delimiters. + +The B prefix can be used with the +thread ID values that are generated internally by notmuch (and do not appear +in email messages). These thread ID values can be seen in the first column +of output from B + +In addition to individual terms, multiple +terms can be combined with Boolean operators ( B, B, B , etc.). Each +term in the query will be implicitly connected by a logical AND if no explicit +operator is provided, (except that terms with a common prefix will be implicitly +combined with OR until we get Xapian defect #402 fixed). +Parentheses can +also be used to control the combination of the Boolean operators, but will +have to be protected from interpretation by the shell, (such as by putting +quotation marks around any parenthesized expression). + +Finally, results +can be restricted to only messages within a particular time range, (based +on the Date: header) with a syntax of: + +=over + +.. + +=back + +Each timestamp is a number representing the number of seconds since +1970-01-01 00:00:00 UTC. This is not the most convenient means of +expressing date ranges, but until notmuch is fixed to accept a more +convenient form, one can use the date program to construct +timestamps. For example, with the bash shell the folowing syntax would +specify a date range to return messages from 2009-10-01 until the +current time: + +=over + +text $(date +%s -d 2009-10-01)..$(date +%s) + +=back + +=head1 See Also + +The emacs-based interface to notmuch (available +as B in the Notmuch distribution). + +The notmuch website: L + +=head1 Contact + +Feel free to send questions, comments, or kudos to the notmuch mailing +list . Subscription is not required before +posting, but is available from the notmuchmail.org website. + +Real-time interaction with the Notmuch community is available via IRC +(server: irc.freenode.net, channel: #notmuch). \ No newline at end of file -- 1.6.5