RFC: tag macros

RFC: tag macros

[David Bremner]

Hi All;

Here is a very early stage proposal to provide tagging macros for
notmuch show mode. 

The idea is that user defines a mapping from single key to a sequence of
tagging operations.  It might be nice if there as some kind of pop-up
menu, or at least a prompt, but I didn't do that so far.

The advantage of this rather than just writing lots of little lambdas is
that it combines adding and deleting, and it could be done via
customize.

As provided, the code should just paste into .emacs, and with a little
editing into notmuch-show.el.

% ---- cut here ----

(eval-after-load 'notmuch-show
  '(define-key notmuch-show-mode-map "t" 'notmuch-show-apply-tag-macro))

(setq notmuch-show-tag-macro-alist
  (list '("p" "+notmuch::patch" "+notmuch::needs-review")
	'("r" "+notmuch::review")
	'("o" "+notmuch::patch" "+notmuch::obsolete" "-notmuch::needs-review")
	'("m" "+notmuch::patch" "+notmuch::moreinfo" "-notmuch::needs-review")))

(defun notmuch-show-apply-tag-macro (key)
  (interactive "k")
  (let ((macro (assoc key notmuch-show-tag-macro-alist)))
    (apply 'notmuch-show-add-or-del-tags (cdr macro))))

(defun notmuch-show-add-or-del-tags (&rest add-or-dels)
  "Add or delete tags to/from the current message."
  (let* ((current-tags (notmuch-show-get-tags))
	 (new-tags (notmuch-show-add-or-del-tags-worker current-tags add-or-dels)))
    (unless (equal current-tags new-tags)
      (apply 'notmuch-tag (notmuch-show-get-message-id) add-or-dels)
      (notmuch-show-set-tags new-tags))))


(defun notmuch-show-add-or-del-tags-worker (current-tags add-or-dels)
  "Remove any tags in `add-or-del' prefixed with `-' from `current-tags', add any prefixed with `+'
and return the result."
  (let (adds deletes)
    (mapc (lambda (tag-str)
	    (if (string-match "^\\([+\-]\\)\\(.*\\)" tag-str)
		(let ((op (match-string 1 tag-str))
		      (tag (match-string 2 tag-str)))
		  (if (equal op "+")
		      (setq adds (cons tag adds))
		    (setq deletes (cons tag deletes))))
	      (error "%s: does not start with + or -" tag-str)))
	  add-or-dels)
    (notmuch-show-del-tags-worker 
     (notmuch-show-add-tags-worker current-tags adds)
     deletes)))

Re: RFC: tag macros

[David Edmondson]

[-- Attachment #1: Type: text/plain, Size: 224 bytes --]

On Wed, 18 Jan 2012 10:45:06 -0400, David Bremner <david@tethera.net> wrote:
> Here is a very early stage proposal to provide tagging macros for
> notmuch show mode. 

Nice idea. Please make it work on regions as well.

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: RFC: tag macros

[Austin Clements]

Quoth David Bremner on Jan 18 at 10:45 am:
> 
> Hi All;
> 
> Here is a very early stage proposal to provide tagging macros for
> notmuch show mode. 
> 
> The idea is that user defines a mapping from single key to a sequence of
> tagging operations.  It might be nice if there as some kind of pop-up
> menu, or at least a prompt, but I didn't do that so far.
> 
> The advantage of this rather than just writing lots of little lambdas is
> that it combines adding and deleting, and it could be done via
> customize.
> 
> As provided, the code should just paste into .emacs, and with a little
> editing into notmuch-show.el.

What about simply providing an API that takes a bunch of tag
operations and applies them to the current thread/message/region?
Maybe even the notmuch-show-add-or-del-tags that you have below
(probably spruced up a bit).  I feel like the type of people who are
likely to use tag macros would also have the know-how to add a simple
key binding of their own, assuming it *were* simple.  Such an API
would probably clean up some of the tagging code in notmuch-show, too.

Re: RFC: tag macros

[Jameson Graef Rollins]

[-- Attachment #1: Type: text/plain, Size: 1206 bytes --]

On Wed, 18 Jan 2012 10:45:06 -0400, David Bremner <david@tethera.net> wrote:
> The advantage of this rather than just writing lots of little lambdas is
> that it combines adding and deleting, and it could be done via
> customize.

Is all of this really easier than just adding the following to your
.emacs?:

(define-key notmuch-search-mode-map "o"
  (lambda ()
    (interactive)
    (notmuch-show-add-tag "notmuch::patch")
    (notmuch-show-add-tag "notmuch::obsolete")
    (notmuch-show-remove-tag "notmuch::needs-review")))

That seems really simple to me, and doesn't require us to support a
bunch of code to do complicated customization stuff.

Rather than have protracted conversations about key bindings or continue
to make more complicated configuration setups, I would like to push the
idea that we support a bunch of nice simple functions to do common,
useful operations (like tagging and navigation), and let users build
macros as they see fit.  I think this is a lot more flexible, and takes
a lot of the maintenance burden off of us.

I've been wanting to put together a wiki page that lists all the useful
functions and has examples of how to put them together into useful
functions.

jamie.

[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]

Re: RFC: tag macros

[David Bremner]

On Wed, 18 Jan 2012 13:33:04 -0500, Austin Clements <amdragon@MIT.EDU> wrote:
> Quoth David Bremner on Jan 18 at 10:45 am:

> What about simply providing an API that takes a bunch of tag
> operations and applies them to the current thread/message/region?

My main motivation here is (as you can probably see from the example)
dealing with patches, and in that setting, tagging the whole thread is
is almost never what you want.

That aside, thread tagging is already there in search view, and I guess
could be done by selecting the whole thread and tagging that region.

I haven't really looked at how to apply tags to regions in
notmuch-show-mode. Is there code around that does that? Or more
generally iterate over messages in a region?

d

Re: RFC: tag macros

[Austin Clements]

Quoth David Bremner on Jan 18 at  3:03 pm:
> On Wed, 18 Jan 2012 13:33:04 -0500, Austin Clements <amdragon@MIT.EDU> wrote:
> > Quoth David Bremner on Jan 18 at 10:45 am:
> 
> > What about simply providing an API that takes a bunch of tag
> > operations and applies them to the current thread/message/region?
> 
> My main motivation here is (as you can probably see from the example)
> dealing with patches, and in that setting, tagging the whole thread is
> is almost never what you want.
> 
> That aside, thread tagging is already there in search view, and I guess
> could be done by selecting the whole thread and tagging that region.
> 
> I haven't really looked at how to apply tags to regions in
> notmuch-show-mode. Is there code around that does that? Or more
> generally iterate over messages in a region?

Sorry, that was all a bit of a red herring in my email.  The
high-level point I was trying to make is really what Jamie said.

Re: RFC: tag macros

[Jameson Graef Rollins]

[-- Attachment #1: Type: text/plain, Size: 977 bytes --]

On Wed, 18 Jan 2012 15:03:52 -0400, David Bremner <david@tethera.net> wrote:
> My main motivation here is (as you can probably see from the example)
> dealing with patches, and in that setting, tagging the whole thread is
> is almost never what you want.

The example I sent was about tagging individual message, not threads.

> That aside, thread tagging is already there in search view, and I guess
> could be done by selecting the whole thread and tagging that region.

Thread tagging would be supported in show mode with the recent
notmuch-show-{add,remove}-tag-thread patches I sent:

id:"1326823531-14549-1-git-send-email-jrollins@finestructure.net"

> I haven't really looked at how to apply tags to regions in
> notmuch-show-mode. Is there code around that does that? Or more
> generally iterate over messages in a region?

I don't think the show mode tagging functions support regions at the
moment, but I think extending them to do that would be a good idea.

jamie.

[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]

Re: RFC: tag macros

[David Bremner]

On Wed, 18 Jan 2012 10:50:50 -0800, Jameson Graef Rollins <jrollins@finestructure.net> wrote:
> 
> I've been wanting to put together a wiki page that lists all the useful
> functions and has examples of how to put them together into useful
> functions.
> 

If we're going to go the way of providing a toolkit/api for uses to make
their own bindings, then I think that we should make the effort to
provide a proper info document with the distribution, rather than
relying on the wiki.  Of course, that means more work, and yet another
markup language, I guess.

d

Re: RFC: tag macros

[Jameson Graef Rollins]

[-- Attachment #1: Type: text/plain, Size: 820 bytes --]

On Wed, 18 Jan 2012 20:04:44 -0400, David Bremner <david@tethera.net> wrote:
> If we're going to go the way of providing a toolkit/api for uses to make
> their own bindings, then I think that we should make the effort to
> provide a proper info document with the distribution, rather than
> relying on the wiki.  Of course, that means more work, and yet another
> markup language, I guess.

Can't we just use the emacs build-in documentation?

My idea of documenting on the wiki was just as a starting point.  It
could list some of the available functions, and how to use them, and
then have good references to emacs documentation and how to find it.

I'm guessing we also have a lot of functions that are marked interactive
that don't necessarily need to be.  Weeding those out might make
documentation easier.

jamie.

[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]

Re: RFC: tag macros

[David Bremner]

On Wed, 18 Jan 2012 18:15:37 -0800, Jameson Graef Rollins <jrollins@finestructure.net> wrote:
> 
> Can't we just use the emacs build-in documentation?
> 

If you mean docstrings, that is only per function/variable.  Which is
better than nothing, but not very good for getting an overview of what
is going on.  Otherwise, info _is_ emacs' built-in documentation.

d

Re: RFC: tag macros

[David Bremner]

On Wed, 18 Jan 2012 10:50:50 -0800, Jameson Graef Rollins <jrollins@finestructure.net> wrote:

> Is all of this really easier than just adding the following to your
> .emacs?:
> 
> (define-key notmuch-search-mode-map "o"
>   (lambda ()
>     (interactive)
>     (notmuch-show-add-tag "notmuch::patch")
>     (notmuch-show-add-tag "notmuch::obsolete")
>     (notmuch-show-remove-tag "notmuch::needs-review")))
> 

I started out along this route.  I think there are a few advantages to
the approach I posted, but only if many people are making similar
snippets for more than one key.

- it doesn't have the 3 lines of boilerplate per keybinding
- it doesn't require the user to program in lisp; I suspect that
  explaining to new users how to customize their lisp snippets is some
  support burden as well.
- it provides the equivalent of a submap, which is another few lines of
  boilerplate. The only actual keybinding is "t" as a prefix. 

In my case, assuming the API was improved a bit as Austin suggested,
this would be a savings of 15-20 lines of boilerplate per user. 

Anyway, we can start by improving and documenting the API, and see how
that goes. The actually "parse lists and turn them into keybindings" part
is only the 4 line function notmuch-show-apply-tag-macro.

> That seems really simple to me, and doesn't require us to support a
> bunch of code to do complicated customization stuff.

I'm admittedly ignorant about emacs customization stuff, this requires a
single list of lists. Personally I use "setq" in .emacs for most
customization; it plays much better with version control.