[notmuch] [PATCH] notmuch.pod: pod version of documentation, converted by rman, massaged by hand.
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.
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
