From: David Bremner <bremner@unb.ca> 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<notmuch> I<command> [I<args> ...] + +=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<notmuch> command with no arguments, which will interactively +guide you through the process of indexing your mail. + +=head1 Note + +While the command-line +program B<notmuch> 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<notmuch setup> 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<notmuch setup> + +Invoking B<notmuch> with no command argument will run B<setup> if the +setup command has not previously been completed. + +=head2 new + +Find and import any new messages to the database. The B<new> 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<inbox> and B<unread> tags. +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 +time if you have a significant amount of mail (several hundred +thousand messages or more). Subsequently, you should run B<notmuch +new> 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<notmuch new> 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<notmuch new> even faster). +Invoking B<notmuch> with no command argument +will run B<new> if B<notmuch setup> has previously been completed, but B<notmuch +new> has not previously been run. +Several of the notmuch commands accept +search terms with a common syntax. See the B<SEARCH SYNTAX> section below for +more details on the supported syntax. +The B<search> and B<show> commands are +used to query the email database. + +=head2 search [options...] <search-term>... + +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<search> include + +=over + +=item B<--sort=>(B<newest-first>|B<oldest-first>) + +This option can be used +to present results in either chronological order (B<oldest-first>) or reverse +chronological order (B<newest-first>). +Note: The thread order will be distinct +between these two options (beyond being simply reversed). When sorting by +B<oldest-first> the threads will be sorted by the oldest message in each thread, +but when sorting by B<newest-first> 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<SEARCH SYNTAX> section below for details of the supported syntax +for B<search-terms>. + +=head2 show [options...] <search-term>... + +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<show> 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<message>, B<header>, B<body>, B<attachment>, and MIME +B<part>), 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<notmuch show> is to display a single thread of +email messages. For this, use a search term of "thread:<thread-id>" as can +be seen in the first column of output from the B<notmuch search> command. + +See the B<SEARCH SYNTAX> section below for details of the supported syntax +for <search-terms>. +The B<reply> command is useful for preparing a template for +an email reply. + +=head2 reply [options...] <search-term>... + +Constructs a reply template +for a set of messages. +To make replying to email easier, B<notmuch reply> +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<reply> include + +=over + +=item B<--format=>(B<default>|B<headers-only>) + +=over + +=item B<default> + +Includes +subject and quoted message body. + +=item B<headers-only> + +Only produces In-Reply-To, References, +To, Cc, and Bcc headers. +See the B<SEARCH SYNTAX> section below for details +of the supported syntax for <search-terms>. + +=back + +=back + +Note: It is most common to use +B<notmuch reply> with a search string matching a single message, (such as +id:<message-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 +<tag>|-<tag> [...] [--] <search-term>... + +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<search-terms> 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<SEARCH SYNTAX> section below for details of the supported syntax for I<search-terms>. +The B<dump> and B<restore> commands can be used to create a textual dump of +email tags for backup purposes, and to restore from that dump + +=head2 dump [<filename>] + +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 <filename> + +Restores the tags from the given file (see B<notmuch dump>. +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<notmuch restore> 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 <brackets> indicate user-supplied values): + +=over + +=begin text + + from:<name-or-address> + to:<name-or-address> + subject:<word-or-quoted-phrase> + attachment:<word> + tag:<tag> + id:<message-id> + thread:<thread-id> + +=end text + +=back + +The B<from:> prefix is used to match the name or address of the sender +of an email message. The B<to:> 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<subject:> 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<subject:>. + +The B<attachment:> +prefix can be used to search for specific filenames (or extensions) of +attachments to email messages. + +For B<tag:>, valid tag values include B<inbox> +and B<unread> by default for new messages added by B<notmuch new> as well as +any other tag values added manually with B<notmuch tag>. + +For B<id:>, message +ID values are the literal contents of the Message-ID: header of email messages, +but without the '<', '>' delimiters. + +The B<thread:> 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<notmuch search> + +In addition to individual terms, multiple +terms can be combined with Boolean operators ( B<and>, B<or>, B<not> , 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 + +<initial-timestamp>..<final-timestamp> + +=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<notmuch.el> in the Notmuch distribution). + +The notmuch website: L<http://notmuchmail.org> + +=head1 Contact + +Feel free to send questions, comments, or kudos to the notmuch mailing +list <notmuch@notmuchmail.org> . 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