Add documentation for horizontal scroll bars and fix some minor issues.

* buffer.c (scroll_bar_width, scroll_bar_height): Fix
doc-strings.
* window.c (Fset_window_scroll_bars): Fix doc-string.
(Fwindow_scroll_bars): Have it return what the doc-string says.

* window.el (window-full-height-p): Make it behave correctly for
minibuffer window.
(window-current-scroll-bars): Fix code.
(fit-frame-to-buffer): Use window-scroll-bar-height instead of
window-scroll-bars.
* frame.el (frame-current-scroll-bars): Fix doc-string.
* scroll-bar.el (toggle-horizontal-scroll-bar): New command.

* frames.texi (Scroll Bars): Describe use of horizontal scroll
bars.

* display.texi (Scroll Bars): Add description of horizontal scroll
bars and associated functions.
* frames.texi (Layout Parameters): Add horizontal scroll bar
entries.  Remove paragraph on "combined fringe widths".
* windows.texi (Window Sizes): Describe affects of horizontal
scroll bars on window layout and sizes.  Fix description of
window-full-height-p.
(Resizing Windows): Mention horizontal scroll bar.

5 files changed, 188 insertions, 118 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index f3fce93dd53..510f9e983c3 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,14 @@
+2014-10-04  Martin Rudalics  <rudalics@gmx.at>
+
+        * display.texi (Scroll Bars): Add description of horizontal scroll
+        bars and associated functions.
+        * frames.texi (Layout Parameters): Add horizontal scroll bar
+        entries.  Remove paragraph on "combined fringe widths".
+        * windows.texi (Window Sizes): Describe affects of horizontal
+        scroll bars on window layout and sizes.  Fix description of
+        window-full-height-p.
+        (Resizing Windows): Mention horizontal scroll bar.
+
 2014-10-04  Glenn Morris  <rgm@gnu.org>
 
         * commands.texi (Generic Commands): Copyedits.
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 46be5ecf3f0..7248aa32a30 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -23,7 +23,7 @@ that Emacs presents to the user.
 * Faces::               A face defines a graphics style for text characters:
                           font, colors, etc.
 * Fringes::             Controlling window fringes.
-* Scroll Bars::         Controlling vertical scroll bars.
+* Scroll Bars::         Controlling scroll bars.
 * Window Dividers::     Separating windows visually.
 * Display Property::    Enabling special display features.
 * Images::              Displaying images in Emacs buffers.
@@ -3866,102 +3866,164 @@ arrow position.  If either property is not set, the default
 @code{overlay-arrow-string} or @code{overlay-arrow} fringe indicator
 is used.
 
+
 @node Scroll Bars
 @section Scroll Bars
 @cindex scroll bars
 
 Normally the frame parameter @code{vertical-scroll-bars} controls
-whether the windows in the frame have vertical scroll bars, and
-whether they are on the left or right.  The frame parameter
-@code{scroll-bar-width} specifies how wide they are (@code{nil}
-meaning the default).  @xref{Layout Parameters}.
+whether the windows in the frame have vertical scroll bars, and whether
+they are on the left or right.  The frame parameter
+@code{scroll-bar-width} specifies how wide they are (@code{nil} meaning
+the default).
+
+   The frame parameter @code{horizontal-scroll-bars} controls whether
+the windows in the frame have horizontal scroll bars.  The frame
+parameter @code{scroll-bar-height} specifies how high they are
+(@code{nil} meaning the default).  @xref{Layout Parameters}.
+
+@vindex horizontal-scroll-bars-available-p
+   Horizontal scroll bars are not available on all platforms.  The
+function @code{horizontal-scroll-bars-available-p} which takes no
+argument returns non-@code{nil} if they are available on your system.
+
+   The following three functions take as argument a live frame which
+defaults to the selected one.
 
 @defun frame-current-scroll-bars &optional frame
