[Emacs-diffs] trunk r116692: Add/update elisp texinfo for window-min-size and split-window.

[Martin Rudalics]

------------------------------------------------------------
revno: 116692
revision-id: address@hidden
parent: address@hidden
committer: martin rudalics <address@hidden>
branch nick: trunk
timestamp: Fri 2014-03-07 10:53:23 +0100
message:
  Add/update elisp texinfo for window-min-size and split-window.
  
  * windows.texi (Window Sizes): Describe `window-min-size'.
  (Splitting Windows): Update description of `split-window'.
modified:
  doc/lispref/ChangeLog          changelog-20091113204419-o5vbwnq5f7feedwu-6155
  doc/lispref/windows.texi       
windows.texi-20091113204419-o5vbwnq5f7feedwu-6224

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2014-03-06 13:41:58 +0000
+++ b/doc/lispref/ChangeLog     2014-03-07 09:53:23 +0000
@@ -1,3 +1,8 @@
+2014-03-07  Martin Rudalics  <address@hidden>
+
+       * windows.texi (Window Sizes): Describe `window-min-size'.
+       (Splitting Windows): Update description of `split-window'.
+
 2014-03-06  Martin Rudalics  <address@hidden>
 
        * frames.texi (Size and Position): Rewrite entries for

=== modified file 'doc/lispref/windows.texi'
--- a/doc/lispref/windows.texi  2014-03-06 13:41:58 +0000
+++ b/doc/lispref/windows.texi  2014-03-07 09:53:23 +0000
@@ -656,6 +656,36 @@
 @xref{Resizing Windows}.
 @end defvar
 
+The following function tells how small a specific window can get taking
+into account the sizes of its areas and the values of
address@hidden, @code{window-min-width} and
address@hidden
+
address@hidden window-min-size &optional window horizontal ignore pixelwise
+This function returns the minimum size of @var{window}.  @var{window}
+must be a valid window and defaults to the selected one.  The optional
+argument @var{horizontal} address@hidden means to return the minimum
+number of columns of @var{window}; otherwise return the minimum number
+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
address@hidden @code{nil} it includes the mode and header line and the
+bottom divider.  With @var{horizontal} address@hidden 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 address@hidden, means ignore
+restrictions imposed by fixed size windows, @code{window-min-height} or
address@hidden settings.  If @var{ignore} equals @code{safe},
+live windows may get as small as @code{window-safe-min-height} lines and
address@hidden columns.  If @var{ignore} is a window,
+ignore restrictions for that window only.  Any other address@hidden
+value means ignore all of the above restrictions for all windows.
+
+The optional argument @var{pixelwise} address@hidden means to return the
+minimum size of @var{window} counted in pixels.
address@hidden defun
 
 @node Resizing Windows
 @section Resizing Windows
@@ -718,7 +748,7 @@
 The optional argument @var{ignore} has the same meaning as for the
 function @code{window-resizable} above.
 
-If the optional argument @code{pixelwise} is address@hidden,
+If the optional argument @var{pixelwise} is address@hidden,
 @var{delta} will be interpreted as pixels.
 
 The choice of which window edges this function alters depends on the
@@ -879,7 +909,7 @@
 This section describes functions for creating a new window by
 @dfn{splitting} an existing one.
 
address@hidden split-window &optional window size side
address@hidden split-window &optional window size side pixelwise
 This function creates a new live window next to the window
 @var{window}.  If @var{window} is omitted or @code{nil}, it defaults
 to the selected window.  That window is ``split'', and reduced in
@@ -894,15 +924,25 @@
 window is given @address@hidden lines (or columns).
 
 If @var{size} is @code{nil}, this function obeys the variables
address@hidden and @code{window-min-width}.  @xref{Change
-Window,,Deleting and Rearranging Windows, emacs, The GNU Emacs
-Manual}.  Thus, it signals an error if splitting would result in
-making a window smaller than those variables specify.  However, a
address@hidden and @code{window-min-width} (@pxref{Window
+Sizes}).  Thus, it signals an error if splitting would result in making
+a window smaller than those variables specify.  However, a
 address@hidden value for @var{size} causes those variables to be
-ignored; in that case, the smallest allowable window is considered to
-be one that has space for a text area one line tall and/or two columns
+ignored; in that case, the smallest allowable window is considered to be
+one that has space for a text area one line tall and/or two columns
 wide.
 
+Hence, if @var{size} is specified, it's the caller's responsibility to
+check whether the emanating windows are large enough to encompass all
+areas like a mode line or a scroll bar.  The function
address@hidden (@pxref{Window Sizes}) can be used to determine
+the minimum requirements of @var{window} in this regard.  Since the new
+window usually ``inherits'' areas like the mode line or the scroll bar
+from @var{window}, that function is also a good guess for the minimum
+size of the new window.  The caller should specify a smaller size only
+if it correspondingly removes an inherited area before the next
+redisplay.
+
 The optional third argument @var{side} determines the position of the
 new window relative to @var{window}.  If it is @code{nil} or
 @code{below}, the new window is placed below @var{window}.  If it is
@@ -914,6 +954,10 @@
 window is placed on the left of @var{window}.  In both these cases,
 @var{size} specifies a total window width, in columns.
 
+The optional fourth argument @var{pixelwise}, if address@hidden, means
+to interpret @var{size} in units of pixels, instead of lines and
+columns.
+
 If @var{window} is a live window, the new window inherits various
 properties from it, including margins and scroll bars.  If
 @var{window} is an internal window, the new window inherits the