# HG changeset patch # User Richard M. Stallman # Date 1138732740 0 # Node ID 698cfed8969f40bcc742e0fc9714034f14b8610f # Parent 9141c59ac2099fbd8dae6242671393204fd7cfce (Scrolling, Horizontal Scrolling, Follow Mode): Nodes moved to top. diff -r 9141c59ac209 -r 698cfed8969f man/display.texi --- a/man/display.texi Tue Jan 31 18:37:23 2006 +0000 +++ b/man/display.texi Tue Jan 31 18:39:00 2006 +0000 @@ -27,6 +27,245 @@ * Display Custom:: Information on variables for customizing display. @end menu +@node Scrolling +@section Scrolling + + If a buffer contains text that is too large to fit entirely within a +window that is displaying the buffer, Emacs shows a contiguous portion of +the text. The portion shown always contains point. + +@cindex scrolling + @dfn{Scrolling} means moving text up or down in the window so that +different parts of the text are visible. Scrolling ``forward'' or +``up'' means that text moves up, and new text appears at the bottom. +Scrolling ``backward'' or ``down'' moves text down, and new text +appears at the top. + + Scrolling happens automatically if you move point past the bottom or +top of the window. You can also scroll explicitly with the commands +in this section. + +@table @kbd +@item C-l +Clear screen and redisplay, scrolling the selected window to center +point vertically within it (@code{recenter}). +@item C-v +Scroll forward (a windowful or a specified number of lines) (@code{scroll-up}). +@item @key{NEXT} +@itemx @key{PAGEDOWN} +Likewise, scroll forward. +@item M-v +Scroll backward (@code{scroll-down}). +@item @key{PRIOR} +@itemx @key{PAGEUP} +Likewise, scroll backward. +@item @var{arg} C-l +Scroll so point is on line @var{arg} (@code{recenter}). +@item C-M-l +Scroll heuristically to bring useful information onto the screen +(@code{reposition-window}). +@end table + +@kindex C-l +@findex recenter + The most basic scrolling command is @kbd{C-l} (@code{recenter}) with +no argument. It scrolls the selected window so that point is halfway +down from the top of the window. On a text terminal, it also clears +the screen and redisplays all windows. That is useful in case the +screen is garbled (@pxref{Screen Garbled}). + +@kindex C-v +@kindex M-v +@kindex NEXT +@kindex PRIOR +@kindex PAGEDOWN +@kindex PAGEUP +@findex scroll-up +@findex scroll-down +@vindex next-screen-context-lines + To read the buffer a windowful at a time, use @kbd{C-v} +(@code{scroll-up}) with no argument. This scrolls forward by nearly +the whole window height. The effect is to take the two lines at the +bottom of the window and put them at the top, followed by nearly a +whole windowful of lines that were not previously visible. If point +was in the text that scrolled off the top, it ends up at the new top +of the window. + + @kbd{M-v} (@code{scroll-down}) with no argument scrolls backward in +a similar way, also with overlap. The number of lines of overlap +across a @kbd{C-v} or @kbd{M-v} is controlled by the variable +@code{next-screen-context-lines}; by default, it is 2. The function +keys @key{NEXT} and @key{PRIOR}, or @key{PAGEDOWN} and @key{PAGEUP}, +are equivalent to @kbd{C-v} and @kbd{M-v}. + + The commands @kbd{C-v} and @kbd{M-v} with a numeric argument scroll +the text in the selected window up or down a few lines. @kbd{C-v} +with an argument moves the text and point up, together, that many +lines; it brings the same number of new lines into view at the bottom +of the window. @kbd{M-v} with numeric argument scrolls the text +downward, bringing that many new lines into view at the top of the +window. @kbd{C-v} with a negative argument is like @kbd{M-v} and vice +versa. + + The names of scroll commands are based on the direction that the +text moves in the window. Thus, the command to scroll forward is +called @code{scroll-up} because it moves the text upward on the +screen. The keys @key{PAGEDOWN} and @key{PAGEUP} derive their names +and customary meanings from a different convention that developed +elsewhere; hence the strange result that @key{PAGEDOWN} runs +@code{scroll-up}. + +@vindex scroll-preserve-screen-position + Some users like the full-screen scroll commands to keep point at the +same screen line. To enable this behavior, set the variable +@code{scroll-preserve-screen-position} to a non-@code{nil} value. In +this mode, when scrolling shifts point off the screen, or into the +scrolling margins, Emacs moves point to keep the same vertical +position within the window. This mode is convenient for browsing +through a file by scrolling by screenfuls; if you come back to the +screen where you started, point goes back to the line where it +started. However, this mode is inconvenient when you move to the next +screen in order to move point to the text there. + + Another way to do scrolling is with @kbd{C-l} with a numeric argument. +@kbd{C-l} does not clear the screen when given an argument; it only scrolls +the selected window. With a positive argument @var{n}, it repositions text +to put point @var{n} lines down from the top. An argument of zero puts +point on the very top line. Point does not move with respect to the text; +rather, the text and point move rigidly on the screen. @kbd{C-l} with a +negative argument puts point that many lines from the bottom of the window. +For example, @kbd{C-u - 1 C-l} puts point on the bottom line, and @kbd{C-u +- 5 C-l} puts it five lines from the bottom. @kbd{C-u C-l} scrolls to put +point at the center (vertically) of the selected window. + +@kindex C-M-l +@findex reposition-window + The @kbd{C-M-l} command (@code{reposition-window}) scrolls the current +window heuristically in a way designed to get useful information onto +the screen. For example, in a Lisp file, this command tries to get the +entire current defun onto the screen if possible. + +@vindex scroll-conservatively + Scrolling happens automatically when point moves out of the visible +portion of the text. Normally, automatic scrolling 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---then Emacs scrolls the text just far enough to bring point +back on screen. By default, @code{scroll-conservatively} is 0. + +@cindex aggressive scrolling +@vindex scroll-up-aggressively +@vindex scroll-down-aggressively + When the window does scroll by a longer distance, 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. +More precisely, when a window scrolls up because point is above the +window start, the new start position is chosen to put point @var{f} +part of the window height from the top. The larger @var{f}, the more +aggressive the scrolling. + + @code{nil}, which is the default, scrolls to put point at the center. +So it is equivalent to .5. + + Likewise, @code{scroll-down-aggressively} is used for scrolling +down. The value, @var{f}, specifies how far point should be placed +from the bottom of the window; thus, as with +@code{scroll-up-aggressively}, a larger value is more aggressive. + +@vindex scroll-margin + The variable @code{scroll-margin} restricts how close point can come +to the top or bottom of a window. Its value is a number of screen +lines; if point comes within that many lines of the top or bottom of the +window, Emacs recenters the window. By default, @code{scroll-margin} is +0. + +@node Horizontal Scrolling +@section Horizontal Scrolling +@cindex horizontal scrolling + + @dfn{Horizontal scrolling} means shifting all the lines sideways +within a window---so that some of the text near the left margin is not +displayed at all. When the text in a window is scrolled horizontally, +text lines are truncated rather than continued (@pxref{Display +Custom}). Whenever a window shows truncated lines, Emacs +automatically updates its horizontal scrolling whenever point moves +off the left or right edge of the screen. You can also use these +commands to do explicit horizontal scrolling. + +@table @kbd +@item C-x < +Scroll text in current window to the left (@code{scroll-left}). +@item C-x > +Scroll to the right (@code{scroll-right}). +@end table + +@kindex C-x < +@kindex C-x > +@findex scroll-left +@findex scroll-right + The command @kbd{C-x <} (@code{scroll-left}) scrolls the selected +window to the left by @var{n} columns with argument @var{n}. This moves +part of the beginning of each line off the left edge of the window. +With no argument, it scrolls by almost the full width of the window (two +columns less, to be precise). + + @kbd{C-x >} (@code{scroll-right}) scrolls similarly to the right. The +window cannot be scrolled any farther to the right once it is displayed +normally (with each line starting at the window's left margin); +attempting to do so has no effect. This means that you don't have to +calculate the argument precisely for @w{@kbd{C-x >}}; any sufficiently large +argument will restore the normal display. + + If you use those commands to scroll a window horizontally, that sets +a lower bound for automatic horizontal scrolling. Automatic scrolling +will continue to scroll the window, but never farther to the right +than the amount you previously set by @code{scroll-left}. + +@vindex hscroll-margin + The value of the variable @code{hscroll-margin} controls how close +to the window's edges point is allowed to get before the window will +be automatically scrolled. It is measured in columns. If the value +is 5, then moving point within 5 columns of the edge causes horizontal +scrolling away from that edge. + +@vindex hscroll-step + The variable @code{hscroll-step} determines how many columns to +scroll the window when point gets too close to the edge. If it's +zero, horizontal scrolling centers point horizontally within the +window. If it's a positive integer, it specifies the number of +columns to scroll by. If it's a floating-point number, it specifies +the fraction of the window's width to scroll by. The default is zero. + +@vindex auto-hscroll-mode + To disable automatic horizontal scrolling, set the variable +@code{auto-hscroll-mode} to @code{nil}. + +@node Follow Mode +@section Follow Mode +@cindex Follow mode +@cindex mode, Follow +@findex follow-mode +@cindex windows, synchronizing +@cindex synchronizing windows + + @dfn{Follow mode} is a minor mode that makes two windows, both +showing the same buffer, scroll as a single tall ``virtual window.'' +To use Follow mode, go to a frame with just one window, split it into +two side-by-side windows using @kbd{C-x 3}, and then type @kbd{M-x +follow-mode}. From then on, you can edit the buffer in either of the +two windows, or scroll either one; the other window follows it. + + In Follow mode, if you move point outside the portion visible in one +window and into the portion visible in the other window, that selects +the other window---again, treating the two as if they were parts of +one large window. + + To turn off Follow mode, type @kbd{M-x follow-mode} a second time. + @node Faces @section Using Multiple Typefaces @cindex faces @@ -466,223 +705,6 @@ @code{hi-lock-exclude-modes}. @end table -@node Scrolling -@section Scrolling - - If a buffer contains text that is too large to fit entirely within a -window that is displaying the buffer, Emacs shows a contiguous portion of -the text. The portion shown always contains point. - -@cindex scrolling - @dfn{Scrolling} means moving text up or down in the window so that -different parts of the text are visible. Scrolling ``forward'' or -``up'' means that text moves up, and new text appears at the bottom. -Scrolling ``backward'' or ``down'' moves text down, and new text -appears at the top. - - Scrolling happens automatically if you move point past the bottom or -top of the window. You can also scroll explicitly with the commands -in this section. - -@table @kbd -@item C-l -Clear screen and redisplay, scrolling the selected window to center -point vertically within it (@code{recenter}). -@item C-v -Scroll forward (a windowful or a specified number of lines) (@code{scroll-up}). -@item @key{NEXT} -@itemx @key{PAGEDOWN} -Likewise, scroll forward. -@item M-v -Scroll backward (@code{scroll-down}). -@item @key{PRIOR} -@itemx @key{PAGEUP} -Likewise, scroll backward. -@item @var{arg} C-l -Scroll so point is on line @var{arg} (@code{recenter}). -@item C-M-l -Scroll heuristically to bring useful information onto the screen -(@code{reposition-window}). -@end table - -@kindex C-l -@findex recenter - The most basic scrolling command is @kbd{C-l} (@code{recenter}) with -no argument. It scrolls the selected window so that point is halfway -down from the top of the window. On a text terminal, it also clears -the screen and redisplays all windows. That is useful in case the -screen is garbled (@pxref{Screen Garbled}). - -@kindex C-v -@kindex M-v -@kindex NEXT -@kindex PRIOR -@kindex PAGEDOWN -@kindex PAGEUP -@findex scroll-up -@findex scroll-down -@vindex next-screen-context-lines - To read the buffer a windowful at a time, use @kbd{C-v} -(@code{scroll-up}) with no argument. This scrolls forward by nearly -the whole window height. The effect is to take the two lines at the -bottom of the window and put them at the top, followed by nearly a -whole windowful of lines that were not previously visible. If point -was in the text that scrolled off the top, it ends up at the new top -of the window. - - @kbd{M-v} (@code{scroll-down}) with no argument scrolls backward in -a similar way, also with overlap. The number of lines of overlap -across a @kbd{C-v} or @kbd{M-v} is controlled by the variable -@code{next-screen-context-lines}; by default, it is 2. The function -keys @key{NEXT} and @key{PRIOR}, or @key{PAGEDOWN} and @key{PAGEUP}, -are equivalent to @kbd{C-v} and @kbd{M-v}. - - The commands @kbd{C-v} and @kbd{M-v} with a numeric argument scroll -the text in the selected window up or down a few lines. @kbd{C-v} -with an argument moves the text and point up, together, that many -lines; it brings the same number of new lines into view at the bottom -of the window. @kbd{M-v} with numeric argument scrolls the text -downward, bringing that many new lines into view at the top of the -window. @kbd{C-v} with a negative argument is like @kbd{M-v} and vice -versa. - - The names of scroll commands are based on the direction that the -text moves in the window. Thus, the command to scroll forward is -called @code{scroll-up} because it moves the text upward on the -screen. The keys @key{PAGEDOWN} and @key{PAGEUP} derive their names -and customary meanings from a different convention that developed -elsewhere; hence the strange result that @key{PAGEDOWN} runs -@code{scroll-up}. - -@vindex scroll-preserve-screen-position - Some users like the full-screen scroll commands to keep point at the -same screen line. To enable this behavior, set the variable -@code{scroll-preserve-screen-position} to a non-@code{nil} value. In -this mode, when scrolling shifts point off the screen, or into the -scrolling margins, Emacs moves point to keep the same vertical -position within the window. This mode is convenient for browsing -through a file by scrolling by screenfuls; if you come back to the -screen where you started, point goes back to the line where it -started. However, this mode is inconvenient when you move to the next -screen in order to move point to the text there. - - Another way to do scrolling is with @kbd{C-l} with a numeric argument. -@kbd{C-l} does not clear the screen when given an argument; it only scrolls -the selected window. With a positive argument @var{n}, it repositions text -to put point @var{n} lines down from the top. An argument of zero puts -point on the very top line. Point does not move with respect to the text; -rather, the text and point move rigidly on the screen. @kbd{C-l} with a -negative argument puts point that many lines from the bottom of the window. -For example, @kbd{C-u - 1 C-l} puts point on the bottom line, and @kbd{C-u -- 5 C-l} puts it five lines from the bottom. @kbd{C-u C-l} scrolls to put -point at the center (vertically) of the selected window. - -@kindex C-M-l -@findex reposition-window - The @kbd{C-M-l} command (@code{reposition-window}) scrolls the current -window heuristically in a way designed to get useful information onto -the screen. For example, in a Lisp file, this command tries to get the -entire current defun onto the screen if possible. - -@vindex scroll-conservatively - Scrolling happens automatically when point moves out of the visible -portion of the text. Normally, automatic scrolling 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---then Emacs scrolls the text just far enough to bring point -back on screen. By default, @code{scroll-conservatively} is 0. - -@cindex aggressive scrolling -@vindex scroll-up-aggressively -@vindex scroll-down-aggressively - When the window does scroll by a longer distance, 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. -More precisely, when a window scrolls up because point is above the -window start, the new start position is chosen to put point @var{f} -part of the window height from the top. The larger @var{f}, the more -aggressive the scrolling. - - @code{nil}, which is the default, scrolls to put point at the center. -So it is equivalent to .5. - - Likewise, @code{scroll-down-aggressively} is used for scrolling -down. The value, @var{f}, specifies how far point should be placed -from the bottom of the window; thus, as with -@code{scroll-up-aggressively}, a larger value is more aggressive. - -@vindex scroll-margin - The variable @code{scroll-margin} restricts how close point can come -to the top or bottom of a window. Its value is a number of screen -lines; if point comes within that many lines of the top or bottom of the -window, Emacs recenters the window. By default, @code{scroll-margin} is -0. - -@node Horizontal Scrolling -@section Horizontal Scrolling -@cindex horizontal scrolling - - @dfn{Horizontal scrolling} means shifting all the lines sideways -within a window---so that some of the text near the left margin is not -displayed at all. When the text in a window is scrolled horizontally, -text lines are truncated rather than continued (@pxref{Display -Custom}). Whenever a window shows truncated lines, Emacs -automatically updates its horizontal scrolling whenever point moves -off the left or right edge of the screen. You can also use these -commands to do explicit horizontal scrolling. - -@table @kbd -@item C-x < -Scroll text in current window to the left (@code{scroll-left}). -@item C-x > -Scroll to the right (@code{scroll-right}). -@end table - -@kindex C-x < -@kindex C-x > -@findex scroll-left -@findex scroll-right - The command @kbd{C-x <} (@code{scroll-left}) scrolls the selected -window to the left by @var{n} columns with argument @var{n}. This moves -part of the beginning of each line off the left edge of the window. -With no argument, it scrolls by almost the full width of the window (two -columns less, to be precise). - - @kbd{C-x >} (@code{scroll-right}) scrolls similarly to the right. The -window cannot be scrolled any farther to the right once it is displayed -normally (with each line starting at the window's left margin); -attempting to do so has no effect. This means that you don't have to -calculate the argument precisely for @w{@kbd{C-x >}}; any sufficiently large -argument will restore the normal display. - - If you use those commands to scroll a window horizontally, that sets -a lower bound for automatic horizontal scrolling. Automatic scrolling -will continue to scroll the window, but never farther to the right -than the amount you previously set by @code{scroll-left}. - -@vindex hscroll-margin - The value of the variable @code{hscroll-margin} controls how close -to the window's edges point is allowed to get before the window will -be automatically scrolled. It is measured in columns. If the value -is 5, then moving point within 5 columns of the edge causes horizontal -scrolling away from that edge. - -@vindex hscroll-step - The variable @code{hscroll-step} determines how many columns to -scroll the window when point gets too close to the edge. If it's -zero, horizontal scrolling centers point horizontally within the -window. If it's a positive integer, it specifies the number of -columns to scroll by. If it's a floating-point number, it specifies -the fraction of the window's width to scroll by. The default is zero. - -@vindex auto-hscroll-mode - To disable automatic horizontal scrolling, set the variable -@code{auto-hscroll-mode} to @code{nil}. - @node Fringes @section Window Fringes @cindex fringes @@ -759,28 +781,6 @@ can enable or disable this feature for all new buffers. (This feature currently doesn't work on text-only terminals.) -@node Follow Mode -@section Follow Mode -@cindex Follow mode -@cindex mode, Follow -@findex follow-mode -@cindex windows, synchronizing -@cindex synchronizing windows - - @dfn{Follow mode} is a minor mode that makes two windows, both -showing the same buffer, scroll as a single tall ``virtual window.'' -To use Follow mode, go to a frame with just one window, split it into -two side-by-side windows using @kbd{C-x 3}, and then type @kbd{M-x -follow-mode}. From then on, you can edit the buffer in either of the -two windows, or scroll either one; the other window follows it. - - In Follow mode, if you move point outside the portion visible in one -window and into the portion visible in the other window, that selects -the other window---again, treating the two as if they were parts of -one large window. - - To turn off Follow mode, type @kbd{M-x follow-mode} a second time. - @node Selective Display @section Selective Display @cindex selective display