-This function reports the scroll bar type settings for frame
-@var{frame}.  The value is a cons cell
-@code{(@var{vertical-type} .@: @var{horizontal-type})}, where
-@var{vertical-type} is either @code{left}, @code{right}, or @code{nil}
-(which means no scroll bar.)  @var{horizontal-type} is meant to
-specify the horizontal scroll bar type, but since they are not
-implemented, it is always @code{nil}.
-@end defun
-
-@vindex vertical-scroll-bar
-  You can enable or disable scroll bars for a particular buffer,
-by setting the variable @code{vertical-scroll-bar}.  This variable
-automatically becomes buffer-local when set.  The possible values are
-@code{left}, @code{right}, @code{t}, which means to use the
-frame's default, and @code{nil} for no scroll bar.
+This function reports the scroll bar types for frame @var{frame}.  The
+value is a cons cell @code{(@var{vertical-type} .@:
+@var{horizontal-type})}, where @var{vertical-type} is either
+@code{left}, @code{right}, or @code{nil} (which means no vertical scroll
+bar.)  @var{horizontal-type} is either @code{bottom} or @code{nil}
+(which means no horizontal scroll bar).
+@end defun
 
-  You can also control this for individual windows.  Call the function
-@code{set-window-scroll-bars} to specify what to do for a specific window:
+@defun frame-scroll-bar-width &optional Lisp_Object &optional frame
+This function returns the width of vertical scroll bars of @var{frame}
+in pixels.
+@end defun
 
-@defun set-window-scroll-bars window width &optional vertical-type horizontal-type
-This function sets the width and type of scroll bars for window
-@var{window}.
+@defun frame-scroll-bar-height &optional Lisp_Object &optional frame
+This function returns the height of horizontal scroll bars of
+@var{frame} in pixels.
+@end defun
 
-@var{width} specifies the scroll bar width in pixels (@code{nil} means
-use the width specified for the frame).  @var{vertical-type} specifies
-whether to have a vertical scroll bar and, if so, where.  The possible
-values are @code{left}, @code{right} and @code{nil}, just like the
-values of the @code{vertical-scroll-bars} frame parameter.
+You can override the frame specific settings for individual windows by
+using the following function:
 
-The argument @var{horizontal-type} is meant to specify whether and
-where to have horizontal scroll bars, but since they are not
-implemented, it has no effect.  If @var{window} is @code{nil}, the
-selected window is used.
+@defun set-window-scroll-bars window &optional width vertical-type height horizontal-type
+This function sets the width and/or height and the types of scroll bars
+for window @var{window}.
+
+@var{width} specifies the width of the vertical scroll bar in pixels
+(@code{nil} means use the width specified for the frame).
+@var{vertical-type} specifies whether to have a vertical scroll bar and,
+if so, where.  The possible values are @code{left}, @code{right},
+@code{t}, which means to use the frame's default, and @code{nil} for no
+vertical scroll bar.
+
+@var{height} specifies the height of the horizontal scroll bar in pixels
+(@code{nil} means use the height specified for the frame).
+@var{horizontal-type} specifies whether to have a horizontal scroll bar.
+The possible values are @code{bottom}, @code{t}, which means to use the
+frame's default, and @code{nil} for no horizontal scroll bar.
+
+If @var{window} is @code{nil}, the selected window is used.
 @end defun
 
+The following four functions take as argument a live window which
+defaults to the selected one.
+
 @defun window-scroll-bars &optional window
-Report the width and type of scroll bars specified for @var{window}.
-If @var{window} is omitted or @code{nil}, the selected window is used.
-The value is a list of the form @code{(@var{width}
-@var{cols} @var{vertical-type} @var{horizontal-type})}.  The value
-@var{width} is the value that was specified for the width (which may
-be @code{nil}); @var{cols} is the number of columns that the scroll
-bar actually occupies.
+This function returns a list of the form @code{(@var{width}
+@var{columns} @var{vertical-type} @var{height} @var{lines}
+@var{horizontal-type})}.
 
