[Date Prev][Date Next][Thread Prev][][Date Index][Thread Index]

Re: w3m-pop-up-windows and w3m-use-tab [PATCH]



On 2018-03-12 09:09, Katsumi Yamaoka wrote:
> In [emacs-w3m:12934]
> On Fri, 09 Mar 2018 11:28:33 -0500, Boruch Baum wrote:
> > why are there three separate variables? They could easily be
> > replaced with a single `w3m-display-mode' set to one of the five
> > options. This would also make it easier for users like me (and for
> > developers?), rather than having to figure out the interaction
> > between all the variables.
>
> I think it's a good idea that `w3m-display-mode' overrides
> w3m-use-tab, w3m-pop-up-windows, and w3m-pop-up-frames if and
> only if it is non-nil.

I'm attaching a first version of a patch this quickly because its nature
turned out to be over 90% documentation for clarity, and the actual code
amounts to simple and modular plug-ins. However, at this point I've only
done minor testing on it, so I'm sharing it primarily for its
documentation value. Don't get me wrong - if anyone has got some time
and wants to evaluate it, great.

... and yes, I know, the final patch will need a verrrrrrrry long
Changelog entry ....

Regards,


-- 
hkp://keys.gnupg.net
CA45 09B5 5351 7C11 A9D1  7286 0036 9E45 1595 8BC0
Index: w3m-bookmark.el
===================================================================
RCS file: /storage/cvsroot/emacs-w3m/w3m-bookmark.el,v
retrieving revision 1.58
diff -u -r1.58 w3m-bookmark.el
--- w3m-bookmark.el	11 Dec 2017 04:30:37 -0000	1.58
+++ w3m-bookmark.el	12 Mar 2018 10:52:02 -0000
@@ -331,7 +331,7 @@
   "Add urls of all pages being visited to the bookmark."
   (interactive)
   (let ((buffers (w3m-list-buffers)))
-    (if (and w3m-use-tab
+    (if (and (w3m--display-mode 'use-tab)
 	     (>= (length buffers) 2))
 	(while buffers
 	  (switch-to-buffer (pop buffers))
Index: w3m-ems.el
===================================================================
RCS file: /storage/cvsroot/emacs-w3m/w3m-ems.el,v
retrieving revision 1.66
diff -u -r1.66 w3m-ems.el
--- w3m-ems.el	27 Feb 2018 06:23:35 -0000	1.66
+++ w3m-ems.el	12 Mar 2018 10:52:03 -0000
@@ -75,7 +75,8 @@
   (defvar w3m-use-favicon)
   (defvar w3m-use-header-line)
   (defvar w3m-use-header-line-title)
-  (defvar w3m-use-tab)
+  (defvar w3m-display-mode)   ;; BB 2018-03-12 Not sure if this defvar
+                              ;; is necessary. Replaces `w3m-use-tab',
   ;; `w3m-tab-move-right' calls the inline function `w3m-buffer-set-number'
   ;; which uses it.
   (defvar w3m-use-title-buffer-name)
@@ -815,7 +816,7 @@

 (defun w3m-setup-header-line ()
   (setq header-line-format
-	(cond (w3m-use-tab
+	(cond ((w3m--display-mode 'use-tab)
 	       '(:eval (w3m-tab-line)))
 	      (w3m-use-header-line
 	       (list
@@ -951,7 +952,7 @@
 EVENT is a command event.  ORDER is the order number in tabs.
 The optional DECELERATE if it is non-nil means not to respond to too
 fast operation of mouse wheel."
-  (when (and w3m-use-tab window-system w3m-tab-track-mouse
+  (when (and (w3m--display-mode 'use-tab) window-system w3m-tab-track-mouse
 	     (consp event) (symbolp (car event)))
     (let ((e (get (car event) 'event-symbol-elements))
 	  (len (* (car w3m-tab-mouse-position-adjuster) order))
Index: w3m-fb.el
===================================================================
RCS file: /storage/cvsroot/emacs-w3m/w3m-fb.el,v
retrieving revision 1.6
diff -u -r1.6 w3m-fb.el
--- w3m-fb.el	18 Feb 2018 23:10:22 -0000	1.6
+++ w3m-fb.el	12 Mar 2018 10:52:03 -0000
@@ -17,11 +17,15 @@

 ;;; Commentary:
 ;;
+;; This mode handles the DEDICATED-FRAMES and TABBED-DEDICATED-FRAMES
+;; display options, set in variable `w3m-display-mode' as 'frames or
+;; 'tabbed-frames.
+;;
 ;; With this mode switched on, W3M buffers are associated with the
-;; frame on which they were created.  Only tabs for the current
-;; frame's W3M buffers are shown (with non-nil w3m-use-tab); other
-;; affected commands are w3m-next-buffer w3m-previous-buffer,
-;; w3m-select-buffer and w3m-quit.
+;; frame on which they were created. For TABBED-DEDICATED-FRAMES, only
+;; tabs for the current frame's W3M buffers are shown; other affected
+;; commands are w3m-next-buffer w3m-previous-buffer, w3m-select-buffer
+;; and w3m-quit.
 ;;
 ;; Switch the mode on programmatically with:
 ;;
@@ -38,8 +42,8 @@
   (autoload 'w3m-delete-buffer "w3m" nil t)
   (autoload 'w3m-list-buffers "w3m-util")
   (autoload 'w3m-next-buffer "w3m" nil t)
-  (defvar w3m-pop-up-frames))
-
+  (defvar w3m-display-mode)) ;; BB 2018-03-12 Not sure if this defvar
+                             ;; is necessary. Replaces `w3m-pop-up-frames',
 (eval-and-compile
   (defalias 'w3m-fb-frame-parameter
     (cond
@@ -171,11 +175,11 @@
   :group 'w3m-fb
   :global t
   (if (and w3m-fb-mode
-	   (if w3m-pop-up-frames
+	   (if (w3m--display-mode 'pop-up-frames)
 	       (prog1
 		   (setq w3m-fb-mode nil)
 		 (message "\
-W3M Frame Buffer mode not activated (non-nil w3m-pop-up-frames)")
+W3M Frame Buffer mode not activated (w3m--display-mode 'pop-up-frames).")
 		 (sit-for 2))
 	     t))
       (progn
Index: w3m-util.el
===================================================================
RCS file: /storage/cvsroot/emacs-w3m/w3m-util.el,v
retrieving revision 1.190
diff -u -r1.190 w3m-util.el
--- w3m-util.el	27 Feb 2018 06:27:25 -0000	1.190
+++ w3m-util.el	12 Mar 2018 10:52:03 -0000
@@ -50,14 +50,14 @@
   (defvar w3m-fb-list-buffers-frame)
   (defvar w3m-fb-mode)
   (defvar w3m-mode-hook)
-  (defvar w3m-pop-up-frames)
-  (defvar w3m-pop-up-windows)
   (defvar w3m-popup-frame-parameters)
   (defvar w3m-previous-session-buffer)
   (defvar w3m-refresh-timer)
   (defvar w3m-select-buffer-name)
   (defvar w3m-use-refresh)
-  (defvar w3m-use-tab)
+  (defvar w3m-display-mode)  ;; BB 2018-03-12 Not sure if this defvar
+                             ;; is necessary. Replaces `w3m-use-tab',
+                             ;; `w3m-pop-up-windows' and `w3m-pop-up-frames'.
   (defvar w3m-work-buffer-list)
   (defvar w3m-use-japanese-menu)
   (defvar w3m-mode-map)
@@ -504,7 +504,7 @@
 		    (sort rest #'w3m-buffer-name-lessp)))
     (when (and (boundp 'w3m-fb-mode)
 	       w3m-fb-mode
-	       (if (or w3m-pop-up-frames
+	       (if (or (w3m--display-mode 'pop-up-frames)
 		       (not (memq 'w3m-fb-add w3m-mode-hook)))
 		   ;; `w3m-fb-mode' might have been set by something
 		   ;; other than the `w3m-fb-mode' function.
@@ -546,19 +546,6 @@
       (device-on-window-system-p)
     window-system))

-(defmacro w3m-popup-frame-p ()
-  "Return non-nil if `w3m-pop-up-frames' is non-nil and Emacs really
-supports separate frames."
-  '(and w3m-pop-up-frames (w3m-device-on-window-system-p)))
-
-(defmacro w3m-use-tab-p ()
-  "Return non-nil if `w3m-use-tab' is non-nil and Emacs really supports
-the tabs line."
-  (cond ((featurep 'xemacs)
-	 '(and w3m-use-tab (device-on-window-system-p)))
-	(t
-	 'w3m-use-tab)))
-
 (defun w3m-lefttab-exist-p (&optional buffer)
   (not (eq (or buffer (current-buffer)) (car (w3m-list-buffers)))))

@@ -572,13 +559,6 @@
 	(when (eq cbuf buf)
 	  (throw 'exist bufs))))))

-(defmacro w3m-popup-window-p ()
-  "Return non-nil if `w3m-pop-up-windows' is non-nil and the present
-situation allows it."
-  '(and w3m-pop-up-windows
-	(not (w3m-use-tab-p))
-	(not (get-buffer-window w3m-select-buffer-name))))
-
 (defvar w3m-initial-frames nil
   "Variable used to keep a list of the frame-IDs when emacs-w3m sessions
 are popped-up as new frames.  This variable is used for the control
@@ -586,8 +566,7 @@
 (make-variable-buffer-local 'w3m-initial-frames)

 (defun w3m-popup-buffer (buffer)
-  "Pop up BUFFER as a new window or a new frame
-according to `w3m-pop-up-windows' and `w3m-pop-up-frames' (which see)."
+  "Pop up BUFFER as a new window or a new frame, per the `w3m-display-mode'."
   (let ((window (get-buffer-window buffer t))
 	oframe popup-frame-p frame pop-up-frames buffers other)
     (unless (eq window (selected-window))
@@ -601,7 +580,7 @@
 	     ;; There is no window for BUFFER, so look for the existing
 	     ;; emacs-w3m window if the tabs line is enabled or the
 	     ;; selection window exists (i.e., we can reuse it).
-	     (if (or (w3m-use-tab-p)
+	     (if (or (w3m--display-mode 'use-tab)
 		     (get-buffer-window w3m-select-buffer-name t))
 		 (progn
 		   (setq buffers (delq buffer (w3m-list-buffers t)))
@@ -612,8 +591,11 @@
 		   (if window ;; The window showing another buffer exists.
 		       (not (eq (setq frame (window-frame window)) oframe))
 		     (setq other nil)
-		     ;; There is no window after all, so leave to the value
-		     ;; of `w3m-pop-up-frames' whether to pop up a new frame.
+		     ;; ;; There is no window after all, so leave to the value
+		     ;; ;; of `w3m-pop-up-frames' whether to pop up a new frame.
+                     ;; BB 2018-03-12 - I don't understand the comment. It seems
+                     ;; like a decision to ignore w3m-display-mode in favor of
+                     ;; the native emacs setting.
 		     popup-frame-p))
 	       ;; Ditto.
 	       popup-frame-p)))
@@ -670,13 +652,13 @@
   (unless frame
     (setq frame (selected-frame)))
   ;; Share the opened frame in `w3m-initial-frames' over all emacs-w3m
-  ;; buffers if `w3m-use-tab' is non-nil.  Otherwise, the frame is
+  ;; buffers if using a tabbed display mode.  Otherwise, the frame is
   ;; appended into `w3m-initial-frames' only in the current buffer.
   (with-current-buffer (window-buffer (frame-first-window frame))
     (when (eq major-mode 'w3m-mode)
       (unless (memq frame w3m-initial-frames)
 	(push frame w3m-initial-frames))
-      (when w3m-use-tab
+      (when (w3m--display-mode 'use-tab)
 	(dolist (buffer (delq (current-buffer) (w3m-list-buffers t)))
 	  (set-buffer buffer)
 	  (unless (memq frame w3m-initial-frames)
Index: w3m-xmas.el
===================================================================
RCS file: /storage/cvsroot/emacs-w3m/w3m-xmas.el,v
retrieving revision 1.158
diff -u -r1.158 w3m-xmas.el
--- w3m-xmas.el	4 Sep 2013 02:39:48 -0000	1.158
+++ w3m-xmas.el	12 Mar 2018 10:52:04 -0000
@@ -58,7 +58,8 @@
   (defvar w3m-show-graphic-icons-in-mode-line)
   (defvar w3m-toolbar)
   (defvar w3m-toolbar-buttons)
-  (defvar w3m-use-tab)
+  (defvar w3m-display-mode)  ;; BB 2018-03-12 Not sure if this defvar
+                             ;; is necessary. Replaces `w3m-use-tab',
   (defvar w3m-use-tab-menubar)
   (defvar w3m-work-buffer-name)
   (defvar w3m-work-buffer-list)
@@ -762,14 +763,14 @@
   (defun w3m-setup-tab-in-gutter ()
     "Set up buffers tab in the gutter."
     (set-specifier default-gutter-visible-p
-		   (and w3m-use-tab gutter-buffers-tab-enabled t)
+		   (and (w3m--display-mode 'use-tab) gutter-buffers-tab-enabled t)
 		   (current-buffer)))
   (add-hook 'w3m-mode-setup-functions 'w3m-setup-tab-in-gutter)
   (add-hook 'w3m-select-buffer-mode-hook 'w3m-setup-tab-in-gutter)

   (defun w3m-update-tab-in-gutter (&rest args)
     "Update the tab control in the gutter area."
-    (when (and w3m-use-tab gutter-buffers-tab-enabled)
+    (when (and (w3m--display-mode 'use-tab) gutter-buffers-tab-enabled)
       (update-tab-in-gutter (selected-frame))))
   (add-hook 'w3m-display-functions 'w3m-update-tab-in-gutter))

Index: w3m.el
===================================================================
RCS file: /storage/cvsroot/emacs-w3m/w3m.el,v
retrieving revision 1.1706
diff -u -r1.1706 w3m.el
--- w3m.el	27 Feb 2018 06:23:35 -0000	1.1706
+++ w3m.el	12 Mar 2018 10:52:09 -0000
@@ -1550,11 +1550,95 @@
 	   (unless noninteractive
 	     (w3m-menu-on-forefront value)))))

+(defcustom w3m-display-mode nil
+  "How to display emacs-w3m buffers.
+
+There exist five display modes for emacs-w3m called
+interactively: Plain, Tabbed, Dual-Pane, Dedicated-Frames, and
+Tabbed-Dedicated-Frames. When emacs-w3m is run in batch mode or
+non-interactively, only the Plain or Tabbed display modes are
+available.
+
+In the past, these modes had been set by a combination of three
+now-deprecated variables, `w3m-use-tab', `w3m-pop-up-windows' and
+`w3m-pop-up-frames', but can now be set with this single setting
+`w3m-display-mode'. When this variable is set, the other three
+are ignored.
+
+PLAIN: Each emacs-w3m buffer exists on its own and can appear in
+any window in any frame, although a reasonable attempt will be
+made to re-use an existing window. There is no tab bar. In the
+past, this had been set by the combination: `w3m-use-tab' nil,
+`w3m-pop-up-windows' nil, and `w3m-pop-up-frames' nil.
+
+TABBED: A reasonable attempt is made to keep only one window
+displaying emacs-w3m buffers. That window has a cliackable tab
+bar along the top. Users can manually subvert this by explicitly
+opening an emacs-w3m buffer in any number of other windows. In
+the past, this had been set by the combination: `w3m-use-tab' t
+`w3m-pop-up-windows' ignored, and `w3m-pop-up-frames' nil.
+
+DUAL-PANE: Once more than one emacs-w3m buffer exists, a
+reasonable attempt is made to present emacs-w3m in two windows on
+the same frame. Any action to open a new emacs-w3m buffer, such
+as `w3m-goto-url-new-session' or `w3m-search-new-session'
+displays the new buffer in the unfocused pane, and transfers
+focus there. In the past, this had been set by the combination:
+`w3m-use-tab' nil `w3m-pop-up-windows' t, and `w3m-pop-up-frames'
+nil.
+
+DEDICATED-FRAMES: Each new emacs-w3m buffer is opened in a new
+single-window frame. In the past, this had been set by the
+combination: `w3m-use-tab' nil `w3m-pop-up-windows' ignored, and
+`w3m-pop-up-frames' t.
+
+TABBED-DEDICATED-FRAMES: Each new emacs-w3m buffer is opened in
+the same window of the frame from which it was spawned, and is
+not easily visible to emacs-w3m buffers associated with other
+frames. The window includes a clickable tab bar along the top. In
+the past, this had been set by the combination: `w3m-use-tab' t
+`w3m-pop-up-windows' ignored, and `w3m-pop-up-frames' t."
+  :type '(radio (const :format "Unset" nil)
+		(const :format "Plain" plain)
+		(const :format "Tabbed" tabbed)
+		(const :format "Dual-pane" dual-pane)
+		(const :format "Dedicated Frames" frames)
+		(const :format "Tabbed Dedicated Frames" tabbed-frames)))
+
+(defun w3m--display-mode (detail)
+  "Return useful display details for the current `w3m-display-mode'.
+Valid values for DETAIL are 'use-tab, 'pop-up-windows, or 'pop-up-frames."
+  (cond
+   ((equal detail 'pop-up-windows)
+      (and interactive-p ;; ref NOTE: BB_2018-03-12_001 below
+           (not (get-buffer-window w3m-select-buffer-name)) ;; from macro `w3m-popup-window-p'
+        (if (not w3m-display-mode) w3m-pop-up-windows)
+         (if (equal w3m-display-mode 'dual-pane) t nil)))
+   ((equal detail 'pop-up-frames)
+      (and interactive-p ;; ref NOTE: BB_2018-03-12_001 below BB 2018-03-12
+           ;; I'm starting out rejecting this next test because I seem to
+           ;; successfully run emacs-w3m in frame modes, in emacs-nox where
+           ;; `window-system' is nil.
+           ;; (w3m-device-on-window-system-p) ;; from macro `w3m-pop-up-frame-p'
+        (if (not w3m-display-mode) w3m-pop-up-frames)
+         (if (or (equal w3m-display-mode 'frames)
+                 (equal w3m-display-mode 'tabbed-frames)) t nil)))
+   ((equal detail 'use-tab)
+      (if (not w3m-display-mode) w3m-use-tab)
+       (if (or (equal w3m-display-mode 'tabbed)
+               (equal w3m-display-mode 'tabbed-frames)) t nil))
+   (t nil)))
+
 (defcustom w3m-use-tab t
-  "Non-nil means make emacs-w3m a tab browser.
-It makes it possible to show all emacs-w3m buffers in a single window
-with the tabs line, and you can choose one by clicking a mouse on it.
-See also `w3m-use-tab-menubar'."
+  "Use emacs-w3m in \"Tabbed\" display mode.
+
+This variable is now DEPRECATED! Please use `w3m-display-mode'
+instead.
+
+When non-nil, emacs-w3m will make a reasonable effort to display
+all its buffers in a single window, which has a clickable tab bar
+along the top. See also `w3m-use-tab-menubar'."
+;; Deprecation notice 2018-03. Consider obsolescence 2020-03.
   :group 'w3m
   :type 'boolean)

@@ -1565,11 +1649,12 @@

 (defcustom w3m-use-tab-menubar t
   "Non-nil means use the TAB pull-down menu in the menubar.
-It makes it possible to show all emacs-w3m buffers in a single window,
-and you can choose one by clicking a mouse on it.  This feature
-requires that Emacs has been built to be able to display multilingual
-text in the menubar if you often visit web sites written in non-ascii
-text.  See also `w3m-use-tab'."
+It makes it possible to show all emacs-w3m buffers in a single
+window, and you can choose one by clicking a mouse on it. This
+feature requires that Emacs has been built to be able to display
+multilingual text in the menubar if you often visit web sites
+written in non-ascii text. See also `w3m-display-mode' and the
+deprecated variable `w3m-use-tab'."
   :group 'w3m
   :type 'boolean)

@@ -1634,22 +1719,54 @@
   :group 'w3m
   :type 'boolean)

+
 (defcustom w3m-pop-up-windows t
-  "Non-nil means split the windows when a new emacs-w3m session is created.
-This variable is similar to `pop-up-windows' and quite overridden by
-`w3m-pop-up-frames' as if `pop-up-frames' influences.  Furthermore, if
-`w3m-use-tab' is non-nil or there is the buffers selection window (for
-the `w3m-select-buffer' feature), this variable is ignored when
-creating the second or more emacs-w3m session."
+  "Use emacs-w3m in dual-pane mode.
+
+This variable is now DEPRECATED! Please use `w3m-display-mode'
+instead.
+
+When non-nil, once more than one emacs-w3m buffer exists, a
+reasonable attempt is made to present emacs-w3m in two windows on
+the same frame. Any action to open a new emacs-w3m buffer, such
+as `w3m-goto-url-new-session' or `w3m-search-new-session'
+displays the new buffer in the unfocused pane, and transfers
+focus there.
+
+Note that this display mode setting is of the lowest priority, in
+that if either `w3m-pop-up-frames' or `w3m-use-tab' is non-nil,
+this setting will be ignored."
+;; Deprecation notice 2018-03. Consider obsolescence 2020-03.
   :group 'w3m
   :type 'boolean)

+
 (defcustom w3m-pop-up-frames nil
-  "Non-nil means pop to a new frame up for an emacs-w3m session.
-This variable is similar to `pop-up-frames' and does override
-`w3m-pop-up-windows'.  If `w3m-use-tab' is non-nil or there is the
-buffers selection window (for the `w3m-select-buffer' feature), this
-variable is ignored when creating the second or more emacs-w3m session."
+  "Use emacs-w3m in a dedicated frame mode.
+
+This variable is now DEPRECATED! Please use `w3m-display-mode'
+instead.
+
+When non-nil, emacs-w3m makes a reasonable attempt to display its
+buffers in dedicated frames, although you can manually subvert
+that if you insist.
+
+There are actually two types of dedicated frame display modes,
+DEDICATED-FRAMES and TABBED-DEDICATED-FRAMES.
+
+DEDICATED-FRAMES mode creates a new single-window frame for each
+new emacs-w3m buffer you create.
+
+TABBED-DEDICATED-FRAMES mode opens new emacs-w3m buffers in the
+same window of the frame from which it was spawned, and those
+buffers are not easily visible to emacs-w3m buffers associated
+with other frames. The window includes a clickable tab bar along
+the top. To enable this variant display mode under the old
+scheme, you need to set this variable and also variable
+`w3m-use-tab'. When using this display mode, you can still
+manually create multiple emacs-w3m frames by using the basic
+command `w3m'."
+;; Deprecation notice 2018-03. Consider obsolescence 2020-03.
   :group 'w3m
   :type 'boolean)

@@ -7963,19 +8080,23 @@

 (defun w3m-copy-buffer (&optional buffer newname just-copy empty background
 				  last)
-  "Create a copy of the BUFFER where emacs-w3m is running.
-Return a new buffer.
+  "Copy an emacs-w3m BUFFER, and return the new buffer.
+
+If BUFFER is nil, the current buffer is assumed. If NEWNAME is
+nil, it defaults to the name of the current buffer.

-If BUFFER is nil, the current buffer is assumed.  If NEWNAME is nil,
-it defaults to the name of the current buffer.  If JUST-COPY is nil,
-this function makes the new buffer the current buffer and pops up as
-a new window or a new frame according to `w3m-pop-up-windows' and
-`w3m-pop-up-frames' (which see), otherwise creates just BUFFER's copy.
-If EMPTY is nil, a page of the same url will be re-rendered in the new
-buffer, otherwise an empty buffer is created.  If BACKGROUND is non-nil,
-you will not leave the current buffer.  If LAST is non-nil, the new
-buffer will be made the last in order of the w3m buffers, otherwise it
-will be made the next of the current buffer.
+If JUST-COPY is nil, then after performing the copy, the new
+buffer becomes the current buffer and pops up as a new window or
+a new frame depending upon the state of `w3m-display-mode' (or if
+that variable is unset, according to the deprecated variables
+`w3m-pop-up-windows' and `w3m-pop-up-frames').
+
+If EMPTY is nil, a page of the same url will be re-rendered in
+the new buffer, otherwise an empty buffer is created. If
+BACKGROUND is non-nil, you will not leave the current buffer. If
+LAST is non-nil, the new buffer will be made the last in order of
+the w3m buffers, otherwise it will be made the next of the
+current buffer.

 Note that this function should be called on the window displaying the
 original buffer BUFFER even if JUST-COPY is non-nil in order to render
@@ -8077,10 +8198,11 @@

 (defun w3m-delete-buffer (&optional force)
   "Delete the current emacs-w3m buffer and switch to the previous one.
-If there is the sole emacs-w3m buffer, it is assumed to be called for
-terminating the emacs-w3m session; the prefix argument FORCE will be
-passed to the `w3m-quit' function (which see).  When `w3m-use-tab' is
-non-nil, it returns to the buffer that launches this buffer."
+If there is only one emacs-w3m buffer, assume intent to terminate
+the emacs-w3m session; the prefix argument FORCE will be passed
+to the `w3m-quit' function. When in a tabbed display mode (see
+`w3m-display-mode' or the deprecated variable `w3m-use-tab'),
+focus is returned to the buffer that launched this buffer."
   (interactive "P")
   ;; Bind `w3m-fb-mode' to nil so that this function might not call
   ;; `w3m-quit' when there is only one buffer belonging to the selected
@@ -8092,7 +8214,7 @@
     (if (= 1 num)
 	(w3m-quit force)
       (setq cur (current-buffer))
-      (if (w3m-use-tab-p)
+      (if (w3m--display-mode 'use-tab)
 	  (progn
 	    (select-window (or (get-buffer-window cur t) (selected-window)))
 	    (w3m-next-buffer -1 w3m-previous-session-buffer))
@@ -9477,8 +9599,11 @@

 (defun w3m-doc-view (url)
   "View PDF/PostScript/DVI files using `doc-view-mode'.
-`w3m-pop-up-windows' and `w3m-pop-up-frames' control how the document
-window turns up."
+
+Where the document is displayed depends upon the state of
+`w3m-display-mode' (or if that variable is unset, according to
+the deprecated variables `w3m-pop-up-windows' and
+`w3m-pop-up-frames')."
   (let* ((basename (file-name-nondirectory (w3m-url-strip-query url)))
 	 (regexp (concat "\\`" (regexp-quote basename) "\\(?:<[0-9]+>\\)?\\'"))
 	 (buffers (buffer-list))
@@ -9498,8 +9623,8 @@
 	      (unless buffer
 		(setq buffer (generate-new-buffer basename)
 		      data (buffer-string)))
-	      (let ((pop-up-windows w3m-pop-up-windows)
-		    (pop-up-frames w3m-pop-up-frames))
+	      (let ((pop-up-windows (w3m--display-mode 'pop-up-windows))
+		    (pop-up-frames  (w3m--display-mode 'pop-up-frames)))
 		(pop-to-buffer buffer)))
       (set-buffer-multibyte nil)
       (insert data)
@@ -9514,10 +9639,10 @@
   "Quit the `doc-view-mode' window that emacs-w3m launches.
 With the prefix argument KILL, kill the buffer."
   (interactive "P")
-  (cond (w3m-pop-up-frames
+  (cond ((w3m--display-mode 'pop-up-frames)
 	 (when (prog1 (one-window-p t) (quit-window kill))
 	   (delete-frame (selected-frame))))
-	(w3m-pop-up-windows
+	((w3m--display-mode 'pop-up-windows)
 	 (if (fboundp 'quit-window)
 	     (quit-window kill)
 	   (if kill
@@ -10325,36 +10450,32 @@
 (defun w3m (&optional url new-session interactive-p)
   "Visit World Wide Web pages using the external w3m command.

-When you invoke this command interactively for the first time, it will
-visit a page which is pointed to by a string like url around the
-cursor position or the home page specified by the `w3m-home-page'
-variable, but you will be prompted for a URL if `w3m-quick-start' is
-nil (default t) or `w3m-home-page' is nil.
-
-The variables `w3m-pop-up-windows' and `w3m-pop-up-frames' control
-whether this command should pop to a window or a frame up for the
-session.
-
-When an emacs-w3m session has already been opened, this command will
-pop to an existing window or frame, but if `w3m-quick-start' is nil,
-(default t), you will be prompted for a URL (which defaults to `popup'
-meaning to pop to an existing emacs-w3m buffer up).
-
-In addition, if the prefix argument is given or you enter the empty
-string for the prompt, this command will visit a url at the point, or
-the home page the `w3m-home-page' variable specifies, or the \"about:\"
-page.
+If no emacs-w3m session already exists: If POINT is at a url
+string, visit that. Otherwise, if `w3m-home-page' is defined,
+visit that. Otherwise, present a blank page. This behavior can be
+over-ridden by setting variable `w3m-quick-start' to nil, in
+which case you will always be prompted for a URL.
+
+If an emacs-w3m session already exists: Pop to one of its windows
+or frames. You can over-ride this behavior by setting
+`w3m-quick-start' to nil, in order to always be prompted for a
+URL.
+
+In you have set `w3m-quick-start' to nil, but wish to over-ride
+default behavior from the command line, either run this command
+with a prefix argument or enter the empty string for the prompt.
+In such cases, this command will visit a url at the point or,
+lacking that, the URL set in variable `w3m-home-page' or, lacking
+that, the \"about:\" page.
+
+Any of five display styles are possible. See `w3m-display-mode'
+for a description of those options.

 You can also run this command in the batch mode as follows:

   emacs -f w3m http://emacs-w3m.namazu.org/ &

-In that case, or if this command is called non-interactively, the
-variables `w3m-pop-up-windows' and `w3m-pop-up-frames' will be ignored
-\(treated as nil) and it will run emacs-w3m at the current (or the
-initial) window.
-
-If the optional NEW-SESSION is non-nil, this function makes a new
+If the optional NEW-SESSION is non-nil, this function creates a new
 emacs-w3m buffer.  Besides that, it also makes a new emacs-w3m buffer
 if `w3m-make-new-session' is non-nil and a user specifies a url string.

@@ -10388,8 +10509,18 @@
   (let ((nofetch (eq url 'popup))
 	(alived (w3m-alive-p))
 	(buffer (unless new-session (w3m-alive-p t)))
-	(w3m-pop-up-frames (and interactive-p w3m-pop-up-frames))
-	(w3m-pop-up-windows (and interactive-p w3m-pop-up-windows)))
+        ;; BEGIN_NOTE: BB_2018-03-12_001 As this is the main emacs-w3m
+        ;; function, it seems that these two assignments carry through
+        ;; the entire project, thus with the advent of
+        ;; `w3m-display-mode', the check for interactive-p should be
+        ;; made in function `w3m--display-mode', and these two lines
+        ;; should be commented out. universal one, and thus should
+	;;
+        ;; (w3m-pop-up-frames (and interactive-p (w3m--display-mode 'pop-up-frames)))
+	;; (w3m-pop-up-windows (and interactive-p (w3m--display-mode 'pop-up-windows)))
+        ;;
+        ;; Remove this note once `w3m-display-mode' has been fully tested.
+        ;; END_NOTE: BB_2018-03-12_001
     (unless (and (stringp url)
 		 (> (length url) 0))
       (if buffer
@@ -10426,9 +10557,7 @@
 (defun w3m-browse-url (url &optional new-session)
   "Ask emacs-w3m to browse URL.
 NEW-SESSION specifies whether to create a new emacs-w3m session.  URL
-defaults to the string looking like a url around the cursor position.
-Pop to a window or a frame up according to `w3m-pop-up-windows' and
-`w3m-pop-up-frames'."
+defaults to the string looking like a url around the cursor position."
   (interactive (progn
 		 (require 'browse-url)
 		 (browse-url-interactive-arg "Emacs-w3m URL: ")))
@@ -10976,9 +11105,11 @@
        (or w3m-fill-column -1))))

 (defun w3m-select-buffer (&optional toggle nomsg)
-  "Pop to the emacs-w3m buffers selection window up.
-It provides the feature for switching emacs-w3m buffers using the
-buffer list.  The following command keys are available:
+  "Pop-up an emacs-w3m buffers selection window.
+
+Allows convenient switching between emacs-w3m buffers.
+
+The following command keys are available:

 \\{w3m-select-buffer-mode-map}"
   (interactive "P")
@@ -11012,7 +11143,7 @@
   (when (get-buffer-window w3m-select-buffer-name)
     (save-selected-window
       (w3m-select-buffer nil 'update)))
-  (when w3m-use-tab
+  (when (w3m--display-mode 'use-tab)
     (w3m-force-window-update)))

 (defun w3m-select-buffer-generate-contents (current-buffer)
@@ -11283,8 +11414,12 @@
   :type 'boolean)

 (defcustom w3m-use-header-line-title nil
-  "Non-nil means display the current title at the header line.
-This variable is effective only when `w3m-use-tab' is nil."
+  "Display the current URI title on the header line.
+
+This variable is ignored when using a tabbed display mode,
+because in such cases the header line is used for the tab
+list. (see `w3m-display-mode' or the deprecated variable
+`w3m-use-tab')."
   :group 'w3m
   :type 'boolean)

@@ -11332,7 +11467,7 @@
 (defun w3m-header-line-insert ()
   "Put the header line into the current buffer."
   (when (and (or (featurep 'xemacs)
-		 (w3m-use-tab-p))
+		 (w3m--display-mode 'use-tab))
 	     w3m-use-header-line
 	     w3m-current-url
 	     (eq 'w3m-mode major-mode))
@@ -11389,7 +11524,7 @@

 (defun w3m-safe-view-this-url (&optional force)
   "View the URL of the link under point.
-This command is quite similar to `w3m-view-this-url' except for the
+This command is quite similar to `w3m-view-this-url' except for
 four differences: [1]don't handle forms, [2]don't consider URL-like
 string under the cursor, [3]compare URL with `w3m-safe-url-regexp'
 first to check whether it is safe, and [4]the arguments list differs;
@@ -11401,7 +11536,7 @@
 non-nil and a user invokes this command in a buffer not being running
 the `w3m-mode', otherwise use an existing emacs-w3m buffer."
   (interactive "P")
-  (let ((w3m-pop-up-windows nil)
+  (let ((w3m-display-mode (if (w3m--display-mode 'pop-up-windows) 'plain w3m-display-mode))
 	(url (w3m-url-valid (w3m-anchor)))
 	safe-regexp)
     (cond