windows.texi doc fix

windows.texi doc fix

[david.ponce]

Hi,

Following is a small patch to the Elisp manual that fixes the missing
documentation of the `preserve-before' optional argument of the
functions `enlarge-window' and `shrink-window'.  I just added the
description I found in doc strings.

David

2004-10-19  David Ponce  <david@dponce.com>

	* windows.texi (Resizing Windows): Document the `preserve-before'
	argument of the functions `enlarge-window' and `shrink-window'.

Index: windows.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/windows.texi,v
retrieving revision 1.75
diff -c -r1.75 windows.texi
*** windows.texi	24 Jul 2004 15:33:15 -0000	1.75
--- windows.texi	19 Oct 2004 09:57:54 -0000
***************
*** 1922,1928 ****
  window size.  Emacs does not permit overlapping windows or gaps between
  windows, so resizing one window affects other windows.
  
! @deffn Command enlarge-window size &optional horizontal
  This function makes the selected window @var{size} lines taller,
  stealing lines from neighboring windows.  It takes the lines from one
  window at a time until that window is used up, then takes from another.
--- 1922,1928 ----
  window size.  Emacs does not permit overlapping windows or gaps between
  windows, so resizing one window affects other windows.
  
! @deffn Command enlarge-window size &optional horizontal preserve-before
  This function makes the selected window @var{size} lines taller,
  stealing lines from neighboring windows.  It takes the lines from one
  window at a time until that window is used up, then takes from another.
***************
*** 1950,1955 ****
--- 1950,1959 ----
  than the minimum size (@code{window-min-height} and
  @code{window-min-width}), @code{enlarge-window} deletes the window.
  
+ Optional third arg @var{preserve-before}, if non-@code{nil}, means do
+ not change the size of the siblings above or to the left of the
+ selected window.  Only siblings to the right or below are changed.
+ 
  @code{enlarge-window} returns @code{nil}.
  @end deffn
  
***************
*** 1965,1971 ****
  @end example
  @end deffn
  
! @deffn Command shrink-window size &optional horizontal
  This function is like @code{enlarge-window} but negates the argument
  @var{size}, making the selected window smaller by giving lines (or
  columns) to the other windows.  If the window shrinks below
--- 1969,1975 ----
  @end example
  @end deffn
  
! @deffn Command shrink-window size &optional horizontal preserve-before
  This function is like @code{enlarge-window} but negates the argument
  @var{size}, making the selected window smaller by giving lines (or
  columns) to the other windows.  If the window shrinks below
***************
*** 1973,1978 ****
--- 1977,1986 ----
  
  If @var{size} is negative, the window is enlarged by @minus{}@var{size}
  lines or columns.
+ 
+ Optional third arg @var{preserve-before}, if non-@code{nil}, means do
+ not change the size of the siblings above or to the left of the
+ selected window.  Only siblings to the right or below are changed.
  @end deffn
  
  @deffn Command shrink-window-horizontally columns

Re: windows.texi doc fix

[Richard Stallman]

    Following is a small patch to the Elisp manual that fixes the missing
    documentation of the `preserve-before' optional argument of the
    functions `enlarge-window' and `shrink-window'.  I just added the
    description I found in doc strings.

It is good to notice that this needed to be fixed, but the style that
we use in doc strings is too terse and not correct enough for the
manual.  The former uses incomplete sentences, such as this:

    + Optional third arg @var{preserve-before}, if non-@code{nil}, means 

Could you please try rewriting this text using the style that we use
for such cases elsewhere in the manual?  Please just try your best--I
can polish it up after you install it.

Re: windows.texi doc fix

[David PONCE]

> It is good to notice that this needed to be fixed, but the style that
> we use in doc strings is too terse and not correct enough for the
> manual.  The former uses incomplete sentences, such as this:
> 
>     + Optional third arg @var{preserve-before}, if non-@code{nil}, means 
> 
> Could you please try rewriting this text using the style that we use
> for such cases elsewhere in the manual?  Please just try your best--I
> can polish it up after you install it.

OK.  WDYT of this version, which is much simpler.  As the
documentation explicitly says that `shrink-window' is like
`enlarge-window' but negates the size argument, I didn't duplicated
the description of `preserve-before'.

David

*** windows.texi.orig	2004-07-24 17:33:15.000000000 +0200
--- windows.texi	2004-10-21 12:32:38.681402600 +0200
***************
*** 1922,1928 ****
  window size.  Emacs does not permit overlapping windows or gaps between
  windows, so resizing one window affects other windows.
  
! @deffn Command enlarge-window size &optional horizontal
  This function makes the selected window @var{size} lines taller,
  stealing lines from neighboring windows.  It takes the lines from one
  window at a time until that window is used up, then takes from another.
--- 1922,1928 ----
  window size.  Emacs does not permit overlapping windows or gaps between
  windows, so resizing one window affects other windows.
  
! @deffn Command enlarge-window size &optional horizontal preserve-before
  This function makes the selected window @var{size} lines taller,
  stealing lines from neighboring windows.  It takes the lines from one
  window at a time until that window is used up, then takes from another.
***************
*** 1945,1950 ****
--- 1945,1955 ----
  size of a fixed-size window, @code{enlarge-window} gets an error
  instead.
  
+ If @var{preserve-before} is non-@code{nil}, this function does not
+ changes the size of the siblings above or to the left of the selected
+ window.  Only the size of the siblings below or to the right of the
+ selected window are changed.
+ 
  If @var{size} is negative, this function shrinks the window by
  @minus{}@var{size} lines or columns.  If that makes the window smaller
  than the minimum size (@code{window-min-height} and
***************
*** 1965,1971 ****
  @end example
  @end deffn
  
! @deffn Command shrink-window size &optional horizontal
  This function is like @code{enlarge-window} but negates the argument
  @var{size}, making the selected window smaller by giving lines (or
  columns) to the other windows.  If the window shrinks below
--- 1970,1976 ----
  @end example
  @end deffn
  
! @deffn Command shrink-window size &optional horizontal preserve-before
  This function is like @code{enlarge-window} but negates the argument
  @var{size}, making the selected window smaller by giving lines (or
  columns) to the other windows.  If the window shrinks below

Re: windows.texi doc fix

[Richard Stallman]

    + If @var{preserve-before} is non-@code{nil}, this function does not
    + changes the size of the siblings above or to the left of the selected
    + window.  Only the size of the siblings below or to the right of the
    + selected window are changed.

This is good now.  There's only a spelling error: "does not changes".
So please install it, fixing that.