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 C71374196F4 for ; Sun, 13 Jun 2010 08:02:07 -0700 (PDT) X-Virus-Scanned: Debian amavisd-new at olra.theworths.org X-Spam-Flag: NO X-Spam-Score: -1.9 X-Spam-Level: X-Spam-Status: No, score=-1.9 tagged_above=-999 required=5 tests=[BAYES_00=-1.9] autolearn=ham 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 KL9anZhoFnLg for ; Sun, 13 Jun 2010 08:01:56 -0700 (PDT) Received: from pivot.cs.unb.ca (pivot.cs.unb.ca [131.202.240.57]) by olra.theworths.org (Postfix) with ESMTP id EA2DB431FC1 for ; Sun, 13 Jun 2010 08:01:55 -0700 (PDT) Received: from fctnnbsc30w-142167182069.pppoe-dynamic.high-speed.nb.bellaliant.net ([142.167.182.69] 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 1ONoh6-00015s-Ad; Sun, 13 Jun 2010 12:01:53 -0300 Received: from bremner by rocinante.cs.unb.ca with local (Exim 4.71) (envelope-from ) id 1ONoh0-0001Mt-MR; Sun, 13 Jun 2010 12:01:46 -0300 From: david@tethera.net To: notmuch@notmuchmail.org Subject: [PATCH] notmuch.pod: pod version of documentation, converted by rman, massaged by hand. Date: Sun, 13 Jun 2010 12:01:30 -0300 Message-Id: <1276441290-5081-1-git-send-email-david@tethera.net> X-Mailer: git-send-email 1.7.1 In-Reply-To: <87d3xldbav.fsf@rocinante.cs.unb.ca> References: <87d3xldbav.fsf@rocinante.cs.unb.ca> X-Sender-Verified: bremner@pivot.cs.unb.ca Cc: David Bremner X-BeenThere: notmuch@notmuchmail.org X-Mailman-Version: 2.1.13 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: Sun, 13 Jun 2010 15:02:07 -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. I also moved show in front of search, because it explains the output formats. Probably it would make sense to add a separate section explaining common output formats. --- You can take a look at the HTML output at http://pivot.cs.unb.ca/scratch/notmuch.html We can also generate man pages and inline help from this file. I didn't get that far yet, waiting for more encouraging noises :). notmuch.pod | 361 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 361 insertions(+), 0 deletions(-) create mode 100644 notmuch.pod diff --git a/notmuch.pod b/notmuch.pod new file mode 100644 index 0000000..719dead --- /dev/null +++ b/notmuch.pod @@ -0,0 +1,361 @@ +=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. + +=head2 Using notmuch + +The B and B commands are used to query the email +database. The B command is the only command available for +manipulating database contents. Several of the notmuch commands +accept search terms with a common syntax. See the B +section below for more details on the supported syntax. + +=head2 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 L 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. + +Invoking B with no command argument will run B if +B has previously been completed, but B has +not previously been run. + +=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. + +=item B<--format=(json|text)> + +=over + +=item B + +The default plain-text format has 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. + +=item B + +Format output as Javascript Object Notation (JSON). +JSON output always includes all messages in a matching thread; in effect +B<--format=json> implies B<--entire-thread>. + +=back + +=back + +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 . + +=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<--format=>(B|B) + +Presents the results in either JSON or plain-text (default). + +=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 count ... + +Count messages matching the search terms. + +The number of matching messages is output to stdout. With no search +terms, a count of all messages in the database will be displayed. + +=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. Values 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. + +=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). + +=head2 part --part=

... + + +Output a single MIME part of a message. A single decoded MIME part, +with no encoding or framing, is output to stdout. The search terms +must match only a single message, otherwise this command will fail. +The part number should match the part "id" field output by the +"--format=json" option of "notmuch show". If the message specified by +the search terms does not include a part with the specified "id" there +will be no output. See the B section below for details +of the supported syntax for . + +=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. + As +a special case, a search string consisting of exactly a single asterisk +("*") will match all messages. + 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): + + + from: + to: + subject: + attachment: + tag: (or is:) + id: + thread: + + +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 and 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: + + .. + +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: + + + $(date +%s -d 2009-10-01)..$(date +%s) + +=head1 Environment + +The following environment variables can be used to control +the behavior of notmuch. + +=over + +=item B + +Specifies the location of the notmuch +configuration file. Notmuch will use ${HOME}/.notmuch-config if this variable +is not set. + +=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.7.1