[PATCH] notmuch.pod: pod version of documentation, converted by rman, massaged by hand.

[david at tethera.net]

From: David Bremner <bremner at 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.

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<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.
+
+=head2 Using notmuch
+
+The B<search> and B<show> commands are used to query the email
+database.  The B<tag> 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<SEARCH SYNTAX>
+section below for more details on the supported syntax.
+
+=head2 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 L<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.
+
+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.
+
+=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.
+
+=item B<--format=(json|text)>
+
+=over
+
+=item B<text>
+
+The default plain-text format has 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.
+
+=item B<json>
+
+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<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>.
+
+=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<--format=>(B<json>|B<text>)
+
+Presents the results in either JSON or plain-text (default).
+
+=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 count <search-term>...
+
+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...] <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.  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<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.
+
+=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).
+
+=head2 part --part=<part-number> <search-term>...
+
+
+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<SEARCH SYNTAX> section below for details
+of the supported syntax for <search-terms>.
+
+=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 <brackets> indicate user-supplied values):
+
+
+        from:<name-or-address>
+        to:<name-or-address>
+        subject:<word-or-quoted-phrase>
+        attachment:<word>
+        tag:<tag> (or is:<tag>)
+        id:<message-id>
+        thread:<thread-id>
+
+
+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:> and B<is:> 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:
+
+    <initial-timestamp>..<final-timestamp>
+
+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<NOTMUCH_CONFIG>
+
+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<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 at 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.7.1