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

[Carl Worth]

On Sun, 13 Jun 2010 12:01:30 -0300, david at tethera.net wrote:
> We can also generate man pages and inline help from this file. I
> didn't get that far yet, waiting for more encouraging noises :).

Hi David,

Having added some documentation recently, I do continue to be annoyed by
the need to add it all in two places.

So I am still interested in taking advantage of your work here.

I know that you've already refreshed it more than once, so I won't ask
you to do that again.

But if you could implement the ability to actually generate the inline
help and man page from this file (even just the version here would be
fine), then I'd be quite happy to look at that.

And then, if I'm happy with the result, I'd be willing to do the job of
refreshing the documentation to the latest.

Thanks again,

-Carl

PS. Or if you just want to drop this, that's fine too. I won't go
insisting that you do additional work if you don't feel like it. ;-)
-- next part --
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: 

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

You can take a look at the HTML output at

http://pivot.cs.unb.ca/scratch/notmuch.html

We can also generate man pages and inline help from this file. I
didn't get that far yet, waiting for more encouraging noises :).

 notmuch.pod |  361 +++
 1 files changed, 361 insertions(+), 0 deletions(-)
 create mode 100644 notmuch.pod

diff --git a/notmuch.pod b/notmuch.pod
new file mode 100644
index 000..719dead
--- /dev/null
+++ b/notmuch.pod
@@ -0,0 +1,361 @@
+=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
+
+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.
+
+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...] ...
+
+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-content MIME parts decoded.
+Various components in the output, (B, B, B,
+B, and MIME B), will be delimited by easily-parsed
+markers. Each 

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

[david]

From: David Bremner brem...@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.
---

You can take a look at the HTML output at

http://pivot.cs.unb.ca/scratch/notmuch.html

We can also generate man pages and inline help from this file. I
didn't get that far yet, waiting for more encouraging noises :).

 notmuch.pod |  361 +++
 1 files changed, 361 insertions(+), 0 deletions(-)
 create mode 100644 notmuch.pod

diff --git a/notmuch.pod b/notmuch.pod
new file mode 100644
index 000..719dead
--- /dev/null
+++ b/notmuch.pod
@@ -0,0 +1,361 @@
+=head1 Name
+
+notmuch - thread-based email index, search, and tagging
+
+=head1 Synopsis
+
+=over
+
+=item Bnotmuch Icommand [Iargs ...]
+
+=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
+Bnotmuch command with no arguments, which will interactively guide
+you through the process of indexing your mail.
+
+=head2 Using notmuch
+
+The Bsearch and Bshow commands are used to query the email
+database.  The Btag command is the only command available for
+manipulating database contents.  Several of the notmuch commands
+accept search terms with a common syntax. See the BSEARCH SYNTAX
+section below for more details on the supported syntax.
+
+=head2 Note
+
+While the command-line program Bnotmuch 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 Lhttp://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 Bnotmuch 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 Bnotmuch setup
+
+Invoking Bnotmuch with no command argument will run Bsetup if the
+setup command has not previously been completed.
+
+=head2 new
+
+Find and import any new messages to the database.  The Bnew 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 Binbox and Bunread tags.
+You should run Bnotmuch new once after first running Bnotmuch
+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 Bnotmuch 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 Bnotmuch with no command argument will run Bnew if
+Bnotmuch setup has previously been completed, but Bnotmuch new has
+not previously been run.
+
+=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 Bshow 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 

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

[David Bremner]

On Mon, 26 Apr 2010 16:33:27 -0700, Carl Worth  wrote:
> 
> I tried to look at it a couple of times, but it was already stale then
> so I didn't look hard enough.
> 
> The couple of questions I have are:
> 
>   * How close does the generated output match what we have today?

Pretty close, I think.  Essentially I just reformatted one or two places
to make the online help easier to pull out of the man pages.

>   * What additional tools does this require for someone to build the
> tree from the git repository?

A recentish version of perl. 5.8.8 (2006) seems to have the utilities
we'd need.  I guess if people have git, they have perl. I guess in
principle we could ship the pre-processed docs in a distribution
tarball.

> > Should I rebase/rebuild this against the current docs, or not bother?
> 
> I'd be interested in taking another look, if you're willing to take
> another whack at it. I think that our command-line interface is changing
> a lot more slowly such that this won't go immediately stale this time.

Sure, I can have another go at it.  

d

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

