[PATCH] emacs: hello: promote '?' as the universal help key

[PATCH] emacs: hello: promote '?' as the universal help key

[Jani Nikula]

Move the brief help text at the bottom of the hello screen to the
notmuch-hello-mode help, and promote '?' as the universal help key
across Notmuch. This unclutters the hello screen, and allows for a
more verbose description in the mode help. Hopefully, this change is
useful for both experienced and new users alike.

While at it, improve the links to Notmuch and hello screen
customization.

---

This obsoletes
id:1450026221-23286-1-git-send-email-jani@nikula.org
---
 emacs/notmuch-hello.el                             | 44 +++++++++++++++++-----
 test/emacs.expected-output/notmuch-hello           |  7 +---
 .../emacs.expected-output/notmuch-hello-long-names |  7 +---
 .../notmuch-hello-no-saved-searches                |  7 +---
 .../emacs.expected-output/notmuch-hello-with-empty |  7 +---
 5 files changed, 42 insertions(+), 30 deletions(-)

diff --git a/emacs/notmuch-hello.el b/emacs/notmuch-hello.el
index b42e0f24148a..8a31f9a1c52c 100644
--- a/emacs/notmuch-hello.el
+++ b/emacs/notmuch-hello.el
@@ -672,6 +672,31 @@ with `notmuch-hello-query-counts'."
 (defun notmuch-hello-mode ()
  "Major mode for convenient notmuch navigation. This is your entry portal into notmuch.
 
+Saved searches are \"bookmarks\" for arbitrary queries. Hit RET
+or click on a saved search to view matching threads. Edit saved
+searches with the `edit' button. Type `\\[notmuch-jump-search]'
+in any Notmuch screen for quick access to saved searches that
+have shortcut keys.
+
+Type new searches in the search box and hit RET to view matching
+threads. Hit RET in a recent search box to re-submit a previous
+search. Edit it first if you like. Save a recent search to saved
+searches with the `save' button.
+
+Hit `\\[notmuch-search]' or `\\[notmuch-tree]' in any Notmuch
+screen to search for messages and view matching threads or
+messages, respectively. Recent searches are available in the
+minibuffer history.
+
+Expand the all tags view with the `show' button (and collapse
+again with the `hide' button). Hit RET or click on a tag name to
+view matching threads.
+
+Hit `\\[notmuch-refresh-this-buffer]' to refresh the screen and
+`\\[notmuch-bury-or-kill-this-buffer]' to quit.
+
+The screen may be customized via `\\[customize]'.
+
 Complete list of currently available key bindings:
 
 \\{notmuch-hello-mode-map}"
@@ -907,20 +932,19 @@ following:
 (defun notmuch-hello-insert-footer ()
   "Insert the notmuch-hello footer."
   (let ((start (point)))
-    (widget-insert "Type a search query and hit RET to view matching threads.\n")
-    (when notmuch-search-history
-      (widget-insert "Hit RET to re-submit a previous search. Edit it first if you like.\n")
-      (widget-insert "Save recent searches with the `save' button.\n"))
-    (when notmuch-saved-searches
-      (widget-insert "Edit saved searches with the `edit' button.\n"))
-    (widget-insert "Hit RET or click on a saved search or tag name to view matching threads.\n")
-    (widget-insert "`=' to refresh this screen. `s' to search messages. `q' to quit.\n")
+    (widget-insert "Hit `?' for context-sensitive help in any Notmuch screen.\n")
+    (widget-insert "Customize ")
+    (widget-create 'link
+		   :notify (lambda (&rest ignore)
+			     (customize-group 'notmuch))
+		   :button-prefix "" :button-suffix ""
+		   "Notmuch")
+    (widget-insert " or ")
     (widget-create 'link
 		   :notify (lambda (&rest ignore)
 			     (customize-variable 'notmuch-hello-sections))
 		   :button-prefix "" :button-suffix ""
-		   "Customize")
-    (widget-insert " this page.")
+		   "this page.")
     (let ((fill-column (- (window-width) notmuch-hello-indent)))
       (center-region start (point)))))
 
diff --git a/test/emacs.expected-output/notmuch-hello b/test/emacs.expected-output/notmuch-hello
index 9ba4cfc1d560..89186082f8a9 100644
--- a/test/emacs.expected-output/notmuch-hello
+++ b/test/emacs.expected-output/notmuch-hello
@@ -8,8 +8,5 @@ Search:                                                                     .
 
 All tags: [show]
 
-	 Type a search query and hit RET to view matching threads.
-		Edit saved searches with the `edit' button.
-  Hit RET or click on a saved search or tag name to view matching threads.
-      `=' to refresh this screen. `s' to search messages. `q' to quit.
-			    Customize this page.
+	 Hit `?' for context-sensitive help in any Notmuch screen.
+		      Customize Notmuch or this page.
diff --git a/test/emacs.expected-output/notmuch-hello-long-names b/test/emacs.expected-output/notmuch-hello-long-names
index 1c8d6eb624b9..da0f3525325d 100644
--- a/test/emacs.expected-output/notmuch-hello-long-names
+++ b/test/emacs.expected-output/notmuch-hello-long-names
@@ -11,8 +11,5 @@ All tags: [hide]
 	  52 a-very-long-tag       52 inbox                 52 unread
 	   4 attachment             7 signed
 
-	 Type a search query and hit RET to view matching threads.
-		Edit saved searches with the `edit' button.
-  Hit RET or click on a saved search or tag name to view matching threads.
-      `=' to refresh this screen. `s' to search messages. `q' to quit.
-			    Customize this page.
+	 Hit `?' for context-sensitive help in any Notmuch screen.
+		      Customize Notmuch or this page.
diff --git a/test/emacs.expected-output/notmuch-hello-no-saved-searches b/test/emacs.expected-output/notmuch-hello-no-saved-searches
index 05475b15abee..939965fef154 100644
--- a/test/emacs.expected-output/notmuch-hello-no-saved-searches
+++ b/test/emacs.expected-output/notmuch-hello-no-saved-searches
@@ -4,8 +4,5 @@ Search:                                                                     .
 
 All tags: [show]
 
-	 Type a search query and hit RET to view matching threads.
-		Edit saved searches with the `edit' button.
-  Hit RET or click on a saved search or tag name to view matching threads.
-      `=' to refresh this screen. `s' to search messages. `q' to quit.
-			    Customize this page.
+	 Hit `?' for context-sensitive help in any Notmuch screen.
+		      Customize Notmuch or this page.
diff --git a/test/emacs.expected-output/notmuch-hello-with-empty b/test/emacs.expected-output/notmuch-hello-with-empty
index 854e0c2a22e8..97d7db26ebfa 100644
--- a/test/emacs.expected-output/notmuch-hello-with-empty
+++ b/test/emacs.expected-output/notmuch-hello-with-empty
@@ -8,8 +8,5 @@ Search:                                                                     .
 
 All tags: [show]
 
-	 Type a search query and hit RET to view matching threads.
-		Edit saved searches with the `edit' button.
-  Hit RET or click on a saved search or tag name to view matching threads.
-      `=' to refresh this screen. `s' to search messages. `q' to quit.
-			    Customize this page.
+	 Hit `?' for context-sensitive help in any Notmuch screen.
+		      Customize Notmuch or this page.
-- 
2.1.4

Re: [PATCH] emacs: hello: promote '?' as the universal help key

[David Edmondson]

Looks good, thanks for doing it.

On Sun, Mar 13 2016, Jani Nikula wrote:
> Move the brief help text at the bottom of the hello screen to the
> notmuch-hello-mode help, and promote '?' as the universal help key
> across Notmuch. This unclutters the hello screen, and allows for a
> more verbose description in the mode help. Hopefully, this change is
> useful for both experienced and new users alike.
>
> While at it, improve the links to Notmuch and hello screen
> customization.
>
> ---
>
> This obsoletes
> id:1450026221-23286-1-git-send-email-jani@nikula.org
> ---
>  emacs/notmuch-hello.el                             | 44 +++++++++++++++++-----
>  test/emacs.expected-output/notmuch-hello           |  7 +---
>  .../emacs.expected-output/notmuch-hello-long-names |  7 +---
>  .../notmuch-hello-no-saved-searches                |  7 +---
>  .../emacs.expected-output/notmuch-hello-with-empty |  7 +---
>  5 files changed, 42 insertions(+), 30 deletions(-)
>
> diff --git a/emacs/notmuch-hello.el b/emacs/notmuch-hello.el
> index b42e0f24148a..8a31f9a1c52c 100644
> --- a/emacs/notmuch-hello.el
> +++ b/emacs/notmuch-hello.el
> @@ -672,6 +672,31 @@ with `notmuch-hello-query-counts'."
>  (defun notmuch-hello-mode ()
>   "Major mode for convenient notmuch navigation. This is your entry portal into notmuch.
>  
> +Saved searches are \"bookmarks\" for arbitrary queries. Hit RET
> +or click on a saved search to view matching threads. Edit saved
> +searches with the `edit' button. Type `\\[notmuch-jump-search]'
> +in any Notmuch screen for quick access to saved searches that
> +have shortcut keys.
> +
> +Type new searches in the search box and hit RET to view matching
> +threads. Hit RET in a recent search box to re-submit a previous
> +search. Edit it first if you like. Save a recent search to saved
> +searches with the `save' button.
> +
> +Hit `\\[notmuch-search]' or `\\[notmuch-tree]' in any Notmuch
> +screen to search for messages and view matching threads or
> +messages, respectively. Recent searches are available in the
> +minibuffer history.
> +
> +Expand the all tags view with the `show' button (and collapse
> +again with the `hide' button). Hit RET or click on a tag name to
> +view matching threads.
> +
> +Hit `\\[notmuch-refresh-this-buffer]' to refresh the screen and
> +`\\[notmuch-bury-or-kill-this-buffer]' to quit.
> +
> +The screen may be customized via `\\[customize]'.
> +
>  Complete list of currently available key bindings:
>  
>  \\{notmuch-hello-mode-map}"
> @@ -907,20 +932,19 @@ following:
>  (defun notmuch-hello-insert-footer ()
>    "Insert the notmuch-hello footer."
>    (let ((start (point)))
> -    (widget-insert "Type a search query and hit RET to view matching threads.\n")
> -    (when notmuch-search-history
> -      (widget-insert "Hit RET to re-submit a previous search. Edit it first if you like.\n")
> -      (widget-insert "Save recent searches with the `save' button.\n"))
> -    (when notmuch-saved-searches
> -      (widget-insert "Edit saved searches with the `edit' button.\n"))
> -    (widget-insert "Hit RET or click on a saved search or tag name to view matching threads.\n")
> -    (widget-insert "`=' to refresh this screen. `s' to search messages. `q' to quit.\n")
> +    (widget-insert "Hit `?' for context-sensitive help in any Notmuch screen.\n")
> +    (widget-insert "Customize ")
> +    (widget-create 'link
> +		   :notify (lambda (&rest ignore)
> +			     (customize-group 'notmuch))
> +		   :button-prefix "" :button-suffix ""
> +		   "Notmuch")
> +    (widget-insert " or ")
>      (widget-create 'link
>  		   :notify (lambda (&rest ignore)
>  			     (customize-variable 'notmuch-hello-sections))
>  		   :button-prefix "" :button-suffix ""
> -		   "Customize")
> -    (widget-insert " this page.")
> +		   "this page.")
>      (let ((fill-column (- (window-width) notmuch-hello-indent)))
>        (center-region start (point)))))
>  
> diff --git a/test/emacs.expected-output/notmuch-hello b/test/emacs.expected-output/notmuch-hello
> index 9ba4cfc1d560..89186082f8a9 100644
> --- a/test/emacs.expected-output/notmuch-hello
> +++ b/test/emacs.expected-output/notmuch-hello
> @@ -8,8 +8,5 @@ Search:                                                                     .
>  
>  All tags: [show]
>  
> -	 Type a search query and hit RET to view matching threads.
> -		Edit saved searches with the `edit' button.
> -  Hit RET or click on a saved search or tag name to view matching threads.
> -      `=' to refresh this screen. `s' to search messages. `q' to quit.
> -			    Customize this page.
> +	 Hit `?' for context-sensitive help in any Notmuch screen.
> +		      Customize Notmuch or this page.
> diff --git a/test/emacs.expected-output/notmuch-hello-long-names b/test/emacs.expected-output/notmuch-hello-long-names
> index 1c8d6eb624b9..da0f3525325d 100644
> --- a/test/emacs.expected-output/notmuch-hello-long-names
> +++ b/test/emacs.expected-output/notmuch-hello-long-names
> @@ -11,8 +11,5 @@ All tags: [hide]
>  	  52 a-very-long-tag       52 inbox                 52 unread
>  	   4 attachment             7 signed
>  
> -	 Type a search query and hit RET to view matching threads.
> -		Edit saved searches with the `edit' button.
> -  Hit RET or click on a saved search or tag name to view matching threads.
> -      `=' to refresh this screen. `s' to search messages. `q' to quit.
> -			    Customize this page.
> +	 Hit `?' for context-sensitive help in any Notmuch screen.
> +		      Customize Notmuch or this page.
> diff --git a/test/emacs.expected-output/notmuch-hello-no-saved-searches b/test/emacs.expected-output/notmuch-hello-no-saved-searches
> index 05475b15abee..939965fef154 100644
> --- a/test/emacs.expected-output/notmuch-hello-no-saved-searches
> +++ b/test/emacs.expected-output/notmuch-hello-no-saved-searches
> @@ -4,8 +4,5 @@ Search:                                                                     .
>  
>  All tags: [show]
>  
> -	 Type a search query and hit RET to view matching threads.
> -		Edit saved searches with the `edit' button.
> -  Hit RET or click on a saved search or tag name to view matching threads.
> -      `=' to refresh this screen. `s' to search messages. `q' to quit.
> -			    Customize this page.
> +	 Hit `?' for context-sensitive help in any Notmuch screen.
> +		      Customize Notmuch or this page.
> diff --git a/test/emacs.expected-output/notmuch-hello-with-empty b/test/emacs.expected-output/notmuch-hello-with-empty
> index 854e0c2a22e8..97d7db26ebfa 100644
> --- a/test/emacs.expected-output/notmuch-hello-with-empty
> +++ b/test/emacs.expected-output/notmuch-hello-with-empty
> @@ -8,8 +8,5 @@ Search:                                                                     .
>  
>  All tags: [show]
>  
> -	 Type a search query and hit RET to view matching threads.
> -		Edit saved searches with the `edit' button.
> -  Hit RET or click on a saved search or tag name to view matching threads.
> -      `=' to refresh this screen. `s' to search messages. `q' to quit.
> -			    Customize this page.
> +	 Hit `?' for context-sensitive help in any Notmuch screen.
> +		      Customize Notmuch or this page.
> -- 
> 2.1.4

Re: [PATCH] emacs: hello: promote '?' as the universal help key

[Tomi Ollila]

On Sun, Mar 13 2016, Jani Nikula <jani@nikula.org> wrote:

> [ text/plain ]
> Move the brief help text at the bottom of the hello screen to the
> notmuch-hello-mode help, and promote '?' as the universal help key
> across Notmuch. This unclutters the hello screen, and allows for a
> more verbose description in the mode help. Hopefully, this change is
> useful for both experienced and new users alike.
>
> While at it, improve the links to Notmuch and hello screen
> customization.

looks good, works fine. +1

Tomi

PS: kept [text/plain] just for users' annoyance ;)

Re: [PATCH] emacs: hello: promote '?' as the universal help key

[David Bremner]

Jani Nikula <jani@nikula.org> writes:

> Move the brief help text at the bottom of the hello screen to the
> notmuch-hello-mode help, and promote '?' as the universal help key
> across Notmuch. This unclutters the hello screen, and allows for a
> more verbose description in the mode help. Hopefully, this change is
> useful for both experienced and new users alike.
>
> While at it, improve the links to Notmuch and hello screen
> customization.

pushed.

d