w3m-pop-up-windows and w3m-use-tab

[Boruch Baum <boruch_baum@xxxxxxx>]

One of the parts of the documentation that I found very confusing is
everything surrounding variables `w3m-use-tab', `w3m-pop-up-windows', and
`w3m-pop-up-frames'. I finally spent some time today on it, and if my
understanding is correct, would like to propose some minor terminology,
cosmetic coding, and documentation changes.

Here goes:

==BEGIN==
There exist five display modes in emacs-w3m, which I'll call plain, tabbed,
dual-pane, dedicated-frames, and tabbed-dedicated-frames.


1. Plain

  (setq w3m-use-tab         nil
        w3m-pop-up-windows  nil
        w3m-pop-up-frames   nil)

  Each emacs-w3m buffer exists on its own and can appear in any window in
  any frame. There is no tab bar.


2. Tabbed
  (setq w3m-use-tab         t
        w3m-pop-up-windows  nil
        w3m-pop-up-frames   nil)

  A reasonable attempt is made to keep only one window displaying emacs-w3m
  buffers. That window has a tab bar along the top. Users can manually
  subvert this by explicitly opening an emacs-w3m buffer in any number of
  other windows.


3. Dual-pane
  (setq w3m-use-tab         nil
        w3m-pop-up-windows  t
        w3m-pop-up-frames   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' ("G" by
  default) or `w3m-search-new-session' ("S" by default) displays the new
  buffer in the unfocused pane, and transfers focus there.


4. Dedicated-frames
  (setq w3m-use-tab         nil
        w3m-pop-up-windows  nil  # Really, don't care, ie. ignored
        w3m-pop-up-frames   t)

  Each new emacs-w3m buffer is opened in a new single-window frame.


5. Tabbed-dedicated-frames
  (setq w3m-use-tab         t
        w3m-pop-up-windows  nil  # Really, don't care, ie. ignored
        w3m-pop-up-frames   t)

  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 tab bar along the
  top.
==END==

If the above is correct, 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.

If the project needs or insists on retaining the status quo, the docstrings
for the variables could be clearer. For example, the docstring for
`w3m-pop-up-windows' could be something like:

  "Enable dual-pane browsing (not available with tabbed or framed interfaces).

  When non-nil, actions that create a new emacs-w3m buffer will display
  that new buffer in a second window and transfer focus there.

  This is one of five emacs-w3m display modes, controlled by a combination
  of three variables....

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