[Carl Worth]

-- 
carl.d.worth at intel.com
On Sat, 24 Apr 2010 11:04:49 -0300, David Bremner  wrote:
> As I'm faced with writing docs for output selection, I'd like to revisit
> this idea. I didn't get any feedback, positive or negative about the
> idea of keeping the docs in pod.  I don't care much about the format,
> but I think it would be nice to avoid maintaining two copies of the
> documentation.

Sorry about the lack of feedback from me on this.

I tried to look at it a couple of times, but it was already stale then
so I didn't look hard enough.

The couple of questions I have are:

  * How close does the generated output match what we have today?

  * What additional tools does this require for someone to build the
tree from the git repository?

> Should I rebase/rebuild this against the current docs, or not bother?

I'd be interested in taking another look, if you're willing to take
another whack at it. I think that our command-line interface is changing
a lot more slowly such that this won't go immediately stale this time.

Though you could perhaps start by answering the above questions which
might be less work. :-)

-Carl
-- next part --
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
URL: 

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

[David Edmondson]

On Sat, 24 Apr 2010 11:04:49 -0300, David Bremner  wrote:
> As I'm faced with writing docs for output selection, I'd like to revisit
> this idea. I didn't get any feedback, positive or negative about the
> idea of keeping the docs in pod.  I don't care much about the format,
> but I think it would be nice to avoid maintaining two copies of the
> documentation.
> 
> Should I rebase/rebuild this against the current docs, or not bother?

I like the idea, but I have no experience with pod.

dme.
-- 
David Edmondson, http://dme.org

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

[David Edmondson]

On Sat, 24 Apr 2010 11:04:49 -0300, David Bremner da...@tethera.net wrote:
 As I'm faced with writing docs for output selection, I'd like to revisit
 this idea. I didn't get any feedback, positive or negative about the
 idea of keeping the docs in pod.  I don't care much about the format,
 but I think it would be nice to avoid maintaining two copies of the
 documentation.
 
 Should I rebase/rebuild this against the current docs, or not bother?

I like the idea, but I have no experience with pod.

dme.
-- 
David Edmondson, http://dme.org
___
notmuch mailing list
notmuch@notmuchmail.org
http://notmuchmail.org/mailman/listinfo/notmuch

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

[David Bremner]

On Mon, 26 Apr 2010 16:33:27 -0700, Carl Worth cwo...@cworth.org wrote:
 
 I tried to look at it a couple of times, but it was already stale then
 so I didn't look hard enough.
 
 The couple of questions I have are:
 
   * How close does the generated output match what we have today?

Pretty close, I think.  Essentially I just reformatted one or two places
to make the online help easier to pull out of the man pages.

   * What additional tools does this require for someone to build the
 tree from the git repository?

A recentish version of perl. 5.8.8 (2006) seems to have the utilities
we'd need.  I guess if people have git, they have perl. I guess in
principle we could ship the pre-processed docs in a distribution
tarball.

  Should I rebase/rebuild this against the current docs, or not bother?
 
 I'd be interested in taking another look, if you're willing to take
 another whack at it. I think that our command-line interface is changing
 a lot more slowly such that this won't go immediately stale this time.

Sure, I can have another go at it.  

d

___
notmuch mailing list
notmuch@notmuchmail.org
http://notmuchmail.org/mailman/listinfo/notmuch

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

[David Bremner]

On Thu, 31 Dec 2009 13:39:29 -0400, david at tethera.net wrote:
> 
> 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
> 

As I'm faced with writing docs for output selection, I'd like to revisit
this idea. I didn't get any feedback, positive or negative about the
idea of keeping the docs in pod.  I don't care much about the format,
but I think it would be nice to avoid maintaining two copies of the
documentation.

Should I rebase/rebuild this against the current docs, or not bother?

d

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

[David Bremner]

On Thu, 31 Dec 2009 13:39:29 -0400, da...@tethera.net wrote:
 
 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
 

As I'm faced with writing docs for output selection, I'd like to revisit
this idea. I didn't get any feedback, positive or negative about the
idea of keeping the docs in pod.  I don't care much about the format,
but I think it would be nice to avoid maintaining two copies of the
documentation.

Should I rebase/rebuild this against the current docs, or not bother?

d
___
notmuch mailing list
notmuch@notmuchmail.org
http://notmuchmail.org/mailman/listinfo/notmuch

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

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