[PATCH 0/2]: emacs: Improve notmuch-help

[PATCH 0/2]: emacs: Improve notmuch-help

[Nelson Elhage]

This patch set makes notmuch-help integrate with the built-in emacs
help system, resulting in behaviors more familiar and more natural to
most emacs users.

If other people preferred the old behavior of *notmuch-help* buffers
that kept spawning new buffers every time you hit '?', they should
speak up, but as long long-time emacs user, I find this behavior much
more preferable.

[PATCH 1/2] emacs: notmuch-help: Integrate into the emacs help system.

[Nelson Elhage]

Use a *help* buffer like other help commands, and make the [back] and
[forward] links work.
---
 emacs/notmuch.el |   14 ++++++--------
 1 files changed, 6 insertions(+), 8 deletions(-)

diff --git a/emacs/notmuch.el b/emacs/notmuch.el
index 57e1140..6bf8251 100644
--- a/emacs/notmuch.el
+++ b/emacs/notmuch.el
@@ -174,16 +174,14 @@ For a mouse binding, return nil."
       (setq beg (match-end 0)))
     doc))
 
-(defun notmuch-help ()
+(defun notmuch-help (&optional mode)
   "Display help for the current notmuch mode."
   (interactive)
-  (let* ((mode major-mode)
-	 (doc (substitute-command-keys (notmuch-substitute-command-keys (documentation mode t)))))
-    (with-current-buffer (generate-new-buffer "*notmuch-help*")
-      (insert doc)
-      (goto-char (point-min))
-      (set-buffer-modified-p nil)
-      (view-buffer (current-buffer) 'kill-buffer-if-not-modified))))
+  (let ((mode (or mode major-mode)))
+    (help-setup-xref `(notmuch-help ,mode) (interactive-p))
+    (with-help-window (help-buffer)
+      (princ (substitute-command-keys
+              (notmuch-substitute-command-keys (documentation mode t)))))))
 
 (defcustom notmuch-search-hook '(hl-line-mode)
   "List of functions to call when notmuch displays the search results."
-- 
1.6.6.30.g1e6fd

[PATCH 2/2] emacs: notmuch-search-mode: wrap the documentation string

[Nelson Elhage]

This makes for easier reading in the *help* window.
---
 emacs/notmuch.el |   21 ++++++++++++---------
 1 files changed, 12 insertions(+), 9 deletions(-)

diff --git a/emacs/notmuch.el b/emacs/notmuch.el
index 6bf8251..1149d1b 100644
--- a/emacs/notmuch.el
+++ b/emacs/notmuch.el
@@ -306,16 +306,19 @@ number of matched messages and total messages in the thread,
 participants in the thread, a representative subject line, and
 any tags).
 
-Pressing \\[notmuch-search-show-thread] on any line displays that thread. The '\\[notmuch-search-add-tag]' and '\\[notmuch-search-remove-tag]'
-keys can be used to add or remove tags from a thread. The '\\[notmuch-search-archive-thread]' key
+Pressing \\[notmuch-search-show-thread] on any line displays that
+thread. The '\\[notmuch-search-add-tag]' and
+'\\[notmuch-search-remove-tag]' keys can be used to add or remove
+tags from a thread. The '\\[notmuch-search-archive-thread]' key
 is a convenience for archiving a thread (removing the \"inbox\"
-tag). The '\\[notmuch-search-operate-all]' key can be used to add or remove a tag from all
-threads in the current buffer.
-
-Other useful commands are '\\[notmuch-search-filter]' for filtering the current search
-based on an additional query string, '\\[notmuch-search-filter-by-tag]' for filtering to include
-only messages with a given tag, and '\\[notmuch-search]' to execute a new, global
-search.
+tag). The '\\[notmuch-search-operate-all]' key can be used to add
+or remove a tag from all threads in the current buffer.
+
+Other useful commands are '\\[notmuch-search-filter]' for
+filtering the current search based on an additional query string,
+'\\[notmuch-search-filter-by-tag]' for filtering to include only
+messages with a given tag, and '\\[notmuch-search]' to execute a
+new, global search.
 
 Complete list of currently available key bindings:
 
-- 
1.6.6.30.g1e6fd

Re: [PATCH 0/2]: emacs: Improve notmuch-help

[Nelson Elhage]

Oops; I realized I haven't been signing off on last few patches I've
sent.

Signed-off-by: Nelson Elhage <nelhage@mit.edu>

for

id:1273869727-32740-2-git-send-email-nelhage@mit.edu
id:1273869727-32740-3-git-send-email-nelhage@mit.edu
id:1273857338-20127-1-git-send-email-nelhage@mit.edu
id:1273805175-6660-1-git-send-email-nelhage@ksplice.com

(Although the last one is probably superceded by the patch in
id:1272882573-9864-1-git-send-email-Sebastian@SSpaeth.de)

I can resend the entire patches with the signoffs if you prefer.

- Nelson

On Fri, 14 May 2010 16:42:05 -0400, Nelson Elhage <nelhage@MIT.EDU> wrote:
> This patch set makes notmuch-help integrate with the built-in emacs
> help system, resulting in behaviors more familiar and more natural to
> most emacs users.
> 
> If other people preferred the old behavior of *notmuch-help* buffers
> that kept spawning new buffers every time you hit '?', they should
> speak up, but as long long-time emacs user, I find this behavior much
> more preferable.
> 
> _______________________________________________
> notmuch mailing list
> notmuch@notmuchmail.org
> http://notmuchmail.org/mailman/listinfo/notmuch
> 

Re: [PATCH 1/2] emacs: notmuch-help: Integrate into the emacs help system.

[Sebastian Spaeth]

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

On 2010-05-14, Nelson Elhage wrote:
> Use a *help* buffer like other help commands, and make the [back] and
> [forward] links work.

I just tried this and one thing I did not like is that it opens a new
split help window but does not focus it immediately. I need to scroll
down the list of keybindings to see all but that requires manual buffer
switching. Can we focus it by default or is that un-emacsy?

Also, when closing with "q" the buffer split remains and I am left with
an empty split buffer, which is not what I want. I usually press "?" as
a key binding reference and want to get back to the state I was working
when I close the help window.

Also, -and that might be related to my additional notmuch-hello mode
patch that I am running- I get a "wrong type argument: listp, keymap"
when I press "?" in notmuch-hello although it works in notmuch-search
and notmuch-show. So that point might be moot.

I am sure there is a variable that customizes the help-buffer behavior,
isn't there? :-)

Sebastian

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

Re: [PATCH 1/2] emacs: notmuch-help: Integrate into the emacs help system.

[Sebastian Spaeth]

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

On 2010-05-14, Sebastian Spaeth wrote:
> I just tried this and one thing I did not like...

> I am sure there is a variable that customizes the help-buffer behavior,
> isn't there? :-)

DOH, I should have known :-). Emacs 23.1 has: "help-window-select" which
when set to 't behaves as I want it. It creates a split help window and
selects it. When pressing 'q' it deletes the frame.

This should go into the wiki or some other documentation. Or we should
set it locally for notmuch-help.

For notmuch-help I actually don't need a split window (I want
temporarily see as much info as possible and close the buffer quickly),
does the help-window thing also allow for that?

Thanks in any case.
Sebastian

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

Re: [PATCH 1/2] emacs: notmuch-help: Integrate into the emacs help system.

[Nelson Elhage]

On Fri, 14 May 2010 15:47:24 -0700, "Sebastian Spaeth" <Sebastian@sspaeth.de> wrote:
> On 2010-05-14, Sebastian Spaeth wrote:
> > I just tried this and one thing I did not like...
> 
> > I am sure there is a variable that customizes the help-buffer behavior,
> > isn't there? :-)
> 
> DOH, I should have known :-). Emacs 23.1 has: "help-window-select" which
> when set to 't behaves as I want it. It creates a split help window and
> selects it. When pressing 'q' it deletes the frame.
> 
> This should go into the wiki or some other documentation. Or we should
> set it locally for notmuch-help.

It's worth documenting. I'd prefer not to override it in notmuch-help,
because it's important to me that it behave like other help functions in
emacs. users could defadvice it or something if they really want.

> 
> For notmuch-help I actually don't need a split window (I want
> temporarily see as much info as possible and close the buffer quickly),
> does the help-window thing also allow for that?

I'm not sure. My emacs frame is always split, so it just opens in the
other window for me, which is what I want. I'm sure some quick source-
or documentation- diving would answer whether with-help-window can be
made to re-use the current window, but I haven't done that.

Thanks for giving it a try,

- Nelson

> 
> Thanks in any case.
> Sebastian

Re: [PATCH 1/2] emacs: notmuch-help: Integrate into the emacs help system.

[Carl Worth]

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

On Sat, 15 May 2010 17:07:42 -0400, Nelson Elhage <nelhage@MIT.EDU> wrote:
> On Fri, 14 May 2010 15:47:24 -0700, "Sebastian Spaeth" <Sebastian@sspaeth.de> wrote:
> > On 2010-05-14, Sebastian Spaeth wrote:
> > > I just tried this and one thing I did not like...
...
> It's worth documenting. I'd prefer not to override it in notmuch-help,
> because it's important to me that it behave like other help functions in
> emacs. users could defadvice it or something if they really want.

Hi Nelson,

I appreciate your desire to make notmuch work more consistently for
experienced users of emacs.

But this is a case where I think the emacs defaults are wrong for a new
user, (I'm imagining someone getting started with notmuch and that
otherwise doesn't use emacs regularly).

For a user like this I think it's important for the notmuch emacs
interface to not do any window-splitting by default. Without any
splitting the new user is given a consistent experience, (notmuch often
opens new windows and the user can clear any window by pressing "q" and
seeing the previous window).

But with window splitting, the user now needs to know a new command for
undoing the split, (such as C-x 1) or for switching between the windows
(such as C-x o).

So for this particular feature, I want the default behavior to open the
help window just like any other notmuch window, (even though that
doesn't match what emacs typically does for help windows). Then the
"experienced" emacs suers can be given a configuration option to get the
desired behavior.

Would you care to put together a patch to do that?

-Carl

-- 
carl.d.worth@intel.com

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

Re: [PATCH 2/2] emacs: notmuch-search-mode: wrap the documentation string

[Carl Worth]

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

On Fri, 14 May 2010 16:42:07 -0400, Nelson Elhage <nelhage@MIT.EDU> wrote:
> This makes for easier reading in the *help* window.

How are you getting unpleasant results here?

I intentionally implemented manual, "incorrect" wrapping in the
source. The idea is that once the text is actually displayed (whether
view `notmuch-help' or `describe-mode') those long command names should
be substituted by shorter keybindings and the final result should be
wrapped nicely.

For example, what I currently get after pressing "?" in a notmuch-search
buffer is as follows:

---
Pressing RET on any line displays that thread. The '+' and '-'
keys can be used to add or remove tags from a thread. The 'a' key
is a convenience for archiving a thread (removing the "inbox"
tag). The '*' key can be used to add or remove a tag from all
threads in the current buffer.

Other useful commands are 'f' for filtering the current search
based on an additional query string, 't' for filtering to include
only messages with a given tag, and 's' to execute a new, global
search.
---

And I think your wrapping change would make that displayed result
incorrect.

Is there something different about your environment that's making this
not work as desired?

-Carl

-- 
carl.d.worth@intel.com

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

Re: [PATCH 0/2]: emacs: Improve notmuch-help

[Carl Worth]

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

On Fri, 14 May 2010 16:46:31 -0400, Nelson Elhage <nelhage@MIT.EDU> wrote:
> Oops; I realized I haven't been signing off on last few patches I've
> sent.
> 
> Signed-off-by: Nelson Elhage <nelhage@mit.edu>

That's not a problem at all.

We don't require signed-off by for the notmuch project. Instead, people
should be adding Copyright attributions to any files that they change in
non-trivial ways.

And we should fix the notmuchmail.org web page to not point to the git
project's patch submission guidelines. Worse than the incorrect
information about Signed-off-by, those guidelines are *ridiculously*
*long*. We should instead have a very short list of the simplest, good
procedure for a new git user to follow.

As is, I wouldn't be surprised if potential contributors were scared
away by the length of the instructions.

-Carl

-- 
carl.d.worth@intel.com

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

Re: [PATCH 2/2] emacs: notmuch-search-mode: wrap the documentation string

[Nelson Elhage]

Hm. I was looking at the result of C-h f notmuch-search-mode RET, which
is how I'm used to looking at emacs documentation inside emacs. Having
just checked with an 'emacs -q', it looks like the notmuch "?" buffer
does wrap the docstring, but C-h f does not.

I feel like the right answer here is probably to make notmuch-help do
the right thing with manually-wrapped text, since that's the standard
thing for emacs documentation, and what emacs' built-in documentation
expects. I can try to come up with a patch that does that if you agree.

- Nelson

On Mon, 08 Nov 2010 09:35:47 -0800, Carl Worth <cworth@cworth.org> wrote:
> On Fri, 14 May 2010 16:42:07 -0400, Nelson Elhage <nelhage@MIT.EDU> wrote:
> > This makes for easier reading in the *help* window.
> 
> How are you getting unpleasant results here?
> 
> I intentionally implemented manual, "incorrect" wrapping in the
> source. The idea is that once the text is actually displayed (whether
> view `notmuch-help' or `describe-mode') those long command names should
> be substituted by shorter keybindings and the final result should be
> wrapped nicely.
> 
> For example, what I currently get after pressing "?" in a notmuch-search
> buffer is as follows:
> 
> ---
> Pressing RET on any line displays that thread. The '+' and '-'
> keys can be used to add or remove tags from a thread. The 'a' key
> is a convenience for archiving a thread (removing the "inbox"
> tag). The '*' key can be used to add or remove a tag from all
> threads in the current buffer.
> 
> Other useful commands are 'f' for filtering the current search
> based on an additional query string, 't' for filtering to include
> only messages with a given tag, and 's' to execute a new, global
> search.
> ---
> 
> And I think your wrapping change would make that displayed result
> incorrect.
> 
> Is there something different about your environment that's making this
> not work as desired?
> 
> -Carl
> 
> -- 
> carl.d.worth@intel.com
Non-text part: application/pgp-signature

Re: [PATCH 1/2] emacs: notmuch-help: Integrate into the emacs help system.

[Nelson Elhage]

I'll think about putting together that patch, although I am going on
vacation for a few weeks shortly, so it might not happen particularly
soon.

IME trying to use emacs without any window splitting is a bit of a lost
cause, but maybe you're right that it's possible if you're /just/ using
notmuch, so I'll work on that patch.

- Nelson

On Mon, 08 Nov 2010 09:29:42 -0800, Carl Worth <cworth@cworth.org> wrote:
> On Sat, 15 May 2010 17:07:42 -0400, Nelson Elhage <nelhage@MIT.EDU> wrote:
> > On Fri, 14 May 2010 15:47:24 -0700, "Sebastian Spaeth" <Sebastian@sspaethde> wrote:
> > > On 2010-05-14, Sebastian Spaeth wrote:
> > > > I just tried this and one thing I did not like...
> ..
> > It's worth documenting. I'd prefer not to override it in notmuch-help,
> > because it's important to me that it behave like other help functions in
> > emacs. users could defadvice it or something if they really want.
> 
> Hi Nelson,
> 
> I appreciate your desire to make notmuch work more consistently for
> experienced users of emacs.
> 
> But this is a case where I think the emacs defaults are wrong for a new
> user, (I'm imagining someone getting started with notmuch and that
> otherwise doesn't use emacs regularly).
> 
> For a user like this I think it's important for the notmuch emacs
> interface to not do any window-splitting by default. Without any
> splitting the new user is given a consistent experience, (notmuch often
> opens new windows and the user can clear any window by pressing "q" and
> seeing the previous window).
> 
> But with window splitting, the user now needs to know a new command for
> undoing the split, (such as C-x 1) or for switching between the windows
> (such as C-x o).
> 
> So for this particular feature, I want the default behavior to open the
> help window just like any other notmuch window, (even though that
> doesn't match what emacs typically does for help windows). Then the
> "experienced" emacs suers can be given a configuration option to get the
> desired behavior.
> 
> Would you care to put together a patch to do that?
> 
> -Carl
> 
> -- 
> carl.d.worth@intel.com
Non-text part: application/pgp-signature

Re: [PATCH 2/2] emacs: notmuch-search-mode: wrap the documentation string

[Nelson Elhage]

Oh, I see the problem. I wasn't paying attention -- the problem is that
C-h f substitutes "M-x <command-name>" for those keybindings, instead of
a keystroke, which is why it looks weird. That's annoying, but I'm not
sure what we can do, so I guess let's drop this patch in favor of it
looking good in the builtin help.

- Nelson

On Mon, 08 Nov 2010 12:51:24 -0500, Nelson Elhage <nelhage@MIT.EDU> wrote:
> Hm. I was looking at the result of C-h f notmuch-search-mode RET, which
> is how I'm used to looking at emacs documentation inside emacs. Having
> just checked with an 'emacs -q', it looks like the notmuch "?" buffer
> does wrap the docstring, but C-h f does not.
> 
> I feel like the right answer here is probably to make notmuch-help do
> the right thing with manually-wrapped text, since that's the standard
> thing for emacs documentation, and what emacs' built-in documentation
> expects. I can try to come up with a patch that does that if you agree.
> 
> - Nelson
> 
> On Mon, 08 Nov 2010 09:35:47 -0800, Carl Worth <cworth@cworth.org> wrote:
> > On Fri, 14 May 2010 16:42:07 -0400, Nelson Elhage <nelhage@MIT.EDU> wrote:
> > > This makes for easier reading in the *help* window.
> > 
> > How are you getting unpleasant results here?
> > 
> > I intentionally implemented manual, "incorrect" wrapping in the
> > source. The idea is that once the text is actually displayed (whether
> > view `notmuch-help' or `describe-mode') those long command names should
> > be substituted by shorter keybindings and the final result should be
> > wrapped nicely.
> > 
> > For example, what I currently get after pressing "?" in a notmuch-search
> > buffer is as follows:
> > 
> > ---
> > Pressing RET on any line displays that thread. The '+' and '-'
> > keys can be used to add or remove tags from a thread. The 'a' key
> > is a convenience for archiving a thread (removing the "inbox"
> > tag). The '*' key can be used to add or remove a tag from all
> > threads in the current buffer.
> > 
> > Other useful commands are 'f' for filtering the current search
> > based on an additional query string, 't' for filtering to include
> > only messages with a given tag, and 's' to execute a new, global
> > search.
> > ---
> > 
> > And I think your wrapping change would make that displayed result
> > incorrect.
> > 
> > Is there something different about your environment that's making this
> > not work as desired?
> > 
> > -Carl
> > 
> > -- 
> > carl.d.worth@intel.com
> Non-text part: application/pgp-signature
> _______________________________________________
> notmuch mailing list
> notmuch@notmuchmail.org
> http://notmuchmail.org/mailman/listinfo/notmuch
>