master 63eab2948a: * lisp/pixel-scroll.el: Update commentary.

[Po Lu]

branch: master
commit 63eab2948a23c6302308358472fb7f718759f67a
Author: Po Lu <luangruo@yahoo.com>
Commit: Po Lu <luangruo@yahoo.com>

    * lisp/pixel-scroll.el: Update commentary.
---
 lisp/pixel-scroll.el | 25 +++++++++++++++++++++++--
 1 file changed, 23 insertions(+), 2 deletions(-)

diff --git a/lisp/pixel-scroll.el b/lisp/pixel-scroll.el
index e8b637ba1a..54724ca328 100644
--- a/lisp/pixel-scroll.el
+++ b/lisp/pixel-scroll.el
@@ -32,8 +32,10 @@
 
 ;;; Commentary:
 
-;; This package offers a global minor mode which makes mouse-wheel
-;; scroll a line smoothly.
+;; This file contains two somewhat related features.
+
+;; The first is a global minor mode which makes Emacs try to scroll
+;; each line smoothly.
 ;;
 ;; Scrolling a line up by `set-window-vscroll' and that by `scroll-up'
 ;; give similar display as shown below.
@@ -58,6 +60,25 @@
 ;;    (set-window-vscroll nil vs t) (sit-for 0))
 ;;  (scroll-up 1)
 
+;; The second is another global minor mode that redefines `wheel-up'
+;; and `wheel-down' to a command that tries to scroll the display
+;; according to the precise movement of a trackpad or mouse.
+
+;; But it operates in a much more intelligent manner than simply
+;; setting the vscroll.  It will set window start to the position
+;; closest to the position at the top-left corner of the window if
+;; vscroll were set accordingly, in a smart and fast manner, and only
+;; set vscroll the rest of the way.  There is no visible difference,
+;; but it is much faster, and doesn't move the display by a huge
+;; portion if vscroll is reset for some reason.
+
+;; It also tries to move point out of the way, so redisplay will not
+;; recenter the display as it scrolls.  This works well almost all of
+;; the time, but is impossible to get right with images larger than
+;; the window they're displayed in.  A feature that will allow
+;; redisplay to skip recentering is in the works, and will completely
+;; resolve this problem.
+
 ;;; Todo:
 ;;
 ;; Allowing pixel-level scrolling in Emacs requires a thorough review