w3m-search feedback for whether in new or current session [PATCH]

[Boruch Baum <boruch_baum@xxxxxxx>]

Just like emacs-w3m allows one to enter a url to be opened in the
current session (g)[`w3m-goto-url'] or in a new session
(G)[`w3m-goto-url-new-session'], it allows one to get a search result in
either the current session (S)[`w3m-search'] or in a new session
[`w3m-search-new-session'].

This patch gives the user visible feedback for which option was
selected, to avoid 'losing' the current session if one mistakenly
performs `w3m-search' instead of `w3m-search-new-session'.

But, There is more to consider for this issue than just the patch:

1] Default key-bindings:

The project doesn't by default bind a key to `w3m-search-new-session',
though I would think that would be a very desirable function. I wanted
to propose binding it to 's', but that binding is already used for
`w3m-history' (in my personal opinion and personal experience, rarely
used).

What I've done on my personal system and what I propose, is to map 's'
to `w3m-search', and 'S' to `w3m-search-new-session'. The result is that
there is a parallel between the two search functions (s,S) the two go-to
functions (g,G), the two bookmark functions (v,V), and possibly others.
The loser would be `w3m-history'.

2] Terminology (sessions, buffers, tabs, windows)

The project has an annoying inconsistency in how it refers to `things'.
Emacs-w3m often uses the term 'session' to refer to an emacs buffer,
what most browsers would call a 'tab'[1], but sometimes to refer to the
collection of all buffers[2]. And although the project often refers to
emacs buffers as 'sessions', it also refers to them as buffers[3].

I'd like to propose that the project start changing documentation and
user-prompts to be more consistent, and to acknowledge the duplication
of terms. 'Sessions' should refer to the collection of all w3m 'buffers'
(or 'tabs') open at a time.

I'm raising the issue for this patch because it is a good example and
starting point. The patch as submitted respects the current terminology,
but I think it should be re-worded to replace session with either
'buffer' or 'tab'. My inclination is to favor 'buffer'.

The elephant in the room would be the matter of re-factoring the
code-base, which is do-able, and which can include defining aliases to
old symbol names, for a deprecation period.


Footnotes:
━━━━━━━━━━
[1] e.g., w3m-goto-url-new-session, w3m-search-new-session,
    w3m-bookmark-view-new-session.

[2] e.g., the functions of file w3m-session.el.

[3] e.g., w3m-next-buffer, w3m-previous-buffer, w3m-copy-buffer.

-- 
hkp://keys.gnupg.net
CA45 09B5 5351 7C11 A9D1  7286 0036 9E45 1595 8BC0

Index: w3m-search.el
===================================================================
RCS file: /storage/cvsroot/emacs-w3m/w3m-search.el,v
retrieving revision 1.82
diff -u -w -B -r1.82 w3m-search.el
--- w3m-search.el	2 Aug 2017 07:39:19 -0000	1.82
+++ w3m-search.el	7 Dec 2017 10:27:18 -0000
@@ -284,26 +284,27 @@
 		   prompt)
 		 initial history default)))
 
-(defun w3m-search-read-variables ()
+(defun w3m-search-read-variables (session)
   "Ask for a search engine and words to query and return them as a list."
   (when w3m-current-process
     (error "%s"
 	   (substitute-command-keys "
 Cannot run two w3m processes simultaneously \
 \(Type `\\<w3m-mode-map>\\[w3m-process-stop]' to stop asynchronous process)")))
-  (let* ((search-engine
+  (let* ((prompt-prefix (format "Search in %s session. " session))
+         (search-engine
 	  (if current-prefix-arg
 	      (let ((default (or (car w3m-search-engine-history)
 				 w3m-search-default-engine))
 		    (completion-ignore-case t))
-		(completing-read (format "Which engine? (default %s): "
-					 default)
+		(completing-read (format "%sWhich engine? (default %s): "
+					 prompt-prefix default)
 				 w3m-search-engine-alist nil t nil
 				 'w3m-search-engine-history default))
 	    w3m-search-default-engine))
 	 (query
 	  (w3m-search-read-query
-	   (format "%s search: " search-engine)
+	   (format "%s %s search: " prompt-prefix search-engine)
 	   (format "%s search (default %%s): " search-engine))))
     (list search-engine query)))
 
@@ -331,13 +332,13 @@
 `w3m-search-default-engine'.
 If Transient Mark mode, use the region as an initial string of query
 and deactivate the mark."
-  (interactive (w3m-search-read-variables))
+  (interactive (w3m-search-read-variables "current"))
   (w3m-search-do-search 'w3m-goto-url search-engine query))
 
 ;;;###autoload
 (defun w3m-search-new-session (search-engine query)
   "Like `w3m-search', but do the search in a new session."
-  (interactive (w3m-search-read-variables))
+  (interactive (w3m-search-read-variables "new"))
   (w3m-search-do-search 'w3m-goto-url-new-session search-engine query))
 
 ;;;###autoload
Index: ChangeLog
===================================================================
RCS file: /storage/cvsroot/emacs-w3m/ChangeLog,v
retrieving revision 1.3634
diff -u -w -B -r1.3634 ChangeLog
--- ChangeLog	7 Dec 2017 06:59:28 -0000	1.3634
+++ ChangeLog	7 Dec 2017 10:27:20 -0000
@@ -1,3 +1,9 @@
+2017-12-07  Boruch Baum  <boruch_baum@xxxxxxx>
+
+	* w3m-search.el (w3m-search, w3m-search-new-session)
+	(w3m-search-read-variables): Provide visual feedback for whether search
+	will be in new or current session.
+
 2017-12-07  Katsumi Yamaoka  <yamaoka@xxxxxxx>
 
 	* w3mhack.el: Require seq.