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

[da...@tethera.net]

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 000..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-cont

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

[david]

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 000..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-cont