improve description of application scrollbar operation (#1033)

wiki/CtrlSeqs.md

@@ -182,14 +182,16 @@ position, and receive scrollbar events as control sequences.
 This mode is up to future revision. It is currently enabled or disabled 
 implicitly, there is no explicit mode setting sequence.
 
-The application scrollbar indicates a scrollbar view ("scroll offset") 
-within an assumed span of a virtual document ("document height", as 
-maintained by the application). The height of the view ("viewport height") 
+The application scrollbar indicates a scrollbar view (scroll offset _position_) 
+within an assumed span of a virtual document (document _size_, as 
+maintained by the application). The height of the view (viewport _height_) 
 defaults to the actual terminal size (rows); its difference to the 
-terminal size is kept when resizing the terminal. Control sequences 
-can set up the current view position ("scroll offset" from 1 to total size) 
-as well as the total virtual document size ("document height" in assumed lines) 
-and optionally the "viewport height".
+terminal size is kept when resizing the terminal.
+
+Control sequences can set the current view position (scroll offset _position_ 
+of the top end of the marked area in the scrollbar, 
+from 1 to _size_ − _height_ + 1) as well as the total virtual document _size_ 
+(in assumed lines) and optionally the viewport _height_.
 
 | **sequence**                       | **scrollbar**                                        |
 |:-----------------------------------|:-----------------------------------------------------|
@@ -201,6 +203,7 @@ and optionally the "viewport height".
 Relative scrollbar movement and absolute positioning are reported with 
 special sequences; for details see 
 [Keycodes – Application scrollbar events](https://github.com/mintty/mintty/wiki/Keycodes#application-scrollbar-events).
+See there also for an illustrated explanation of the meaning of _pos_ vs _size_ values.
 
 
 ## Mousewheel reporting ##

wiki/Keycodes.md

@@ -248,6 +248,32 @@ the modifiers like for other function keys.
 | **Top**         | `^[[0#d`        |                                  |
 | **Bottom**      | `^[[`_size_`#d` | configured virtual _size_        |
 
+See the screenshots for an illustration of the meaning of _pos_ vs _size_ values.
+
+<img align=left src=https://github.com/mintty/mintty/wiki/application-scrollbar-middle.png>
+The position of the _viewport_ (the marked area of the scrollbar) is 
+measured at its top. So when setting up position 50 in size 100 (`^[[50;100;20#t`),
+the viewport is not centered but begins in the middle of the scrollbar.
+<br clear=all>
+
+<img align=left src=https://github.com/mintty/mintty/wiki/application-scrollbar-bottom.png>
+Also, when the viewport is dragged to the bottom, it ends at the total size 
+but the reported position is its beginning (81 in the example, mouse button 
+still held). So the maximum position reported after pulling or dragging the 
+viewport is _size_ − _height_ + 1, but the position reported when placing it 
+directly to the bottom (from the scrollbar menu) will yet be full _size_.
+(Likewise the minimum position reported when dragging is 1 but the position 
+reported for placing to the top is 0.)
+<br clear=all>
+
+Note also that after dragging and releasing the mouse button, the viewport 
+position flips back to its previous place until the application interprets 
+the report and sets the position. (This is to prevent looping interference 
+with updated positions triggering additional system events.)
+
+For the sequences to set up application scrollbar mode and change its parameters see 
+[Control Sequences – Application scrollbar](https://github.com/mintty/mintty/wiki/CtrlSeqs#application-scrollbar).
+
 
 ## Mousewheel ##