[Stefano Zacchiroli] Bug#628018: [PATCH] notmuch-mutt utility for notmuch/contrib/

[David Bremner <david@tethera.net>]

[-- Attachment #0: Type: message/rfc822, Size: 21666 bytes --]

[-- Attachment #1.1.1: Type: text/plain, Size: 1114 bytes --]

Here is an updated patch set that ships the notmuch-mutt utility and
updated the Debian packaging for it. It is now better integrated with
notmuch: it has been renamed to "notmuch-mutt" (to match the naming
convention of other notmuch interfaces) and stores all its data under
~/.cache/notmuch/mutt/ to avoid polluting user $HOME with other
directories. I've also fixed the Debian packaging to generate the
manpage during build.

The first patch in the set adds notmuch-mutt to contrib/, the second
updates debian/ to build a new "notmuch-mutt" binary package.

The full story is available at http://bugs.debian.org/628018

David: I'm still unable to get through the moderation queue of the
notmuch mailing list. Would you be so kind to forward this mail there,
for patch review?

TIA,
Cheers.
-- 
Stefano Zacchiroli     zack@{upsilon.cc,pps.jussieu.fr,debian.org} . o .
Maître de conférences   ......   http://upsilon.cc/zack   ......   . . o
Debian Project Leader    .......   @zack on identi.ca   .......    o o o
« the first rule of tautology club is the first rule of tautology club »

[-- Attachment #1.1.2: 0001-contrib-new-mutt-notmuch-utility-for-Mutt-integratio.patch --]
[-- Type: text/x-diff, Size: 11683 bytes --]

From cbb43be7d163e7662c0aa4fcb69f173074bb947d Mon Sep 17 00:00:00 2001
From: Stefano Zacchiroli <zack@upsilon.cc>
Date: Mon, 26 Mar 2012 10:45:58 +0200
Subject: [PATCH 1/2] contrib: new mutt-notmuch utility for Mutt integration

---
 contrib/notmuch-mutt/.gitignore      |    2 +
 contrib/notmuch-mutt/Makefile        |   12 ++
 contrib/notmuch-mutt/README          |   59 +++++++++
 contrib/notmuch-mutt/notmuch-mutt    |  234 ++++++++++++++++++++++++++++++++++
 contrib/notmuch-mutt/notmuch-mutt.rc |    9 ++
 5 files changed, 316 insertions(+), 0 deletions(-)
 create mode 100644 contrib/notmuch-mutt/.gitignore
 create mode 100644 contrib/notmuch-mutt/Makefile
 create mode 100644 contrib/notmuch-mutt/README
 create mode 100755 contrib/notmuch-mutt/notmuch-mutt
 create mode 100644 contrib/notmuch-mutt/notmuch-mutt.rc

diff --git a/contrib/notmuch-mutt/.gitignore b/contrib/notmuch-mutt/.gitignore
new file mode 100644
index 0000000..682a577
--- /dev/null
+++ b/contrib/notmuch-mutt/.gitignore
@@ -0,0 +1,2 @@
+notmuch-mutt.1
+README.html
diff --git a/contrib/notmuch-mutt/Makefile b/contrib/notmuch-mutt/Makefile
new file mode 100644
index 0000000..87f9031
--- /dev/null
+++ b/contrib/notmuch-mutt/Makefile
@@ -0,0 +1,12 @@
+NAME = notmuch-mutt
+
+all: $(NAME) $(NAME).1
+
+$(NAME).1: $(NAME)
+	pod2man $< > $@
+
+README.html: README
+	markdown $< > $@
+
+clean:
+	rm -f notmuch-mutt.1 README.html
diff --git a/contrib/notmuch-mutt/README b/contrib/notmuch-mutt/README
new file mode 100644
index 0000000..382ac91
--- /dev/null
+++ b/contrib/notmuch-mutt/README
@@ -0,0 +1,59 @@
+notmuch-mutt: Notmuch (of a) helper for Mutt
+============================================
+
+notmuch-mutt provide integration among the [Mutt] [1] mail user agent and the
+[Notmuch] [2] mail indexer.
+
+notmuch-mutt offer two main integration features. The first one is the ability
+of stating a **search query interactively** and then jump to a fresh Maildir
+containing its search results only. The second one is the ability to
+**reconstruct threads on the fly** starting from the currently highlighted
+mail, which comes handy when a thread has been split across different maildirs,
+archived, or the like.
+
+notmuch-mutt enables to trigger mail searches via a Mutt macro (usually F8) and
+reconstruct threads via another (usually F9). Check the manpage for the 2-liner
+configuration snippet for your Mutt configuration files (~/.muttrc,
+/etc/Muttrc, or a /etc/Muttrc.d snippet).
+
+A [blog style introduction] [3] to notmuch-mutt is available and includes some
+more rationale for its existence.
+
+Arguably, some of the logics of notmuch-mutt could disappear by adding support
+for a --output=symlinks flag to notmuch.
+
+
+[1]: http://www.mutt.org/
+[2]: http://notmuchmail.org/
+[3]: http://upsilon.cc/~zack/blog/posts/2011/01/how_to_use_Notmuch_with_Mutt/
+
+
+Requirements
+------------
+
+To *run* notmuch-mutt you will need Perl with the following libraries:
+
+- Mail::Box <http://search.cpan.org/~markov/Mail-Box/>
+  (Debian package: libmail-box-perl)
+- Mail::Internet <http://search.cpan.org/~markov/MailTools/>
+  (Debian package: libmailtools-perl)
+- String::ShellQuote <http://search.cpan.org/~rosch/String-ShellQuote/ShellQuote.pm>
+  (Debian package: libstring-shellquote-perl)
+- Term::ReadLine <http://search.cpan.org/~hayashi/Term-ReadLine-Gnu/>
+  (Debian package: libterm-readline-gnu-perl)
+
+To *build* notmuch-mutt documentation you will need:
+
+- pod2man (coming with Perl) to generate the manpage
+- markdown to generate README.html out of this file
+
+
+License
+-------
+
+notmuch-mutt is copyright (C) 2011-2012 Stefano Zacchiroli <zack@upsilon.cc>.
+
+notmuch-mutt is released under the terms of the GNU General Public License
+(GPL), version 3 or above. A copy of the license is available online at
+<http://www.gnu.org/licenses/>.
+
diff --git a/contrib/notmuch-mutt/notmuch-mutt b/contrib/notmuch-mutt/notmuch-mutt
new file mode 100755
index 0000000..29674ec
--- /dev/null
+++ b/contrib/notmuch-mutt/notmuch-mutt
@@ -0,0 +1,234 @@
+#!/usr/bin/perl -w
+#
+# notmuch-mutt - notmuch (of a) helper for Mutt
+#
+# Copyright: © 2011-2012 Stefano Zacchiroli <zack@upsilon.cc> 
+# License: GNU General Public License (GPL), version 3 or above
+#
+# See the bottom of this file for more documentation.
+# A manpage can be obtained by running "pod2man notmuch-mutt > notmuch-mutt.1"
+
+use strict;
+use warnings;
+
+use File::Path;
+use Getopt::Long qw(:config no_getopt_compat);
+use Mail::Internet;
+use Mail::Box::Maildir;
+use Pod::Usage;
+use String::ShellQuote;
+use Term::ReadLine;
+
+
+my $cache_dir = "$ENV{HOME}/.cache/notmuch/mutt";
+
+
+# create an empty maildir (if missing) or empty an existing maildir"
+sub empty_maildir($) {
+    my ($maildir) = (@_);
+    rmtree($maildir) if (-d $maildir);
+    my $folder = new Mail::Box::Maildir(folder => $maildir,
+					create => 1);
+    $folder->close();
+}
+
+# search($maildir, $query)
+# search mails according to $query with notmuch; store results in $maildir
+sub search($$) {
+    my ($maildir, $query) = @_;
+    $query = shell_quote($query);
+
+    empty_maildir($maildir);
+    system("notmuch search --output=files $query"
+	   . " | sed -e 's: :\\\\ :g'"
+	   . " | xargs --no-run-if-empty ln -s -t $maildir/cur/");
+}
+
+sub prompt($$) {
+    my ($text, $default) = @_;
+    my $query = "";
+    my $term = Term::ReadLine->new( "notmuch-mutt" );
+    my $histfile = "$cache_dir/history";
+
+    $term->ornaments( 0 );
+    $term->unbind_key( ord( "\t" ) );
+    $term->MinLine( 3 );
+    $histfile = $ENV{MUTT_NOTMUCH_HISTFILE} if $ENV{MUTT_NOTMUCH_HISTFILE};
+    $term->ReadHistory($histfile) if (-r $histfile);
+    while (1) {
+	chomp($query = $term->readline($text, $default));
+	if ($query eq "?") {
+	    system("man", "notmuch");
+	} else {
+	    $term->WriteHistory($histfile);
+	    return $query;
+	}
+    }
+}
+
+sub get_message_id() {
+    my $mail = Mail::Internet->new(\*STDIN);
+    $mail->head->get("message-id") =~ /^<(.*)>$/;	# get message-id
+    return $1;
+}
+
+sub search_action($$@) {
+    my ($interactive, $results_dir, @params) = @_;
+
+    if (! $interactive) {
+	search($results_dir, join(' ', @params));
+    } else {
+	my $query = prompt("search ('?' for man): ", join(' ', @params));
+	if ($query ne "") {
+	    search($results_dir,$query);
+	}
+    }
+}
+
+sub thread_action(@) {
+    my ($results_dir, @params) = @_;
+    my $mid = get_message_id();
+    my $tid = `notmuch search --output=threads id:$mid`;# get thread id
+    chomp($tid);
+
+    search($results_dir, $tid);
+}
+
+sub tag_action(@) {
+    my $mid = get_message_id();
+
+    system("notmuch tag "
+	   . shell_quote(join(' ', @_))
+	   . " id:$mid");
+}
+
+sub die_usage() {
+    my %podflags = ( "verbose" => 1,
+		    "exitval" => 2 );
+    pod2usage(%podflags);
+}
+
+sub main() {
+    mkpath($cache_dir) unless (-d $cache_dir);
+
+    my $results_dir = "$cache_dir/results";
+    my $interactive = 0;
+    my $help_needed = 0;
+
+    my $getopt = GetOptions(
+	"h|help" => \$help_needed,
+	"o|output-dir=s" => \$results_dir,
+	"p|prompt" => \$interactive);
+    if (! $getopt || $#ARGV < 0) { die_usage() };
+    my ($action, @params) = ($ARGV[0], @ARGV[1..$#ARGV]);
+
+    foreach my $param (@params) {
+      $param =~ s/folder:=/folder:/g;
+    }
+
+    if ($help_needed) {
+	die_usage();
+    } elsif ($action eq "search" && $#ARGV == 0 && ! $interactive) {
+	print STDERR "Error: no search term provided\n\n";
+	die_usage();
+    } elsif ($action eq "search") {
+	search_action($interactive, $results_dir, @params);
+    } elsif ($action eq "thread") {
+	thread_action($results_dir, @params);
+    } elsif ($action eq "tag") {
+	tag_action(@params);
+    } else {
+	die_usage();
+    }
+}
+
+main();
+
+__END__
+
+=head1 NAME
+
+notmuch-mutt - notmuch (of a) helper for Mutt
+
+=head1 SYNOPSIS
+
+=over
+
+=item B<notmuch-mutt> [I<OPTION>]... search [I<SEARCH-TERM>]...
+
+=item B<notmuch-mutt> [I<OPTION>]... thread < I<MAIL>
+
+=item B<notmuch-mutt> [I<OPTION>]... tag [I<TAGS>]... < I<MAIL>
+
+=back
+
+=head1 DESCRIPTION
+
+notmuch-mutt is a frontend to the notmuch mail indexer capable of populating
+maildir with search results.
+
+=head1 OPTIONS
+
+=over 4
+
+=item -o DIR
+
+=item --output-dir DIR
+
+Store search results as (symlink) messages under maildir DIR. Beware: DIR will
+be overwritten. (Default: F<~/.cache/notmuch/mutt/results/>)
+
+=item -p
+
+=item --prompt
+
+Instead of using command line search terms, prompt the user for them (only for
+"search").
+
+=item -h
+
+=item --help
+
+Show usage information and exit.
+
+=back
+
+=head1 INTEGRATION WITH MUTT
+
+notmuch-mutt can be used to integrate notmuch with the Mutt mail user agent
+(unsurprisingly, given the name). To that end, you should define macros like
+the following in your Mutt configuration (usually one of: F<~/.muttrc>,
+F</etc/Muttrc>, or a configuration snippet under F</etc/Muttrc.d/>):
+
+    macro index <F8> \
+          "<enter-command>unset wait_key<enter><shell-escape>notmuch-mutt --prompt search<enter><change-folder-readonly>~/.cache/notmuch/mutt/results<enter>" \
+          "notmuch: search mail"
+    macro index <F9> \
+          "<enter-command>unset wait_key<enter><pipe-message>notmuch-mutt thread<enter><change-folder-readonly>~/.cache/notmuch/mutt/results<enter><enter-command>set wait_key<enter>" \
+          "notmuch: reconstruct thread"
+    macro index <F6> \
+          "<enter-command>unset wait_key<enter><pipe-message>notmuch-mutt tag -inbox<enter>" \
+          "notmuch: remove message from inbox"
+
+The first macro (activated by <F8>) prompts the user for notmuch search terms
+and then jump to a temporary maildir showing search results. The second macro
+(activated by <F9>) reconstructs the thread corresponding to the current mail
+and show it as search results. The third macro (activated by <F6>) removes the
+tag C<inbox> from the current message; by changing C<-inbox> this macro may be
+customised to add or remove tags appropriate to the users notmuch work-flow.
+
+To keep notmuch index current you should then periodically run C<notmuch
+new>. Depending on your local mail setup, you might want to do that via cron,
+as a hook triggered by mail retrieval, etc.
+
+=head1 SEE ALSO
+
+mutt(1), notmuch(1)
+
+=head1 AUTHOR
+
+Copyright: (C) 2011-2012 Stefano Zacchiroli <zack@upsilon.cc>
+
+License: GNU General Public License (GPL), version 3 or higher
+
+=cut
diff --git a/contrib/notmuch-mutt/notmuch-mutt.rc b/contrib/notmuch-mutt/notmuch-mutt.rc
new file mode 100644
index 0000000..269f03f
--- /dev/null
+++ b/contrib/notmuch-mutt/notmuch-mutt.rc
@@ -0,0 +1,9 @@
+macro index <F8> \
+      "<enter-command>unset wait_key<enter><shell-escape>notmuch-mutt --prompt search<enter><change-folder-readonly>~/.cache/notmuch/mutt/results<enter>" \
+      "notmuch: search mail"
+macro index <F9> \
+      "<enter-command>unset wait_key<enter><pipe-message>notmuch-mutt thread<enter><change-folder-readonly>~/.cache/notmuch/mutt/results<enter><enter-command>set wait_key<enter>" \
+      "notmuch: reconstruct thread"
+macro index <F6> \
+      "<enter-command>unset wait_key<enter><pipe-message>notmuch-mutt tag -inbox<enter>" \
+      "notmuch: remove message from inbox"
-- 
1.7.9.1


[-- Attachment #1.1.3: 0002-debian-packaging-new-binary-package-notmuch-mutt.patch --]
[-- Type: text/x-diff, Size: 3313 bytes --]

From c342af0fa2b9d936753f57cd8fa232ca246079d1 Mon Sep 17 00:00:00 2001
From: Stefano Zacchiroli <zack@upsilon.cc>
Date: Mon, 26 Mar 2012 10:51:44 +0200
Subject: [PATCH 2/2] debian packaging: new binary package notmuch-mutt

---
 debian/changelog             |    6 ++++++
 debian/control               |   16 ++++++++++++++++
 debian/notmuch-mutt.docs     |    1 +
 debian/notmuch-mutt.install  |    2 ++
 debian/notmuch-mutt.manpages |    1 +
 debian/rules                 |    2 ++
 6 files changed, 28 insertions(+), 0 deletions(-)
 create mode 100644 debian/notmuch-mutt.docs
 create mode 100644 debian/notmuch-mutt.install
 create mode 100644 debian/notmuch-mutt.manpages

diff --git a/debian/changelog b/debian/changelog
index d0eec37..bd70d08 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,9 @@
+notmuch (0.12-2) UNRELEASED; urgency=low
+
+  * new binary package "notmuch-mutt" for Mutt integration
+
+ -- Stefano Zacchiroli <zack@debian.org>  Mon, 26 Mar 2012 10:47:29 +0200
+
 notmuch (0.12-1) unstable; urgency=low
 
   * New upstream release
diff --git a/debian/control b/debian/control
index ed27c58..ada9d3d 100644
--- a/debian/control
+++ b/debian/control
@@ -105,3 +105,19 @@ Description: thread-based email index, search and tagging (vim interface)
  This package provides a vim based mail user agent based on
  notmuch.
 
+Package: notmuch-mutt
+Architecture: all
+Depends: notmuch, libmail-box-perl, libmailtools-perl,
+ libstring-shellquote-perl, libterm-readline-gnu-perl,
+ ${misc:Depends}
+Recommends: mutt
+Enhances: notmuch, mutt
+Description: thread-based email index, search and tagging (Mutt interface)
+ notmuch-mutt provides integration among the Mutt mail user agent and
+ the Notmuch mail indexer.
+ .
+ notmuch-mutt offer two main integration features. The first one is
+ the ability of stating a search query interactively and then jump to
+ a fresh Maildir containing its search results only. The second one is
+ the ability to reconstruct threads on the fly starting from the
+ current highlighted mail.
diff --git a/debian/notmuch-mutt.docs b/debian/notmuch-mutt.docs
new file mode 100644
index 0000000..f3d25cd
--- /dev/null
+++ b/debian/notmuch-mutt.docs
@@ -0,0 +1 @@
+contrib/notmuch-mutt/README
diff --git a/debian/notmuch-mutt.install b/debian/notmuch-mutt.install
new file mode 100644
index 0000000..9141c26
--- /dev/null
+++ b/debian/notmuch-mutt.install
@@ -0,0 +1,2 @@
+contrib/notmuch-mutt/notmuch-mutt	usr/bin
+contrib/notmuch-mutt/notmuch-mutt.rc	etc/Muttrc.d
diff --git a/debian/notmuch-mutt.manpages b/debian/notmuch-mutt.manpages
new file mode 100644
index 0000000..3f6b8ab
--- /dev/null
+++ b/debian/notmuch-mutt.manpages
@@ -0,0 +1 @@
+contrib/notmuch-mutt/notmuch-mutt.1
diff --git a/debian/rules b/debian/rules
index 956f3f2..603b3ab 100755
--- a/debian/rules
+++ b/debian/rules
@@ -9,10 +9,12 @@ override_dh_auto_configure:
 override_dh_auto_build:
 	dh_auto_build
 	dh_auto_build --sourcedirectory bindings/python
+	$(MAKE) -C contrib/notmuch-mutt
 
 override_dh_auto_clean:
 	dh_auto_clean
 	dh_auto_clean --sourcedirectory bindings/python
+	$(MAKE) -C contrib/notmuch-mutt clean
 
 override_dh_auto_install:
 	dh_auto_install
-- 
1.7.9.1


[-- Attachment #1.2: Digital signature --]
[-- Type: application/pgp-signature, Size: 828 bytes --]