[PATCH 1/4] 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.

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<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
+
+=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<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
+
+=for help args NULL
+
+=for help desc 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>...
+
+=for help args [options...] <search-term>...
+=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<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>...
+
+=for help args [options...] <search-term>...
+=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<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>...
+
+=for help args <search-term>...
+
+=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...] <search-term>...
+
+=for help args [options...] <search-term>...
+=for help desc Construct 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>...
+
+=for help args +<tag>|-<tag> [...] [--] <search-term>...
+
+=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<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>]
+
+=for help args [<filename>]
+=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 <filename>
+
+=for help args [<filename>]
+=for help desc Restore the tags from the given file (see <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>...
+
+=for help args --part=<part-number> <search-term>...
+=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<SEARCH SYNTAX>
+section below for details of the supported syntax for <search-terms>.
+
+=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 <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