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 D225140D14B for ; Wed, 3 Nov 2010 10:19:53 -0700 (PDT) X-Virus-Scanned: Debian amavisd-new at olra.theworths.org X-Spam-Flag: NO X-Spam-Score: -2.6 X-Spam-Level: X-Spam-Status: No, score=-2.6 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, RCVD_IN_DNSWL_LOW=-0.7] 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 p2vKz8lAT1Hs for ; Wed, 3 Nov 2010 10:19:41 -0700 (PDT) Received: from tempo.its.unb.ca (tempo.its.unb.ca [131.202.1.21]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by olra.theworths.org (Postfix) with ESMTPS id 52DF74196F2 for ; Wed, 3 Nov 2010 10:19:35 -0700 (PDT) Received: from rocinante.cs.unb.ca (fctnnbsc30w-142167176217.pppoe-dynamic.High-Speed.nb.bellaliant.net [142.167.176.217]) (authenticated bits=0) by tempo.its.unb.ca (8.13.8/8.13.8) with ESMTP id oA3HJYns014327 (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NO); Wed, 3 Nov 2010 14:19:34 -0300 Received: from bremner by rocinante.cs.unb.ca with local (Exim 4.72) (envelope-from ) id 1PDgzm-0001Ox-3o; Wed, 03 Nov 2010 14:19:34 -0300 From: david@tethera.net To: notmuch@notmuchmail.org Subject: [PATCH 1/4] notmuch.pod: pod version of documentation, converted by rman, massaged by hand. Date: Wed, 3 Nov 2010 14:18:53 -0300 Message-Id: <1288804736-5173-2-git-send-email-david@tethera.net> X-Mailer: git-send-email 1.7.1 In-Reply-To: <874oc4r4bu.fsf@yoom.home.cworth.org> References: <874oc4r4bu.fsf@yoom.home.cworth.org> 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: Wed, 03 Nov 2010 17:19:54 -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. The =for help lines are ignored for the man page, but used to generate the online help. I also added dummy sections for currently undocumented commands; or more precisely, commands that were not documented that last time I refreshed notmuch.pod. --- notmuch.pod | 409 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 409 insertions(+), 0 deletions(-) create mode 100644 notmuch.pod diff --git a/notmuch.pod b/notmuch.pod new file mode 100644 index 0000000..f4127e0 --- /dev/null +++ b/notmuch.pod @@ -0,0 +1,409 @@ +=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 + +=for help args NULL + +=for help desc 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 + +=for help args NULL + +=for help desc 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...] ... + +=for help args [options...] ... +=for help desc 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...] ... + +=for help args [options...] ... +=for help desc Search threads containing messages matching the given search terms. + +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 ... + +=for help args ... + +=for help desc 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...] ... + +=for help args [options...] ... +=for help desc Construct 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 +|- [...] [--] ... + +=for help args +|- [...] [--] ... + +=for help desc 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 [] + +=for help args [] +=for help desc Create 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 + +=for help args [] +=for help desc Restore the tags from the given file (see ). + +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=

... + +=for help args --part=

... +=for help desc 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 . + +=head2 search-tags + +=for help args dummy args +=for help desc dummy description + +dummy text + +=head2 config + +=for help args dummy args +=for help desc dummy description + +dummy text + +=head2 help + +=for help args dummy args +=for help desc dummy description + +dummy text + + +=head1 Search Syntax + +=for help name 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