new repository

1 files changed, 67 insertions, 0 deletions

diff --git a/devdocs/elisp/textual-scrolling.html b/devdocs/elisp/textual-scrolling.html
new file mode 100644
index 00000000..bc8800f2
--- /dev/null
+++ b/devdocs/elisp/textual-scrolling.html
@@ -0,0 +1,67 @@
+ <h3 class="section">Textual Scrolling</h3>   <p><em>Textual scrolling</em> means moving the text up or down through a window. It works by changing the window’s display-start location. It may also change the value of <code>window-point</code> to keep point on the screen (see <a href="window-point">Window Point</a>). </p> <p>The basic textual scrolling functions are <code>scroll-up</code> (which scrolls forward) and <code>scroll-down</code> (which scrolls backward). In these function names, “up” and “down” refer to the direction of motion of the buffer text relative to the window. Imagine that the text is written on a long roll of paper and that the scrolling commands move the paper up and down. Thus, if you are looking at the middle of a buffer and repeatedly call <code>scroll-down</code>, you will eventually see the beginning of the buffer. </p> <p>Unfortunately, this sometimes causes confusion, because some people tend to think in terms of the opposite convention: they imagine the window moving over text that remains in place, so that “down” commands take you to the end of the buffer. This convention is consistent with fact that such a command is bound to a key named <tt class="key">PageDown</tt> on modern keyboards. </p> <p>Textual scrolling functions (aside from <code>scroll-other-window</code>) have unpredictable results if the current buffer is not the one displayed in the selected window. See <a href="current-buffer">Current Buffer</a>. </p> <p>If the window contains a row taller than the height of the window (for example in the presence of a large image), the scroll functions will adjust the window’s vertical scroll position to scroll the partially visible row. Lisp callers can disable this feature by binding the variable <code>auto-window-vscroll</code> to <code>nil</code> (see <a href="vertical-scrolling">Vertical Scrolling</a>). </p> <dl> <dt id="scroll-up">Command: <strong>scroll-up</strong> <em>&amp;optional count</em>
+</dt> <dd>
+<p>This function scrolls forward by <var>count</var> lines in the selected window. </p> <p>If <var>count</var> is negative, it scrolls backward instead. If <var>count</var> is <code>nil</code> (or omitted), the distance scrolled is <code>next-screen-context-lines</code> lines less than the height of the window’s body. </p> <p>If the selected window cannot be scrolled any further, this function signals an error. Otherwise, it returns <code>nil</code>. </p>
+</dd>
+</dl> <dl> <dt id="scroll-down">Command: <strong>scroll-down</strong> <em>&amp;optional count</em>
+</dt> <dd>
+<p>This function scrolls backward by <var>count</var> lines in the selected window. </p> <p>If <var>count</var> is negative, it scrolls forward instead. In other respects, it behaves the same way as <code>scroll-up</code> does. </p>
+</dd>
+</dl> <dl> <dt id="scroll-up-command">Command: <strong>scroll-up-command</strong> <em>&amp;optional count</em>
+</dt> <dd><p>This behaves like <code>scroll-up</code>, except that if the selected window cannot be scrolled any further and the value of the variable <code>scroll-error-top-bottom</code> is <code>t</code>, it tries to move to the end of the buffer instead. If point is already there, it signals an error. </p></dd>
+</dl> <dl> <dt id="scroll-down-command">Command: <strong>scroll-down-command</strong> <em>&amp;optional count</em>
+</dt> <dd><p>This behaves like <code>scroll-down</code>, except that if the selected window cannot be scrolled any further and the value of the variable <code>scroll-error-top-bottom</code> is <code>t</code>, it tries to move to the beginning of the buffer instead. If point is already there, it signals an error. </p></dd>
+</dl> <dl> <dt id="scroll-other-window">Command: <strong>scroll-other-window</strong> <em>&amp;optional count</em>
+</dt> <dd>
+<p>This function scrolls the text in another window upward <var>count</var> lines. Negative values of <var>count</var>, or <code>nil</code>, are handled as in <code>scroll-up</code>. </p> <p>You can specify which buffer to scroll by setting the variable <code>other-window-scroll-buffer</code> to a buffer. If that buffer isn’t already displayed, <code>scroll-other-window</code> displays it in some window. </p> <p>When the selected window is the minibuffer, the next window is normally the leftmost one immediately above it. You can specify a different window to scroll, when the minibuffer is selected, by setting the variable <code>minibuffer-scroll-window</code>. This variable has no effect when any other window is selected. When it is non-<code>nil</code> and the minibuffer is selected, it takes precedence over <code>other-window-scroll-buffer</code>. See <a href="minibuffer-misc#Definition-of-minibuffer_002dscroll_002dwindow">Definition of minibuffer-scroll-window</a>. </p>
+</dd>
+</dl> <dl> <dt id="scroll-other-window-down">Command: <strong>scroll-other-window-down</strong> <em>&amp;optional count</em>
+</dt> <dd><p>This function scrolls the text in another window downward <var>count</var> lines. Negative values of <var>count</var>, or <code>nil</code>, are handled as in <code>scroll-down</code>. In other respects, it behaves the same way as <code>scroll-other-window</code> does. </p></dd>
+</dl> <dl> <dt id="other-window-scroll-buffer">Variable: <strong>other-window-scroll-buffer</strong>
+</dt> <dd><p>If this variable is non-<code>nil</code>, it tells <code>scroll-other-window</code> which buffer’s window to scroll. </p></dd>
+</dl> <dl> <dt id="scroll-margin">User Option: <strong>scroll-margin</strong>
+</dt> <dd><p>This option specifies the size of the scroll margin—a minimum number of lines between point and the top or bottom of a window. Whenever point gets within this many lines of the top or bottom of the window, redisplay scrolls the text automatically (if possible) to move point out of the margin, closer to the center of the window. </p></dd>
+</dl> <dl> <dt id="maximum-scroll-margin">User Option: <strong>maximum-scroll-margin</strong>
+</dt> <dd>
+<p>This variable limits the effective value of <code>scroll-margin</code> to a fraction of the current window line height. For example, if the current window has 20 lines and <code>maximum-scroll-margin</code> is 0.1, then the scroll margins will never be larger than 2 lines, no matter how big <code>scroll-margin</code> is. </p> <p><code>maximum-scroll-margin</code> itself has a maximum value of 0.5, which allows setting margins large to keep the cursor at the middle line of the window (or two middle lines if the window has an even number of lines). If it’s set to a larger value (or any value other than a float between 0.0 and 0.5) then the default value of 0.25 will be used instead. </p>
+</dd>
+</dl> <dl> <dt id="scroll-conservatively">User Option: <strong>scroll-conservatively</strong>
+</dt> <dd>
+<p>This variable controls how scrolling is done automatically when point moves off the screen (or into the scroll margin). If the value is a positive integer <var>n</var>, then redisplay scrolls the text up to <var>n</var> lines in either direction, if that will bring point back into proper view. This behavior is called <em>conservative scrolling</em>. Otherwise, scrolling happens in the usual way, under the control of other variables such as <code>scroll-up-aggressively</code> and <code>scroll-down-aggressively</code>. </p> <p>The default value is zero, which means that conservative scrolling never happens. </p>
+</dd>
+</dl> <dl> <dt id="scroll-down-aggressively">User Option: <strong>scroll-down-aggressively</strong>
+</dt> <dd>
+<p>The value of this variable should be either <code>nil</code> or a fraction <var>f</var> between 0 and 1. If it is a fraction, that specifies where on the screen to put point when scrolling down. More precisely, when a window scrolls down because point is above the window start, the new start position is chosen to put point <var>f</var> part of the window height from the top. The larger <var>f</var>, the more aggressive the scrolling. </p> <p>A value of <code>nil</code> is equivalent to .5, since its effect is to center point. This variable automatically becomes buffer-local when set in any fashion. </p>
+</dd>
+</dl> <dl> <dt id="scroll-up-aggressively">User Option: <strong>scroll-up-aggressively</strong>
+</dt> <dd><p>Likewise, for scrolling up. The value, <var>f</var>, specifies how far point should be placed from the bottom of the window; thus, as with <code>scroll-down-aggressively</code>, a larger value scrolls more aggressively. </p></dd>
+</dl> <dl> <dt id="scroll-step">User Option: <strong>scroll-step</strong>
+</dt> <dd><p>This variable is an older variant of <code>scroll-conservatively</code>. The difference is that if its value is <var>n</var>, that permits scrolling only by precisely <var>n</var> lines, not a smaller number. This feature does not work with <code>scroll-margin</code>. The default value is zero. </p></dd>
+</dl>  <dl> <dt id="scroll-preserve-screen-position">User Option: <strong>scroll-preserve-screen-position</strong>
+</dt> <dd>
+<p>If this option is <code>t</code>, whenever a scrolling command moves point off-window, Emacs tries to adjust point to keep the cursor at its old vertical position in the window, rather than the window edge. </p> <p>If the value is non-<code>nil</code> and not <code>t</code>, Emacs adjusts point to keep the cursor at the same vertical position, even if the scrolling command didn’t move point off-window. </p> <p>This option affects all scroll commands that have a non-<code>nil</code> <code>scroll-command</code> symbol property. </p>
+</dd>
+</dl> <dl> <dt id="next-screen-context-lines">User Option: <strong>next-screen-context-lines</strong>
+</dt> <dd><p>The value of this variable is the number of lines of continuity to retain when scrolling by full screens. For example, <code>scroll-up</code> with an argument of <code>nil</code> scrolls so that this many lines at the bottom of the window appear instead at the top. The default value is <code>2</code>. </p></dd>
+</dl> <dl> <dt id="scroll-error-top-bottom">User Option: <strong>scroll-error-top-bottom</strong>
+</dt> <dd>
+<p>If this option is <code>nil</code> (the default), <code>scroll-up-command</code> and <code>scroll-down-command</code> simply signal an error when no more scrolling is possible. </p> <p>If the value is <code>t</code>, these commands instead move point to the beginning or end of the buffer (depending on scrolling direction); only if point is already on that position do they signal an error. </p>
+</dd>
+</dl> <dl> <dt id="recenter">Command: <strong>recenter</strong> <em>&amp;optional count redisplay</em>
+</dt> <dd>
+ <p>This function scrolls the text in the selected window so that point is displayed at a specified vertical position within the window. It does not move point with respect to the text. </p> <p>If <var>count</var> is a non-negative number, that puts the line containing point <var>count</var> lines down from the top of the window. If <var>count</var> is a negative number, then it counts upward from the bottom of the window, so that -1 stands for the last usable line in the window. </p> <p>If <var>count</var> is <code>nil</code> (or a non-<code>nil</code> list), <code>recenter</code> puts the line containing point in the middle of the window. If <var>count</var> is <code>nil</code> and <var>redisplay</var> is non-<code>nil</code>, this function may redraw the frame, according to the value of <code>recenter-redisplay</code>. Thus, omitting the second argument can be used to countermand the effect of <code>recenter-redisplay</code> being non-<code>nil</code>. Interactive calls pass non-‘nil’ for <var>redisplay</var>. </p> <p>When <code>recenter</code> is called interactively, <var>count</var> is the raw prefix argument. Thus, typing <kbd>C-u</kbd> as the prefix sets the <var>count</var> to a non-<code>nil</code> list, while typing <kbd>C-u 4</kbd> sets <var>count</var> to 4, which positions the current line four lines from the top. </p> <p>With an argument of zero, <code>recenter</code> positions the current line at the top of the window. The command <code>recenter-top-bottom</code> offers a more convenient way to achieve this. </p>
+</dd>
+</dl>  <dl> <dt id="recenter-window-group">Function: <strong>recenter-window-group</strong> <em>&amp;optional count</em>
+</dt> <dd><p>This function is like <code>recenter</code>, except that when the selected window is part of a group of windows (see <a href="selecting-windows#Window-Group">Window Group</a>), <code>recenter-window-group</code> scrolls the entire group. This condition holds when the buffer local variable <code>recenter-window-group-function</code> is set to a function. In this case, <code>recenter-window-group</code> calls the function with the argument <var>count</var>, then returns its result. The argument <var>count</var> has the same meaning as in <code>recenter</code>, but with respect to the entire window group. </p></dd>
+</dl> <dl> <dt id="recenter-redisplay">User Option: <strong>recenter-redisplay</strong>
+</dt> <dd><p>If this variable is non-<code>nil</code>, calling <code>recenter</code> with a <code>nil</code> <var>count</var> argument and non-<code>nil</code> <var>redisplay</var> argument redraws the frame. The default value is <code>tty</code>, which means only redraw the frame if it is a tty frame. </p></dd>
+</dl> <dl> <dt id="recenter-top-bottom">Command: <strong>recenter-top-bottom</strong> <em>&amp;optional count</em>
+</dt> <dd><p>This command, which is the default binding for <kbd>C-l</kbd>, acts like <code>recenter</code>, except if called with no argument. In that case, successive calls place point according to the cycling order defined by the variable <code>recenter-positions</code>. </p></dd>
+</dl> <dl> <dt id="recenter-positions">User Option: <strong>recenter-positions</strong>
+</dt> <dd><p>This variable controls how <code>recenter-top-bottom</code> behaves when called with no argument. The default value is <code>(middle top
+bottom)</code>, which means that successive calls of <code>recenter-top-bottom</code> with no argument cycle between placing point at the middle, top, and bottom of the window. </p></dd>
+</dl><div class="_attribution">
+  <p class="_attribution-p">
+    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
+    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Textual-Scrolling.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Textual-Scrolling.html</a>
+  </p>
+</div>