bug#17065: 24.3.50; Revise line 5944 of window.el to use `window-width`, instead of `window-total-width`.

[martin rudalics <rudalics@gmx.at>]

 > (defun broken-example ()
 >    (interactive)
 >    (window--display-buffer
 >     ;; buffer
 >     (get-buffer-create "*test*")
 >     ;; window
 >     (split-window (selected-window) nil 'right)
 >     ;; type
 >     'window
 >     ;; alist
 >     '((window-width . 82))
 >     ;; dedicated
 >     t)
 >    (message "Window Width:  %s" (window-width (get-buffer-window "*test*"))) )

Conceptually, the `window-width' alist entry specifies the new total
width of the window, including fringes, scrollbars and vertical
dividers.  You mean that specifiying the number of text columns is more
intuitive?  I might agree, but unfortunately _all_ window resizing
functions intepret "width" in terms of the total width of a window.
Making an exception for this special case would only increase the
confusion.

The confusion has historical reasons and was not considered important,
likely so, because side-by-side windows are in use more frequently only
over the past years.  If, with emacs -Q, I do

(let ((window (split-window (selected-window) -20 'right)))
   (window-body-width window))

I get 16 text columns for the new window which is likely not what I
expected as someone using this function for the first time with an
explicit SIZE argument.

In any case, I will have to adjust some doc-strings and the Elisp
manual.  So far the only hint is the doc-string of `split-window-right'
which says

   Here, SIZE includes the width of the window's scroll bar; if there are
   no scroll bars, it includes the width of the divider column to the
   window's right, if any.

but I'm struggling with this issue ever since.

martin