-@var{horizontal-type} is not actually meaningful.
+The value @var{width} is the value that was specified for the width of
+the vertical scroll bar (which may be @code{nil}); @var{columns} is the
+(possibly rounded) number of columns that the vertical scroll bar
+actually occupies.
+
+The value @var{height} is the value that was specified for the height of
+the horizontal scroll bar (which may be @code{nil}); @var{lines} is the
+(possibly rounded) number of lines that the horizontally scroll bar
+actually occupies.
+@end defun
+
+@defun window-current-scroll-bars &optional window
+This function reports the scroll bar type for window @var{window}.  The
+value is a cons cell @code{(@var{vertical-type} .@:
+@var{horizontal-type})}.  Unlike @code{window-scroll-bars}, this reports
+the scroll bar type actually used, once frame defaults and
+@code{scroll-bar-mode} are taken into account.
 @end defun
 
 @defun window-scroll-bar-width &optional window
 This function returns the width in pixels of @var{window}'s vertical
-scrollbar.  @var{window} must be a live window, and defaults to the
-selected window.
+scrollbar.
+@end defun
+
+@defun window-scroll-bar-height &optional window
+This function returns the height in pixels of @var{window}'s horizontal
+scrollbar.
 @end defun
 
 If you don't specify these values for a window with
 @code{set-window-scroll-bars}, the buffer-local variables
-@code{scroll-bar-mode} and @code{scroll-bar-width} in the buffer being
-displayed control the window's vertical scroll bars.  The function
+@code{vertical-scroll-bar}, @code{horizontal-scroll-bar},
+@code{scroll-bar-width} and @code{scroll-bar-height} in the buffer being
+displayed control the window's scroll bars.  The function
 @code{set-window-buffer} examines these variables.  If you change them
-in a buffer that is already visible in a window, you can make the
-window take note of the new values by calling @code{set-window-buffer}
+in a buffer that is already visible in a window, you can make the window
+take note of the new values by calling @code{set-window-buffer}
 specifying the same buffer that is already displayed.
 
-@defopt scroll-bar-mode
-This variable, always local in all buffers, controls whether and where
-to put scroll bars in windows displaying the buffer.  The possible values
-are @code{nil} for no scroll bar, @code{left} to put a scroll bar on
-the left, and @code{right} to put a scroll bar on the right.
-@end defopt
+You can control the appearance of scroll bars for a particular buffer by
+setting the following variables which automatically become buffer-local
+when set.
 
-@defun window-current-scroll-bars &optional window
-This function reports the scroll bar type for window @var{window}.
-If @var{window} is omitted or @code{nil}, the selected window is used.
-The value is a cons cell
-@code{(@var{vertical-type} .@: @var{horizontal-type})}.  Unlike
-@code{window-scroll-bars}, this reports the scroll bar type actually
-used, once frame defaults and @code{scroll-bar-mode} are taken into
-account.
-@end defun
+@defvar vertical-scroll-bar
+This variable specifies the location of the vertical scroll bar.  The
+possible values are @code{left}, @code{right}, @code{t}, which means to
+use the frame's default, and @code{nil} for no scroll bar.
+@end defvar
+
+@defvar horizontal-scroll-bar
+This variable specifies the location of the horizontal scroll bar.  The
+possible values are @code{bottom}, @code{t}, which means to use the
+frame's default, and @code{nil} for no scroll bar.
+@end defvar
 
 @defvar scroll-bar-width
-This variable, always local in all buffers, specifies the width of the
-buffer's scroll bars, measured in pixels.  A value of @code{nil} means
-to use the value specified by the frame.
+This variable specifies the width of the buffer's vertical scroll bars,
+measured in pixels.  A value of @code{nil} means to use the value
+specified by the frame.
 @end defvar
 
