bug#12865: 24.3.50; Doc fix for the Emacs Manual (scrolling)

bug#12865: 24.3.50; Doc fix for the Emacs Manual (scrolling)

[Dani Moncayo]

Hello,

I want to propose some corrections to the info node "(emacs) Auto Scrolling":

* "(less than N lines)" isn't correct.  It should be "(no more than N lines)".

* There are two paragraphs (4th and 7th) that explain the priority for
deciding which variable is obeyed in case the user sets more than one.
 It would be clearer to merge these two paragraph in one.

* The 5th paragraph states that `scroll-up/down-aggressively' take
effect "When the window does scroll by a distance longer than
`scroll-step'", but the 7th paragraph says that "These two variables
are ignored if either `scroll-step' or `scroll-conservatively' are set
to a non-zero value".  Therefore, the 5th paragraph can be simplified;
there is no need to mention `scroll-step' there (cause it must be
zero).


Also, a minor clarification for the info node "(emacs) Horizontal Scrolling":

* The 2nd paragraph should refer to "the window's edges" as
"left/right edges", to avoid ambiguity with the top/bottom edges.


The following patch is an attempt to make the above corrections (plus
some minor tweaks).  Feel free to use it, as is or with adjustments,
or to make the changes in your own way.  TIA


=== modified file 'doc/emacs/display.texi'
--- doc/emacs/display.texi	2012-11-07 20:43:38 +0000
+++ doc/emacs/display.texi	2012-11-11 20:57:35 +0000
@@ -214,58 +214,53 @@
 @section Automatic Scrolling

   Emacs performs @dfn{automatic scrolling} when point moves out of the
-visible portion of the text.
+visible portion of the text.  By default, this centers point
+vertically within the window, but you have several alternatives to
+customize this behavior.

 @vindex scroll-conservatively
-  Normally, this centers point vertically within the window.  However,
-if you set @code{scroll-conservatively} to a small number @var{n},
-then if you move point just a little off the screen (less than @var{n}
-lines), Emacs scrolls the text just far enough to bring point back on
-screen.  If doing so fails to make point visible, Emacs centers point
-in the window.  By default, @code{scroll-conservatively} is@tie{}0.
-If you set @code{scroll-conservatively} to a large number (larger than
-100), Emacs will never center point as result of scrolling, even if
-point moves far away from the text previously displayed in the window.
-With such a large value, Emacs will always scroll text just enough for
-bringing point into view, so point will end up at the top or bottom of
-the window, depending on the scroll direction.
+  If you set @code{scroll-conservatively} to a small number @var{n},
+then moving point just a little off the screen (no more than @var{n}
+lines), makes Emacs scroll the text just far enough to bring point
+back on screen.  If doing so fails to make point visible, Emacs
+centers point in the window.  By default, @code{scroll-conservatively}
+is@tie{}0.  If you set @code{scroll-conservatively} to a large number
+(larger than 100), Emacs will never center point as result of
+scrolling, even if point moves far away from the text previously
+displayed in the window.  With such a large value, Emacs will always
+scroll text just enough for bringing point into view, so point will
+end up at the top or bottom of the window, depending on the scroll
+direction.

 @vindex scroll-step
-  An alternative way of controlling how Emacs scrolls text is by
-customizing the variable @code{scroll-step}.  Its value determines how
-many lines to scroll the window when point moves off the screen.  If
-moving by that number of lines fails to bring point back into view,
-point is centered instead.  The default value is zero, which causes
-point to always be centered after scrolling.
-
-  Since both @code{scroll-conservatively} and @code{scroll-step}
-control automatic scrolling in contradicting ways, you should set only
-one of them.  If you customize both, the value of
-@code{scroll-conservatively} takes precedence.
+  The variable @code{scroll-step} determines how many lines to scroll
+the window when point moves off the screen.  If moving by that number
+of lines fails to bring point back into view, point is centered
+instead.  The default value is zero, which causes point to always be
+centered after scrolling.

 @cindex aggressive scrolling
 @vindex scroll-up-aggressively
 @vindex scroll-down-aggressively
-  When the window does scroll by a distance longer than
-@code{scroll-step}, you can control how aggressively it scrolls by
-setting the variables @code{scroll-up-aggressively} and
-@code{scroll-down-aggressively}.  The value of
-@code{scroll-up-aggressively} should be either @code{nil}, or a
-fraction @var{f} between 0 and 1.  A fraction specifies where on the
-screen to put point when scrolling upward, i.e.@: forward.  When point
-goes off the window end, the new start position is chosen to put point
-@var{f} parts of the window height from the bottom margin.  Thus,
-larger @var{f} means more aggressive scrolling: more new text is
-brought into view.  The default value, @code{nil}, is equivalent to
-0.5.
+  You can specify where on the screen to put point when scrolling
+upward by setting the variable @code{scroll-up-aggressively} to a
+fraction @var{f} between 0 and 1.  When point goes off the window end,
+the new start position is chosen to put point @var{f} parts of the
+window height from the bottom margin.  Thus, larger @var{f} means more
+aggressive scrolling: more new text is brought into view.  The default
+value, @code{nil}, is equivalent to 0.5.

   Likewise, @code{scroll-down-aggressively} is used for scrolling
 down, i.e.@: backward.  The value specifies how far point should be
 placed from the top margin of the window; thus, as with
 @code{scroll-up-aggressively}, a larger value is more aggressive.

-  These two variables are ignored if either @code{scroll-step} or
-@code{scroll-conservatively} are set to a non-zero value.
+  Since these variables (@code{scroll-conservatively},
+@code{scroll-step} and @code{scroll-up/down-aggressively} control
+automatic scrolling in contradicting ways, you should set only one of
+them, because only one will be obeyed.  The order of priority is:
+@code{scroll-conservatively} first, then @code{scroll-step} and
+finally @code{scroll-up/down-aggressively}.

 @vindex scroll-margin
   The variable @code{scroll-margin} restricts how close point can come
@@ -295,10 +290,10 @@

 @vindex hscroll-margin
   The variable @code{hscroll-margin} controls how close point can get
-to the window's edges before automatic scrolling occurs.  It is
-measured in columns.  For example, if the value is 5, then moving
-point within 5 columns of an edge causes horizontal scrolling away
-from that edge.
+to the window's left/right edges before automatic scrolling occurs.
+It is measured in columns.  For example, if the value is 5, then
+moving point within 5 columns of an edge causes horizontal scrolling
+away from that edge.

 @vindex hscroll-step
   The variable @code{hscroll-step} determines how many columns to



-- 
Dani Moncayo


In GNU Emacs 24.3.50.1 (i386-mingw-nt6.1.7601)
 of 2012-11-11 on MS-W7-DANI
Bzr revision: 110867 eggert@cs.ucla.edu-20121111183929-513iyuqggsacgftv
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -I../../libs/libXpm-3.5.10/include -I../../libs/libXpm-3.5.10/src
 -I../../libs/libpng-1.2.37-lib/include -I../../libs/zlib-1.2.5
 -I../../libs/giflib-4.1.4-1-lib/include
 -I../../libs/jpeg-6b-4-lib/include
 -I../../libs/tiff-3.8.2-1-lib/include
 -I../../libs/libxml2-2.7.8-w32-bin/include/libxml2
 -I../../libs/gnutls-3.0.9-w32-bin/include
 -I../../libs/libiconv-1.9.2-1-lib/include'

Important settings:
  value of $LANG: ESN
  locale-coding-system: cp1252
  default enable-multibyte-characters: t

bug#12865: 24.3.50; Doc fix for the Emacs Manual (scrolling)

[Chong Yidong]

Dani Moncayo <dmoncayo@gmail.com> writes:

> The following patch is an attempt to make the above corrections (plus
> some minor tweaks).  Feel free to use it, as is or with adjustments,
> or to make the changes in your own way.  TIA

Thanks.  I've committed the patch, with some tweaks.