[notmuch] [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.
---

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 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.6.5