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

2009-12-31 Thread 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.
---

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 000..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 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.
+
+=head1 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 
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 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
+
+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.
+
+Note:
+B 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 even faster). 
+Invoking B with no command argument
+will run B if B has previously been completed, but 
B has not previously been run. 
+Several of the notmuch commands accept
+search terms with a common syntax. See the B section below for
+more details on the supported syntax. 
+The B and B commands are
+used to query the email database. 
+
+=head2 search [options...] ... 
+
+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 include 
+
+=over
+
+=item B<--sort=>(B|B) 
+
+This option can be used
+to present results in either chronological order (B) or reverse
+chronological order (B). 
+Note: 

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

2009-12-31 Thread 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.
---

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 000..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 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.
+
+=head1 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 
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 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
+
+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.
+
+Note:
+B 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 even faster). 
+Invoking B with no command argument
+will run B if B has previously been completed, but 
B has not previously been run. 
+Several of the notmuch commands accept
+search terms with a common syntax. See the B section below for
+more details on the supported syntax. 
+The B and B commands are
+used to query the email database. 
+
+=head2 search [options...] ... 
+
+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 include 
+
+=over
+
+=item B<--sort=>(B|B) 
+
+This option can be used
+to present results in either chronological order (B) or reverse
+chronological order (B). 
+Not