+@defvar scroll-bar-height
+This variable specifies the height of the buffer's horizontal scroll
+bar, measured in pixels.  A value of @code{nil} means to use the value
+specified by the frame.
+@end defvar
+
+Finally you can toggle the display of scroll bars on all frames by
+customizing the variables @code{scroll-bar-mode} and
+@code{horizontal-scroll-bar-mode}.
+
+@defopt scroll-bar-mode
+This variable controls whether and where to put vertical scroll bars in
+all frames.  The possible values are @code{nil} for no scroll bars,
+@code{left} to put scroll bars on the left and @code{right} to put
+scroll bars on the right.
+@end defopt
+
+@defopt horizontal-scroll-bar-mode
+This variable controls whether to display horizontal scroll bars on all
+frames.
+@end defopt
+
+
 @node Window Dividers
 @section Window Dividers
 @cindex window dividers
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index bb2e4638396..937345f21e4 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -1343,7 +1343,7 @@ Emacs Display
 * Faces::                   A face defines a graphics style
                               for text characters: font, colors, etc.
 * Fringes::                 Controlling window fringes.
-* Scroll Bars::             Controlling vertical scroll bars.
+* Scroll Bars::             Controlling scroll bars.
 * Window Dividers::         Separating windows visually.
 * Display Property::        Enabling special display features.
 * Images::                  Displaying images in Emacs buffers.
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index c8e0fff6cd0..464c5fccc4f 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -709,19 +709,21 @@ Whether the frame has scroll bars for vertical scrolling, and which side
 of the frame they should be on.  The possible values are @code{left},
 @code{right}, and @code{nil} for no scroll bars.
 
-@ignore
 @vindex horizontal-scroll-bars, a frame parameter
 @item horizontal-scroll-bars
-Whether the frame has scroll bars for horizontal scrolling
-(non-@code{nil} means yes).  Horizontal scroll bars are not currently
-implemented.
-@end ignore
+Whether the frame has scroll bars for horizontal scrolling (@code{t} and
+@code{bottom} mean yes, @code{nil} means no).
 
 @vindex scroll-bar-width, a frame parameter
 @item scroll-bar-width
 The width of vertical scroll bars, in pixels, or @code{nil} meaning to
 use the default width.
 
+@vindex scroll-bar-height, a frame parameter
+@item scroll-bar-height
+The height of horizontal scroll bars, in pixels, or @code{nil} meaning
+to use the default height.
+
 @vindex left-fringe, a frame parameter
 @vindex right-fringe, a frame parameter
 @item left-fringe
@@ -735,14 +737,6 @@ these two frame parameters, the return value is always an integer.
 When using @code{set-frame-parameter}, passing a @code{nil} value
 imposes an actual default value of 8 pixels.
 
-The combined fringe widths must add up to an integral number of
-columns, so the actual default fringe widths for the frame, as
-reported by @code{frame-parameter}, may be larger than what you
-specify.  Any extra width is distributed evenly between the left and
-right fringe.  However, you can force one fringe or the other to a
-precise width by specifying that width as a negative integer.  If both
-widths are negative, only the left fringe gets the specified width.
-
 @vindex right-divider-width, a frame parameter
 @item right-divider-width
 The width (thickness) reserved for the right divider (@pxref{Window
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index f5122a39f8c..5060fef804f 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -394,13 +394,14 @@ internal window).  The @var{edges} element is a list @code{(@var{left}
 @group
         ____________________________________________
        |______________ Header Line ______________|RD| ^
-     ^ |LS|LF|LM|                       |RM|RF|RS|  | |
+     ^ |LS|LM|LF|                       |RF|RM|RS|  | |
      | |  |  |  |                       |  |  |  |  | |
 Window |  |  |  |       Text Area       |  |  |  |  | Window
 Body | |  |  |  |     (Window Body)     |  |  |  |  | Total
 Height |  |  |  |                       |  |  |  |  | Height
      | |  |  |  |<- Window Body Width ->|  |  |  |  | |
      v |__|__|__|_______________________|__|__|__|  | |
+       |_________ Horizontal Scroll Bar _________|  | |
        |_______________ Mode Line _______________|__| |
        |_____________ Bottom Divider _______________| v
         <---------- Window Total Width ------------>
@@ -414,15 +415,15 @@ Height |  |  |  |                       |  |  |  |  | Height
   At the center of the window is the @dfn{text area}, or @dfn{body},
 where the buffer text is displayed.  The text area can be surrounded by
 a series of optional areas.  On the left and right, from innermost to
-outermost, these are the left and right margins, denoted by LM and RM in
-the schematic (@pxref{Display Margins}); the left and right fringes,
-denoted by LF and RF (@pxref{Fringes}); the left or right scroll bar,
-only one of which is present at any time, denoted by LS and RS
-(@pxref{Scroll Bars}); and the right divider, denoted by RD
+outermost, these are the left and right fringes, denoted by LF and RF
+(@pxref{Fringes}); the left and right margins, denoted by LM and RM in
+the schematic (@pxref{Display Margins}); the left or right vertical
+scroll bar, only one of which is present at any time, denoted by LS and
+RS (@pxref{Scroll Bars}); and the right divider, denoted by RD
 (@pxref{Window Dividers}).  At the top of the window is the header line
-(@pxref{Header Lines}); at the bottom of the window is the mode line
-(@pxref{Mode Line Format}) followed by the bottom divider (@pxref{Window
-Dividers}).
+(@pxref{Header Lines}).  At the bottom of the window are the horizontal
+scroll bar (@pxref{Scroll Bars}); the mode line (@pxref{Mode Line
+Format}); and the bottom divider (@pxref{Window Dividers}).
 
   Emacs provides miscellaneous functions for finding the height and
 width of a window.  The return value of many of these functions can be
@@ -439,11 +440,8 @@ displayed within it.
 @cindex height of a window
 @cindex total height of a window
   The @dfn{total height} of a window is the number of lines comprising
-the window's body, the header line, the mode line and the bottom divider
-(if any).  Note that the height of a frame is not the same as the height
-of its root window (@pxref{Windows and Frames}), since a frame may also
-contain an echo area, a menu bar, and a tool bar (@pxref{Size and
-Position}).
+the window's body, the header line, the horizontal scroll bar, the mode
+line and the bottom divider (if any).
 
 @defun window-total-height &optional window round
 This function returns the total height, in lines, of the window
@@ -457,8 +455,8 @@ rounded internally.  This is done in a way such that, if the window is a
 parent window, the sum of the total heights of all its child windows
 internally equals the total height of their parent.  This means that
 although two windows have the same pixel height, their internal total
-heights may differ by one line.  This means also, that if this window is
-vertically combined and has a right sibling, the topmost row of that
+heights may differ by one line.  This means also, that if window is
+vertically combined and has a next sibling, the topmost row of that
 sibling can be calculated as the sum of this window's topmost row and
 total height (@pxref{Coordinates and Windows})
 
@@ -490,11 +488,10 @@ window, the sum of the total widths of all its children internally
 equals the total width of their parent.  This means that although two
 windows have the same pixel width, their internal total widths may
 differ by one column.  This means also, that if this window is
-horizontally combined and has a right sibling, the leftmost column of
+horizontally combined and has a next sibling, the leftmost column of
 that sibling can be calculated as the sum of this window's leftmost
-column and total width (@pxref{Coordinates and Windows}).  The
-optional argument @var{round} behaves as it does for
-@code{window-total-height}.
+column and total width (@pxref{Coordinates and Windows}).  The optional
+argument @var{round} behaves as it does for @code{window-total-height}.
 @end defun
 
 @defun window-total-size &optional window horizontal round
@@ -517,9 +514,10 @@ window in units of pixels.
 This function returns the total height of window @var{window} in pixels.
 @var{window} must be a valid window and defaults to the selected one.
 
-The return value includes mode and header line and a bottom divider, if
-any.  If @var{window} is an internal window, its pixel height is the
-pixel height of the screen areas spanned by its children.
+The return value includes mode and header line, a horizontal scroll bar
+and a bottom divider, if any.  If @var{window} is an internal window,
+its pixel height is the pixel height of the screen areas spanned by its
+children.
 @end defun
 
 @cindex window pixel height
@@ -542,10 +540,12 @@ the screen areas spanned by its children.
 window has any adjacent windows.
 
 @defun window-full-height-p &optional window
-This function returns non-@code{nil} if @var{window} has no other
-window above or below it in its frame, i.e., its total height equals
-the total height of the root window on that frame.  If @var{window} is
-omitted or @code{nil}, it defaults to the selected window.
+This function returns non-@code{nil} if @var{window} has no other window
+above or below it in its frame.  More precisely, this means that the
+total height of @var{window} equals the total height of the root window
+on that frame.  The minibuffer window does not count in this regard.  If
+@var{window} is omitted or @code{nil}, it defaults to the selected
+window.
 @end defun
 
 @defun window-full-width-p &optional window
@@ -559,7 +559,8 @@ that of the root window on that frame.  If @var{window} is omitted or
 @cindex body height of a window
 @cindex window body width
 The @dfn{body height} of a window is the height of its text area, which
-does not include a mode or header line or a bottom divider.
+does not include a mode or header line, a horizontal scroll bar, or a
+bottom divider.
 
 @defun window-body-height &optional window pixelwise
 This function returns the height, in lines, of the body of window
@@ -646,7 +647,8 @@ size:
 @defopt window-min-height
 This option specifies the minimum total height, in lines, of any window.
 Its value has to accommodate at least one text line as well as a mode
-and header line and a bottom divider, if present.
+and header line, a horizontal scroll bar and a bottom divider, if
+present.
 @end defopt
 
 @defopt window-min-width
@@ -685,10 +687,11 @@ of @var{window}'s lines.
 
 The return value makes sure that all components of @var{window} remain
 fully visible if @var{window}'s size were actually set to it.  With
-@var{horizontal} @code{nil} it includes the mode and header line and the
-bottom divider.  With @var{horizontal} non-@code{nil} it includes the
-fringes, a scroll bar, and a right divider, if present.  It does not,
-however, include the space reserved for the margins.
+@var{horizontal} @code{nil} it includes the mode and header line, the
+horizontal scroll bar and the bottom divider.  With @var{horizontal}
+non-@code{nil} it includes the fringes, a scroll bar, and a right
+divider, if present.  It does not, however, include the space reserved
+for the margins.
 
 The optional argument @var{ignore}, if non-@code{nil}, means ignore
 restrictions imposed by fixed size windows, @code{window-min-height} or
@@ -740,11 +743,11 @@ Normally, the variables @code{window-min-height} and
 (@pxref{Window Sizes}).  However, if the optional argument @var{ignore}
 is non-@code{nil}, this function ignores @code{window-min-height} and
 @code{window-min-width}, as well as @code{window-size-fixed}.  Instead,
-it considers the minimum-height window to be one consisting of a header,
-a mode line and a bottom divider (if any), plus a text area one line
-tall; and a minimum-width window as one consisting of fringes, margins,
-a scroll bar and a right divider (if any), plus a text area two columns
-wide.
+it considers the minimum-height window to be one consisting of a header
+and a mode line, a horizontal scrollbar and a bottom divider (if any),
+plus a text area one line tall; and a minimum-width window as one
+consisting of fringes, margins, a scroll bar and a right divider (if
+any), plus a text area two columns wide.
 
 If the optional argument @var{pixelwise} is non-@code{nil},
 @var{delta} is interpreted as pixels.