Mercurial > emacs
changeset 22252:40089afa2b1d
*** empty log message ***
| author | Richard M. Stallman <rms@gnu.org> |
|---|---|
| date | Tue, 26 May 1998 18:56:56 +0000 |
| parents | 5989fa41cda6 |
| children | ed6b191416cf |
| files | lispref/advice.texi lispref/anti.texi lispref/backups.texi lispref/buffers.texi lispref/calendar.texi lispref/commands.texi lispref/customize.texi lispref/debugging.texi lispref/display.texi lispref/edebug.texi lispref/elisp.texi lispref/errors.texi lispref/frames.texi lispref/help.texi lispref/intro.texi lispref/keymaps.texi lispref/loading.texi lispref/markers.texi lispref/minibuf.texi lispref/modes.texi lispref/nonascii.texi lispref/os.texi lispref/positions.texi lispref/processes.texi lispref/searching.texi lispref/sequences.texi lispref/streams.texi lispref/strings.texi lispref/syntax.texi lispref/text.texi lispref/tips.texi lispref/variables.texi lispref/windows.texi |
| diffstat | 33 files changed, 772 insertions(+), 462 deletions(-) [+] |
line wrap: on
line diff
--- a/lispref/advice.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/advice.texi Tue May 26 18:56:56 1998 +0000 @@ -12,10 +12,12 @@ library to customize functions defined by other parts of Emacs---cleaner than redefining the whole function. - Each piece of advice can be enabled or disabled explicitly. The -enabled pieces of advice for any given function actually take effect -when you activate advice for that function, or when that function is -subsequently defined or redefined. +@cindex piece of advice + Each function can have multiple @dfn{pieces of advice}, separately +defined. Each defined piece of advice can be enabled or disabled +explicitly. The enabled pieces of advice for any given function +actually take effect when you @dfn{activate} advice for that function, or when +that function is subsequently defined or redefined. @strong{Usage Note:} Advice is useful for altering the behavior of existing calls to an existing function. If you want the new behavior @@ -25,12 +27,13 @@ @menu * Simple Advice:: A simple example to explain the basics of advice. * Defining Advice:: Detailed description of @code{defadvice}. +* Around-Advice:: Wrapping advice around a function's definition. * Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}. * Activation of Advice:: Advice doesn't do anything until you activate it. * Enabling Advice:: You can enable or disable each piece of advice. * Preactivation:: Preactivation is a way of speeding up the loading of compiled advice. -* Argument Access:: How advice can access the function's arguments. +* Argument Access in Advice:: How advice can access the function's arguments. * Subr Arguments:: Accessing arguments when advising a primitive. * Combined Definition:: How advice is implemented. @end menu @@ -63,7 +66,6 @@ (newline)))) @end example -@cindex piece of advice This expression defines a @dfn{piece of advice} for the function @code{previous-line}. This piece of advice is named @code{next-line-at-end}, and the symbol @code{before} says that it is @@ -100,10 +102,12 @@ @node Defining Advice @section Defining Advice +@cindex defining advice +@cindex advice, defining To define a piece of advice, use the macro @code{defadvice}. A call to @code{defadvice} has the following syntax, which is based on the -syntax of @code{defun}/@code{defmacro} but adds more: +syntax of @code{defun} and @code{defmacro}, but adds more: @findex defadvice @example @@ -132,14 +136,13 @@ around-advice can override the return value by setting @code{ad-return-value}. -Around-advice specifies where the ``original'' function definition -should go by means of the special symbol @code{ad-do-it}. Where this -symbol occurs inside the around-advice body, it is replaced with a -@code{progn} containing the forms of the surrounded code. If the -around-advice does not use @code{ad-do-it}, then the original function -definition is never run. This provides a way to override the original -definition completely. (It also overrides lower-positioned pieces of -around-advice). +@defvar ad-return-value +While advice is executing, after the function's original definition has +been executed, this variable holds its return value, which will +ultimately be returned to the caller after finishing all the advice. +After-advice and around-advice can arrange to return some other value +by storing it in this variable. +@end defvar The argument @var{name} is the name of the advice, a non-@code{nil} symbol. The advice name uniquely identifies one piece of advice, within all @@ -152,11 +155,12 @@ The optional @var{position} specifies where, in the current list of advice of the specified @var{class}, this new advice should be placed. -It should be either @code{first}, @code{last} or a number that -specifies a zero-based position (@code{first} is equivalent to 0). If -no position is specified, the default is @code{first}. The -@var{position} value is ignored when redefining an existing piece of -advice. +It should be either @code{first}, @code{last} or a number that specifies +a zero-based position (@code{first} is equivalent to 0). If no position +is specified, the default is @code{first}. Position values outside the +range of existing positions in this class are mapped to the beginning or +the end of the range, whichever is closer. The @var{position} value is +ignored when redefining an existing piece of advice. The optional @var{arglist} can be used to define the argument list for the sake of advice. This becomes the argument list of the combined @@ -168,12 +172,11 @@ original function, so that it can handle the ways the function is actually called. If more than one piece of advice specifies an argument list, then the first one (the one with the smallest position) found in -the list of all classes of advice is used. Numbers outside the range -are mapped to the beginning or the end, whichever is closer. +the list of all classes of advice is used. -The remaining elements, @var{flags}, is a list of symbols that specify -further information about how to use this piece of advice. Here are the -valid symbols and their meanings: +The remaining elements, @var{flags}, are symbols that specify further +information about how to use this piece of advice. Here are the valid +symbols and their meanings: @table @code @item activate @@ -190,8 +193,8 @@ @item protect Protect this piece of advice against non-local exits and errors in -preceding code and advice. Protecting advice makes it a cleanup in an -@code{unwind-protect} form, so that it will execute even if the +preceding code and advice. Protecting advice places it as a cleanup in +an @code{unwind-protect} form, so that it will execute even if the previous code gets an error or uses @code{throw}. @xref{Cleanups}. @item compile @@ -233,6 +236,38 @@ All subroutines used by the advice need to be available when the byte compiler expands the macro. +@node Around-Advice +@section Around-Advice + + Around-advice lets you ``wrap'' a Lisp expression ``around'' the +original function definition. You specify where the original function +definition should go by means of the special symbol @code{ad-do-it}. +Where this symbol occurs inside the around-advice body, it is replaced +with a @code{progn} containing the forms of the surrounded code. Here +is an example: + +@example +(defadvice foo (around foo-around) + "Ignore case in `foo'." + (let ((case-fold-search t)) + ad-do-it)) +@end example + +@noindent +Its effect is to make sure that case is ignored in +searches when the original definition of @code{foo} is run. + +@defvar ad-do-it +This is not really a variable, but it is somewhat used like one +in around-advice. It specifies the place to run the function's +original definition and other ``earlier'' around-advice. +@end defvar + +If the around-advice does not use @code{ad-do-it}, then it does not run +the original function definition. This provides a way to override the +original definition completely. (It also overrides lower-positioned +pieces of around-advice). + @node Computed Advice @section Computed Advice @@ -270,6 +305,7 @@ @node Activation of Advice @section Activation of Advice @cindex activating advice +@cindex advice, activating By default, advice does not take effect when you define it---only when you @dfn{activate} advice for the function that was advised. You can @@ -302,10 +338,13 @@ To activate advice for a function whose advice is already active is not a no-op. It is a useful operation which puts into effect any changes in -advice since the previous activation of that function's advice. +that function's advice since the previous activation of advice for that +function. @deffn Command ad-deactivate function This command deactivates the advice for @var{function}. +@cindex deactivating advice +@cindex advice, deactivating @end deffn @deffn Command ad-activate-all &optional compile @@ -323,7 +362,7 @@ @end deffn @deffn Command ad-deactivate-regexp regexp -This command deactivates the advice for all functions whose names match +This command deactivates all pieces of advice whose names match @var{regexp}. More precisely, it deactivates all advice for any function which has at least one piece of advice that matches @var{regexp}. @@ -332,6 +371,7 @@ @deffn Command ad-update-regexp regexp &optional compile This command activates pieces of advice whose names match @var{regexp}, but only those for functions whose advice is already activated. +@cindex reactivating advice Reactivating a function's advice is useful for putting into effect all the changes that have been made in its advice (including enabling and @@ -355,17 +395,20 @@ that results from activating advice for a function. @end defopt - If the advised definition was constructed during ``preactivation'' (see -below), then that definition must already be compiled, because it was -constructed during byte-compilation of the file that contained the -@code{defadvice} with the @code{preactivate} flag. + If the advised definition was constructed during ``preactivation'' +(@pxref{Preactivation}), then that definition must already be compiled, +because it was constructed during byte-compilation of the file that +contained the @code{defadvice} with the @code{preactivate} flag. @node Enabling Advice @section Enabling and Disabling Advice +@cindex enabling advice +@cindex advice, enabling and disabling +@cindex disabling advice Each piece of advice has a flag that says whether it is enabled or -not. By enabling or disabling a piece of advice, you can turn it off -and on without having to undefine and redefine it. For example, here is +not. By enabling or disabling a piece of advice, you can turn it on +and off without having to undefine and redefine it. For example, here is how to disable a particular piece of advice named @code{my-advice} for the function @code{foo}: @@ -373,7 +416,7 @@ (ad-disable-advice 'foo 'before 'my-advice) @end example -This function by itself only changes the enable flag for a piece of + This function by itself only changes the enable flag for a piece of advice. To make the change take effect in the advised definition, you must activate the advice for @code{foo} again: @@ -408,6 +451,8 @@ @node Preactivation @section Preactivation +@cindex preactivating advice +@cindex advice, preactivating Constructing a combined definition to execute advice is moderately expensive. When a library advises many functions, this can make loading @@ -486,7 +531,7 @@ A more robust method is to use macros that are translated into the proper access forms at activation time, i.e., when constructing the advised definition. Access macros access actual arguments by position -regardless of how these actual argument get distributed onto the +regardless of how these actual arguments get distributed onto the argument variables of a function. This is robust because in Emacs Lisp the meaning of an argument is strictly determined by its position in the argument list.
--- a/lispref/anti.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/anti.texi Tue May 26 18:56:56 1998 +0000 @@ -73,7 +73,7 @@ or specified padding. @item -The functions @code{split-string} and @code{concat-chars} no longer exist. +The functions @code{split-string} and @code{string} no longer exist. Neither does @code{store-substring} or @code{sref}. @item
--- a/lispref/backups.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/backups.texi Tue May 26 18:56:56 1998 +0000 @@ -588,17 +588,17 @@ of the file with the @code{revert-buffer} command. @xref{Reverting, , Reverting a Buffer, emacs, The GNU Emacs Manual}. -@deffn Command revert-buffer &optional check-auto-save noconfirm +@deffn Command revert-buffer &optional ignore-auto noconfirm This command replaces the buffer text with the text of the visited file on disk. This action undoes all changes since the file was visited or saved. -If the argument @var{check-auto-save} is non-@code{nil}, and the -latest auto-save file is more recent than the visited file, -@code{revert-buffer} asks the user whether to use that instead. -Otherwise, it always uses the text of the visited file itself. -Interactively, @var{check-auto-save} is set if there is a numeric prefix -argument. +By default, if the latest auto-save file is more recent than the visited +file, @code{revert-buffer} asks the user whether to use that instead. +But if the argument @var{ignore-auto} is non-@code{nil}, then only the +the visited file itself is used. Interactively, @var{ignore-auto} is +@code{t} unless there is a numeric prefix argument; thus, the +interactive default is to check the auto-save file. Normally, @code{revert-buffer} asks for confirmation before it changes the buffer; but if the argument @var{noconfirm} is non-@code{nil}, @@ -616,6 +616,14 @@ You can customize how @code{revert-buffer} does its work by setting these variables---typically, as buffer-local variables. +@defvar revert-without-query +This variable holds a list of files that should be reverted without +query. The value is a list of regular expressions. If a file name +matches one of these regular expressions, then @code{revert-buffer} +reverts the file without asking the user for confirmation, if the file +has changed on disk and the buffer is not modified. +@end defvar + @defvar revert-buffer-function The value of this variable is the function to use to revert this buffer. If non-@code{nil}, it is called as a function with no arguments to do
--- a/lispref/buffers.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/buffers.texi Tue May 26 18:56:56 1998 +0000 @@ -213,7 +213,7 @@ exit from @code{save-current-buffer}, then it is not made current again, of course. Instead, whichever buffer was current just before exit remains current. -@end defmac +@end defspec @defmac with-current-buffer buffer body... @tindex with-current-buffer @@ -427,7 +427,7 @@ such buffer in the buffer list. @end defun -@deffn Command set-visited-file-name filename +@deffn Command set-visited-file-name filename &optional no-query along-with-file If @var{filename} is a non-empty string, this function changes the name of the file visited in current buffer to @var{filename}. (If the buffer had no visited file, this gives it one.) The @emph{next time} @@ -440,6 +440,13 @@ ``no visited file''. In this case, @code{set-visited-file-name} marks the buffer as having no visited file. +Normally, this function asks the user for confirmation if the specified +file already exists. If @var{no-query} is non-@code{nil}, that prevents +asking this question. + +If @var{along-with-file} is non-@code{nil}, that means to assume that the +former visited file has been renamed to @var{filename}. + @c Wordy to avoid overfull hbox. --rjc 16mar92 When the function @code{set-visited-file-name} is called interactively, it prompts for @var{filename} in the minibuffer. @@ -723,21 +730,21 @@ @code{buffer-list} frame parameter with @code{modify-frame-parameters} (@pxref{Parameter Access}). -@defun other-buffer &optional buffer visible-ok +@defun other-buffer &optional buffer visible-ok frame This function returns the first buffer in the buffer list other than -@var{buffer}. Usually this is the buffer selected most recently (in the -currently selected frame), aside from @var{buffer}. Buffers whose names -start with a space are not considered at all. +@var{buffer}. Usually this is the buffer selected most recently (in +frame @var{frame} or else the currently selected frame), aside from +@var{buffer}. Buffers whose names start with a space are not considered +at all. If @var{buffer} is not supplied (or if it is not a buffer), then @code{other-buffer} returns the first buffer in the selected frame's buffer list that is not now visible in any window in a visible frame. -If the selected frame has a non-@code{nil} @code{buffer-predicate} -parameter, then @code{other-buffer} uses that predicate to decide which -buffers to consider. It calls the predicate once for each buffer, and -if the value is @code{nil}, that buffer is ignored. @xref{Window Frame -Parameters}. +If @var{frame} has a non-@code{nil} @code{buffer-predicate} parameter, +then @code{other-buffer} uses that predicate to decide which buffers to +consider. It calls the predicate once for each buffer, and if the value +is @code{nil}, that buffer is ignored. @xref{Window Frame Parameters}. @c Emacs 19 feature If @var{visible-ok} is @code{nil}, @code{other-buffer} avoids returning
--- a/lispref/calendar.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/calendar.texi Tue May 26 18:56:56 1998 +0000 @@ -577,7 +577,7 @@ @noindent and would appear in the diary for any date that corresponds to Heshvan 25 -on the Hebrew calendar. And here is Islamic-date diary entry that matches +on the Hebrew calendar. And here is an Islamic-date diary entry that matches Dhu al-Qada 25: @smallexample @@ -668,7 +668,7 @@ @cindex sorting diary entries If you use the fancy diary display, you can use the normal hook @code{list-diary-entries-hook} to sort each day's diary entries by their -time of day. Here's how +time of day. Here's how: @findex sort-diary-entries @example
--- a/lispref/commands.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/commands.texi Tue May 26 18:56:56 1998 +0000 @@ -1589,7 +1589,7 @@ (- (point-max) (point-min)))) @end example -Recall that scroll bar events have two integers forming ratio in place +Recall that scroll bar events have two integers forming a ratio, in place of a pair of x and y coordinates. @end defun @@ -1652,7 +1652,8 @@ To support programs with @samp{\M-} in string constants, there are special rules for including certain meta characters in a string. -Here are the rules for interpreting keyboard +Here are the rules for interpreting a string as a sequence of input +characters: @itemize @bullet @item @@ -1854,7 +1855,7 @@ moves the cursor temporarily to the echo area, to the end of any message displayed there. Otherwise @code{read-event} does not move the cursor. -If @code{read-event} gets an event is defined as a help character, in +If @code{read-event} gets an event that is defined as a help character, in some cases @code{read-event} processes the event directly without returning. @xref{Help Functions}. Certain other events, called @dfn{special events}, are also processed directly within @@ -1948,7 +1949,8 @@ This section describes how to ``peek ahead'' at events without using them up, how to check for pending input, and how to discard pending -input. +input. See also the function @code{read-passwd} (@pxref{Reading a +Password}). @defvar unread-command-events @cindex next input
--- a/lispref/customize.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/customize.texi Tue May 26 18:56:56 1998 +0000 @@ -372,9 +372,9 @@ @item hook The value must be a list of functions (or a single function, but that is obsolete usage). This customization type is used for hook variables. -You can use the @code{:option} in the @code{defcustom} for a hook -variable to specify functions recommended for use in the hook; -see @ref{Variable Definitions}. +You can use the @code{:options} keyword in a hook variable's +@code{defcustom} to specify a list of functions recommended for use in +the hook; see @ref{Variable Definitions}. @item symbol The value must be a symbol. It appears in the customization buffer as
--- a/lispref/debugging.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/debugging.texi Tue May 26 18:56:56 1998 +0000 @@ -124,7 +124,7 @@ If you set @code{debug-on-signal} to a non-@code{nil} value, then the debugger gets the first chance at every error; an error will invoke the debugger regardless of any @code{condition-case}, if it fits the -criterion specified by the values of @code{debug-on-error} and +criteria specified by the values of @code{debug-on-error} and @code{debug-ignored-errors}. @strong{Warning:} This variable is strong medicine! Various parts of @@ -139,9 +139,9 @@ To debug an error that happens during loading of the @file{.emacs} file, use the option @samp{--debug-init}, which binds -@code{debug-on-error} to @code{t} while @file{.emacs} is loaded, and +@code{debug-on-error} to @code{t} while loading @file{.emacs}, and bypasses the @code{condition-case} which normally catches errors in the -init-file. +init file. If your @file{.emacs} file sets @code{debug-on-error}, the effect may not last past the end of loading @file{.emacs}. (This is an undesirable @@ -737,7 +737,7 @@ and you have put back those parentheses, @kbd{C-M-q} should not change anything. -@node Compilation Errors, Edebug, Syntax Errors, Debugging +@node Compilation Errors @section Debugging Problems in Compilation When an error happens during byte compilation, it is normally due to
--- a/lispref/display.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/display.texi Tue May 26 18:56:56 1998 +0000 @@ -11,7 +11,6 @@ @menu * Refresh Screen:: Clearing the screen and redrawing everything on it. -* Screen Size:: How big is the Emacs screen. * Truncation:: Folding or wrapping long text lines. * The Echo Area:: Where messages are displayed. * Invisible Text:: Hiding part of the buffer text. @@ -33,7 +32,7 @@ @section Refreshing the Screen The function @code{redraw-frame} redisplays the entire contents of a -given frame. @xref{Frames}. +given frame (@pxref{Frames}). @c Emacs 19 feature @defun redraw-frame frame @@ -65,65 +64,6 @@ to redraw, @code{nil} means redrawing is needed. The default is @code{nil}. @end defvar -@node Screen Size -@section Screen Size -@cindex size of screen -@cindex screen size -@cindex display lines -@cindex display columns -@cindex resize redisplay - - The screen size functions access or specify the height or width of -the terminal. When you are using multiple frames, they apply to the -selected frame (@pxref{Frames}). - -@defun screen-height -This function returns the number of lines on the screen that are -available for display. - -@example -@group -(screen-height) - @result{} 50 -@end group -@end example -@end defun - -@defun screen-width -This function returns the number of columns on the screen that are -available for display. - -@example -@group -(screen-width) - @result{} 80 -@end group -@end example -@end defun - -@defun set-screen-height lines &optional not-actual-size -This function declares that the terminal can display @var{lines} lines. -The sizes of existing windows are altered proportionally to fit. - -If @var{not-actual-size} is non-@code{nil}, then Emacs displays -@var{lines} lines of output, but does not change its value for the -actual height of the screen. (Knowing the correct actual size may be -necessary for correct cursor positioning.) Using a smaller height than -the terminal actually implements may be useful to reproduce behavior -observed on a smaller screen, or if the terminal malfunctions when using -its whole screen. - -If @var{lines} is different from what it was previously, then the -entire screen is cleared and redisplayed using the new size. - -This function returns @code{nil}. -@end defun - -@defun set-screen-width columns &optional not-actual-size -This function declares that the terminal can display @var{columns} -columns. The details are as in @code{set-screen-height}. -@end defun - @node Truncation @section Truncation @cindex line wrapping @@ -173,7 +113,7 @@ You can override the glyphs that indicate continuation or truncation using the display table; see @ref{Display Tables}. - If your buffer contains @strong{very} long lines, and you use + If your buffer contains @emph{very} long lines, and you use continuation to display them, just thinking about them can make Emacs redisplay slow. The column computation and indentation functions also become slow. Then you might find it advisable to set @@ -395,7 +335,7 @@ During the search, such overlays are made temporarily visible by temporarily modifying their invisible and intangible properties. If you -want this to be done differently for a certain overlays, give it a +want this to be done differently for a certain overlay, give it a @code{isearch-open-invisible-temporary} property which is a function. The function is called with two arguments: the first is the overlay, and the second is @code{t} to make the overlay visible, or @code{nil} to @@ -1093,7 +1033,7 @@ @code{t} is used in the last (or only) element of @var{spec}. @item a list -If @var{display} is alist, each elements should have the form +If @var{display} is a list, each element should have the form @code{(@var{characteristic} @var{value}@dots{})}. Here @var{characteristic} specifies a way of classifying frames, and the @var{value}s are possible classifications which @var{display} should @@ -1110,7 +1050,7 @@ @code{grayscale}, or @code{mono}. @item background -The kind of background--- either @code{light} or @code{dark}. +The kind of background---either @code{light} or @code{dark}. @end table If an element of @var{display} specifies more than one @var{value} for a @@ -1139,6 +1079,15 @@ with the customization buffer, and @code{face-documentation} for the documentation string. +@tindex frame-background-mode +@defopt frame-background-mode +This option, if non-@code{nil}, specifies the background type to use for +interpreting face definitions. If it is @code{dark}, then Emacs treats +all frames as if they had a dark background, regardless of their actual +background colors. If it is @code{light}, then Emacs treats all frames +as if they had a light background. +@end defopt + @node Merging Faces @subsection Merging Faces for Display @@ -1339,6 +1288,12 @@ Normally, the value is the face number of the face named @code{region}. @end defvar +@tindex frame-update-face-colors +@defun frame-update-face-colors frame +This function updates the way faces display on @var{frame}, for a change +in @var{frame}'s foreground or background color. +@end defun + @node Blinking @section Blinking Parentheses @cindex parenthesis matching @@ -1356,23 +1311,23 @@ case nothing is done. @end defvar -@defvar blink-matching-paren +@defopt blink-matching-paren If this variable is @code{nil}, then @code{blink-matching-open} does nothing. -@end defvar +@end defopt -@defvar blink-matching-paren-distance +@defopt blink-matching-paren-distance This variable specifies the maximum distance to scan for a matching parenthesis before giving up. -@end defvar +@end defopt -@defvar blink-matching-paren-delay +@defopt blink-matching-delay This variable specifies the number of seconds for the cursor to remain at the matching parenthesis. A fraction of a second often gives good results, but the default is 1, which works on all systems. -@end defvar +@end defopt -@defun blink-matching-open +@deffn Command blink-matching-open This function is the default value of @code{blink-paren-function}. It assumes that point follows a character with close parenthesis syntax and moves the cursor momentarily to the matching opening character. If that @@ -1398,7 +1353,7 @@ (blink-matching-open))) @end group @end smallexample -@end defun +@end deffn @node Inverse Video @section Inverse Video @@ -1655,13 +1610,13 @@ Here are the possible types of elements in the glyph table: -@table @var -@item string +@table @asis +@item @var{string} Send the characters in @var{string} to the terminal to output this glyph. This alternative is available on character terminals, but not under a window system. -@item integer +@item @var{integer} Define this glyph code as an alias for glyph code @var{integer}. You can use an alias to specify a face code for the glyph; see below. @@ -1705,13 +1660,13 @@ This is a synonym for @code{ding}. @end defun -@defvar visible-bell +@defopt visible-bell This variable determines whether Emacs should flash the screen to represent a bell. Non-@code{nil} means yes, @code{nil} means no. This is effective on a window system, and on a character-only terminal provided the terminal's Termcap entry defines the visible bell capability (@samp{vb}). -@end defvar +@end defopt @defvar ring-bell-function @tindex ring-bell-function @@ -1728,11 +1683,20 @@ concerned; the individual Emacs windows are not known to X at all. @defvar window-system +This variable tells Lisp programs what window system Emacs is running +under. The possible values are + +@table @code +@item x @cindex X Window System -This variable tells Lisp programs what window system Emacs is running -under. Its value should be a symbol such as @code{x} (if Emacs is -running under X) or @code{nil} (if Emacs is running on an ordinary -terminal). +Emacs is displaying using X. +@item pc +Emacs is displaying using MSDOS. +@item w32 +Emacs is displaying using Windows NT or Windows 95. +@item nil +Emacs is using a character-based terminal. +@end table @end defvar @defvar window-setup-hook
--- a/lispref/edebug.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/edebug.texi Tue May 26 18:56:56 1998 +0000 @@ -9,7 +9,7 @@ @c , Bugs and Todo List, Top, Top -@node Edebug,, Compilation Errors, Debugging +@node Edebug, Syntax Errors, Debugger, Debugging @section Edebug @cindex Edebug mode @@ -583,10 +583,12 @@ pause for @var{n} seconds instead. @item w -Move point back to the current stop point (@code{edebug-where}) in the -source code buffer. Also, if you use this command in a different window -displaying the same buffer, that window will be used instead to display -the current definition in the future. +Move point back to the current stop point in the source code buffer +(@code{edebug-where}). + +If you use this command in a different window displaying the same +buffer, that window will be used instead to display the current +definition in the future. @item W @c Its function is not simply to forget the saved configuration -- dan @@ -842,11 +844,10 @@ It also appends a newline to separate entries. @end defun - @code{edebug-tracing} and @code{edebug-trace} insert lines in the trace -buffer even if Edebug is not active. - - Adding text to the trace buffer also scrolls its window to show the -last lines inserted. + @code{edebug-tracing} and @code{edebug-trace} insert lines in the +trace buffer whenever they are called, even if Edebug is not active. +Adding text to the trace buffer also scrolls its window to show the last +lines inserted. @node Coverage Testing @subsection Coverage Testing @@ -855,18 +856,22 @@ @cindex frequency counts @cindex performance analysis Edebug provides rudimentary coverage testing and display of execution -frequency. Coverage testing works by comparing the result of each -expression with the previous result; coverage is considered OK if two -different results are found. Thus, to sufficiently test the coverage of -your code, try to execute it under conditions that evaluate all -expressions more than once, and produce different results for each -expression. Coverage testing makes execution slower, so it is only done -if @code{edebug-test-coverage} is non-@code{nil}. Whether or not -coverage testing is enabled, frequency counting is performed for all -execution of an instrumented function, even if the execution mode is -Go-nonstop. +frequency. -Use @kbd{M-x edebug-display-freq-count} to display both the + Coverage testing works by comparing the result of each expression with +the previous result; each form in the program is considered ``covered'' +if it has returned two different values since you began testing coverage +in the current Emacs session. Thus, to do coverage testing on your +program, execute it under various conditions and note whether it behaves +correctly; Edebug will tell you when you have tried enough different +conditions that each form has returned two different values. + + Coverage testing makes execution slower, so it is only done if +@code{edebug-test-coverage} is non-@code{nil}. Whether or not coverage +testing is enabled, frequency counting is performed for all execution of +an instrumented function, even if the execution mode is Go-nonstop. + + Use @kbd{M-x edebug-display-freq-count} to display both the coverage information and the frequency counts for a definition. @deffn Command edebug-display-freq-count @@ -882,7 +887,7 @@ The character @samp{=} following the count for an expression says that the expression has returned the same value each time it was evaluated. -This is the only coverage information that Edebug records. +In other words, it is not yet ``covered'' for coverage testing purposes. To clear the frequency count and coverage data for a definition, simply reinstrument it with @code{eval-defun}. @@ -1073,7 +1078,7 @@ @end deffn Here is a simple example that defines the specification for the -@code{for} example macro (@code{Argument Evaluation}), followed by an +@code{for} example macro (@pxref{Argument Evaluation}), followed by an alternative, equivalent specification. @example @@ -1143,7 +1148,7 @@ @table @code @item sexp -A single unevaluated expression, which is not instrumented. +A single unevaluated Lisp object, which is not instrumented. @c an "expression" is not necessarily intended for evaluation. @item form @@ -1180,8 +1185,8 @@ @item &rest @kindex &rest @r{(Edebug)} All following elements in the specification list are repeated zero or -more times. All the elements need not match in the last repetition, -however. +more times. In the last repetition, however, it is ok if the expression +runs out before matching all of the elements of the specification list. To repeat only a few elements, use @code{[&rest @var{specs}@dots{}]}. To specify several elements that must all match on every repetition, use
--- a/lispref/elisp.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/elisp.texi Tue May 26 18:56:56 1998 +0000 @@ -66,11 +66,10 @@ @titlepage @title GNU Emacs Lisp Reference Manual -@subtitle GNU Emacs Version 20 -@subtitle for Unix Users +@subtitle For Emacs Version 20.3 @c The edition number appears in several places in this file @c and also in the file intro.texi. -@subtitle Revision 2.5, February 1998 +@subtitle Revision 2.5, May 1998 @author by Bil Lewis, Dan LaLiberte, Richard Stallman @author and the GNU Manual Group @@ -81,9 +80,9 @@ @sp 2 Edition 2.5 @* Revised for Emacs Version 20.3,@* -February 1998.@* +May 1998.@* @sp 2 -ISBN 1-882114-71-X +ISBN 1-882114-72-8 @sp 2 Published by the Free Software Foundation @* @@ -271,7 +270,7 @@ * Process Type:: A process running on the underlying OS. * Stream Type:: Receive or send characters. * Keymap Type:: What function a keystroke invokes. -* Overlay Type:: How an overlay is represented. +* Overlay Type:: How an overlay is represented. Numbers @@ -292,7 +291,7 @@ * Creating Strings:: Functions to allocate new strings. * Text Comparison:: Comparing characters or strings. * String Conversion:: Converting characters or strings and vice versa. -* Formatting Strings:: @code{format}: Emacs's analog of @code{printf}. +* Formatting Strings:: @code{format}: Emacs's analogue of @code{printf}. * Case Conversion:: Case conversion functions. Lists @@ -454,7 +453,7 @@ * Enabling Advice:: You can enable or disable each piece of advice. * Preactivation:: Preactivation is a way of speeding up the loading of compiled advice. -* Argument Access:: How advice can access the function's arguments. +* Argument Access in Advice:: How advice can access the function's arguments. * Subr Arguments:: Accessing arguments when advising a primitive. * Combined Definition:: How advice is implemented. @@ -692,14 +691,14 @@ * Input Focus:: Specifying the selected frame. * Visibility of Frames:: Frames may be visible or invisible, or icons. * Raising and Lowering:: Raising a frame makes it hide other X windows; - lowering it makes the others hide them. + lowering it puts it underneath the others. * Frame Configurations:: Saving the state of all frames. * Mouse Tracking:: Getting events that say when the mouse moves. * Mouse Position:: Asking where the mouse is, or moving it. * Pop-Up Menus:: Displaying a menu for the user to select from. * Dialog Boxes:: Displaying a box to ask yes or no. * Pointer Shapes:: Specifying the shape of the mouse pointer. -* Window System Selections::Transferring text to and from other X clients. +* Window System Selections::Transferring text to and from other window. * Color Names:: Getting the definitions of color names. * Resources:: Getting resource values from the server. * Server Data:: Getting info about the X server.
--- a/lispref/errors.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/errors.texi Tue May 26 18:56:56 1998 +0000 @@ -55,7 +55,7 @@ @xref{Read Only Buffers}. @item cyclic-function-indirection -@code{"Symbol's chain of function indirections contains a loop"}@* +@code{"Symbol's chain of function indirections@* contains a loop"}@* @xref{Function Indirection}. @item end-of-buffer
--- a/lispref/frames.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/frames.texi Tue May 26 18:56:56 1998 +0000 @@ -50,12 +50,15 @@ * Pointer Shapes:: Specifying the shape of the mouse pointer. * Window System Selections:: Transferring text to and from other X clients. * Font Names:: Looking up font names. +* Fontsets:: A fontset is a collection of fonts + for displaying various character sets. * Color Names:: Getting the definitions of color names. * Resources:: Getting resource values from the server. * Server Data:: Getting info about the X server. @end menu - @xref{Display}, for related information. + @xref{Display}, for information about the related topic of +controlling Emacs redisplay. @node Creating Frames @section Creating Frames @@ -92,11 +95,10 @@ @node Multiple Displays @section Multiple Displays -@cindex multiple displays -@cindex multiple X terminals +@cindex multiple X displays @cindex displays, multiple - A single Emacs can talk to more than one X Window display. + A single Emacs can talk to more than one X display. Initially, Emacs uses just one display---the one chosen with the @code{DISPLAY} environment variable or with the @samp{--display} option (@pxref{Initial Options,,, emacs, The GNU Emacs Manual}). To connect to @@ -104,16 +106,18 @@ the @code{display} frame parameter when you create the frame. Emacs treats each X server as a separate terminal, giving each one its -own selected frame and its own minibuffer windows. A few Lisp variables -have values local to the current terminal (that is, the terminal -corresponding to the currently selected frame): these are -@code{default-minibuffer-frame}, @code{defining-kbd-macro}, -@code{last-kbd-macro}, and @code{system-key-alist}. These variables are -always terminal-local and can never be buffer-local or frame-local -(@pxref{Buffer-Local Variables}). +own selected frame and its own minibuffer windows. + + A few Lisp variables are @dfn{terminal-local}; that is, they have a +separate binding for each terminal. The binding in effect at any time +is the one for the terminal that the currently selected frame belongs +to. These variables include @code{default-minibuffer-frame}, +@code{defining-kbd-macro}, @code{last-kbd-macro}, and +@code{system-key-alist}. They are always terminal-local, and can never +be buffer-local (@pxref{Buffer-Local Variables}) or frame-local. A single X server can handle more than one screen. A display name -@samp{@var{host}.@var{server}.@var{screen}} has three parts; the last +@samp{@var{host}:@var{server}.@var{screen}} has three parts; the last part specifies the screen number for a given server. When you use two screens belonging to one server, Emacs knows by the similarity in their names that they share a single keyboard, and it treats them as a single @@ -164,8 +168,8 @@ uses. Frame parameters exist for the sake of window systems. A terminal frame -has a few parameters, mostly for compatibility's sake; only the height, -width, @code{name}, @code{title}, @code{buffer-list} and +has a few parameters, mostly for compatibility's sake; only the @code{height}, +@code{width}, @code{name}, @code{title}, @code{buffer-list} and @code{buffer-predicate} parameters do something special. @menu @@ -418,9 +422,20 @@ The color to use for the image of a character. This is a string; the window system defines the meaningful color names. +If you set the @code{foreground-color} frame parameter, you should +call @code{frame-update-face-colors} to update faces accordingly. + @item background-color The color to use for the background of characters. +If you set the @code{background-color} frame parameter, you should +call @code{frame-update-face-colors} to update faces accordingly. +@xref{Face Functions}. + +@item background-mode +This parameter is either @code{dark} or @code{light}, according +to whether the background color is a light one or a dark one. + @item mouse-color The color for the mouse pointer. @@ -430,6 +445,11 @@ @item border-color The color for the border of the frame. +@item display-type +This parameter describes the range of possible colors that can be used +in this frame. Its value is @code{color}, @code{grayscale} or +@code{mono}. + @item cursor-type The way to display the cursor. The legitimate values are @code{bar}, @code{box}, and @code{(bar . @var{width})}. The symbol @code{box} @@ -470,6 +490,10 @@ @node Size and Position @subsection Frame Size And Position +@cindex size of frame +@cindex screen size +@cindex frame size +@cindex resize frame You can read or change the size and position of a frame using the frame parameters @code{left}, @code{top}, @code{height}, and @@ -481,15 +505,28 @@ @defun set-frame-position frame left top This function sets the position of the top left corner of @var{frame} to @var{left} and @var{top}. These arguments are measured in pixels, and -count from the top left corner of the screen. Negative parameter values -count up or rightward from the top left corner of the screen. +normally count from the top left corner of the screen. + +Negative parameter values position the bottom edge of the window up from +the bottom edge of the screen, or the right window edge to the left of +the right edge of the screen. It would probably be better if the values +were always counted from the left and top, so that negative arguments +would position the frame partly off the top or left edge of the screen, +but it seems inadvisable to change that now. @end defun @defun frame-height &optional frame @defunx frame-width &optional frame These functions return the height and width of @var{frame}, measured in -characters. If you don't supply @var{frame}, they use the selected -frame. +lines and columns. If you don't supply @var{frame}, they use the +selected frame. +@end defun + +@defun screen-height +@defunx screen-width +These functions are old aliases for @code{frame-height} and +@code{frame-width}. When you are using a non-window terminal, the size +of the frame is normally the same as the size of the terminal screen. @end defun @defun frame-pixel-height &optional frame @@ -515,15 +552,38 @@ them to units of characters. @end defun +@defun set-frame-height frame lines &optional pretend +This function resizes @var{frame} to a height of @var{lines} lines. The +sizes of existing windows in @var{frame} are altered proportionally to +fit. + +If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines} +lines of output in @var{frame}, but does not change its value for the +actual height of the frame. This is only useful for a terminal frame. +Using a smaller height than the terminal actually implements may be +useful to reproduce behavior observed on a smaller screen, or if the +terminal malfunctions when using its whole screen. Setting the frame +height ``for real'' does not always work, because knowing the correct +actual size may be necessary for correct cursor positioning on a +terminal frame. +@end defun + +@defun set-frame-width frame width &optional pretend +This function sets the width of @var{frame}, measured in characters. +The argument @var{pretend} has the same meaning as in +@code{set-frame-height}. +@end defun + +@findex set-screen-height +@findex set-screen-width The old-fashioned functions @code{set-screen-height} and @code{set-screen-width}, which were used to specify the height and width of the screen in Emacs versions that did not support multiple frames, -are still usable. They apply to the selected frame. @xref{Screen -Size}. +are still usable. They apply to the selected frame. @defun x-parse-geometry geom @cindex geometry specification -The function @code{x-parse-geometry} converts a standard X Windows +The function @code{x-parse-geometry} converts a standard X window geometry string to an alist that you can use as part of the argument to @code{make-frame}. @@ -562,17 +622,11 @@ @example (x-parse-geometry "35x70+0-0") - @result{} ((width . 35) (height . 70) - (left . 0) (top - 0)) + @result{} ((height . 70) (width . 35) + (top - 0) (left . 0)) @end example @end defun -@ignore -New functions @code{set-frame-height} and @code{set-frame-width} set the -size of a specified frame. The frame is the first argument; the size is -the second. -@end ignore - @node Frame Titles @section Frame Titles @@ -768,8 +822,7 @@ to switch frames, and the change lasts until overridden by a subsequent call to @code{switch-frame}. Each terminal screen except for the initial one has a number, and the number of the selected frame appears -in the mode line after the word @samp{Emacs} (@pxref{Mode Line -Variables}). +in the mode line before the buffer name (@pxref{Mode Line Variables}). @c ??? This is not yet implemented properly. @defun select-frame frame @@ -1283,7 +1336,7 @@ when you specify the ``font'' for a frame or a face. Here is information about defining a fontset under Lisp program control. -@defun create-fontset-from-fontset-spec fontset-spec &optional style noerror +@defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror This function defines a new fontset according to the specification string @var{fontset-spec}. The string should have this format: @@ -1298,22 +1351,23 @@ a standard X font name, except that the last two fields should be @samp{fontset-@var{alias}}. -Each fontset has two names, one long and one short. The long name is +The new fontset has two names, one long and one short. The long name is @var{fontpattern} in its entirety. The short name is @samp{fontset-@var{alias}}. You can refer to the fontset by either name. If a fontset with the same name already exists, an error is signaled, unless @var{noerror} is non-@code{nil}, in which case this function does nothing. +If optional argument @var{style-variant-p} is non-@code{nil}, that says +to create bold, italic and bold-italic variants of the fontset as well. +These variant fontsets do not have a short name, only a long one, which +is made by altering @var{fontpattern} to indicate the bold or italic +status. + The specification string also says which fonts to use in the fontset. See below for the details. @end defun - If optional argument @var{style} is specified, it specifies a way to -modify the fontset. It should be one of @code{bold}, @code{italic}, and -@code{bold-italic}, and it says to find the bold, italic or bold-italic -version of each font if possible. - The construct @samp{@var{charset}:@var{font}} specifies which font to use (in this fontset) for one particular character set. Here, @var{charset} is the name of a character set, and @var{font} is the font @@ -1354,7 +1408,7 @@ You may not have any Chinese font matching the above font specification. Most X distributions include only Chinese fonts that -have @samp{song ti} or @samp{fangsong ti} in @var{family} field. In +have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In such a case, @samp{Fontset-@var{n}} can be specified as below: @smallexample @@ -1415,7 +1469,7 @@ @end example The color values are returned for @var{frame}'s display. If @var{frame} -is omitted or @code{nil}, the information is return for the selected +is omitted or @code{nil}, the information is returned for the selected frame's display. @end defun
--- a/lispref/help.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/help.texi Tue May 26 18:56:56 1998 +0000 @@ -99,15 +99,15 @@ @c Wordy to prevent overfull hbox. --rjc 15mar92 The @file{emacs/lib-src} directory contains two utilities that you can use to print nice-looking hardcopy for the file -@file{emacs/etc/DOC-@var{version}}. These are @file{sorted-doc.c} and -@file{digest-doc.c}. +@file{emacs/etc/DOC-@var{version}}. These are @file{sorted-doc} and +@file{digest-doc}. @node Accessing Documentation @section Access to Documentation Strings @defun documentation-property symbol property &optional verbatim This function returns the documentation string that is recorded -@var{symbol}'s property list under property @var{property}. It +in @var{symbol}'s property list under property @var{property}. It retrieves the text from a file if necessary, and runs @code{substitute-command-keys} to substitute actual key bindings. (This substitution is not done if @var{verbatim} is non-@code{nil}.) @@ -116,7 +116,7 @@ @group (documentation-property 'command-line-processed 'variable-documentation) - @result{} "t once command line has been processed" + @result{} "Non-nil once command line has been processed" @end group @group (symbol-plist 'command-line-processed) @@ -218,7 +218,7 @@ @c That makes them incorrect. @group -set-goal-column Command: C-x C-n +set-goal-column Keys: C-x C-n Set the current horizontal position as a goal for C-n and C-p. @end group @c DO NOT put a blank line here! That is factually inaccurate! @@ -496,7 +496,7 @@ @code{help-form} is a non-@code{nil} Lisp expression, it evaluates that expression, and displays the result in a window if it is a string. -Usually the value of @code{help-form}'s value is @code{nil}. Then the +Usually the value of @code{help-form} is @code{nil}. Then the help character has no special meaning at the level of command input, and it becomes part of a key sequence in the normal way. The standard key binding of @kbd{C-h} is a prefix key for several general-purpose help
--- a/lispref/intro.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/intro.texi Tue May 26 18:56:56 1998 +0000 @@ -491,10 +491,6 @@ Emacs maintainers more quickly, send mail to @code{bug-gnu-emacs@@gnu.org}. -@display - --Bil Lewis, Dan LaLiberte, Richard Stallman -@end display - @node Lisp History @section Lisp History @cindex Lisp history
--- a/lispref/keymaps.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/keymaps.texi Tue May 26 18:56:56 1998 +0000 @@ -338,7 +338,8 @@ also stored in the variable @code{ctl-x-map}. This keymap defines bindings for key sequences starting with @kbd{C-x}. - Here is a list of the standard prefix keys of Emacs and their keymaps: + Some of the standard Emacs prefix keys use keymaps that are +also found in Lisp variables: @itemize @bullet @item @@ -370,6 +371,12 @@ @code{Control-X-prefix}. @item +@cindex @kbd{C-x @key{RET}} +@vindex mule-keymap +@code{mule-keymap} is the global keymap used for the @kbd{C-x @key{RET}} +prefix key. + +@item @cindex @kbd{C-x 4} @vindex ctl-x-4-map @code{ctl-x-4-map} is the global keymap used for the @kbd{C-x 4} prefix @@ -384,11 +391,28 @@ @c Emacs 19 feature @item -@cindex @kbd{C-x n} -@cindex @kbd{C-x r} -@cindex @kbd{C-x a} -The prefix keys @kbd{C-x n}, @kbd{C-x r} and @kbd{C-x a} use keymaps -that have no special names. +@cindex @kbd{C-x 6} +@vindex 2C-mode-map +@code{2C-mode-map} is the global keymap used for the @kbd{C-x 6} prefix +key. + +@item +@cindex @kbd{C-x v} +@vindex vc-prefix-map +@code{vc-prefix-map} is the global keymap used for the @kbd{C-x v} prefix +key. + +@item +@cindex @kbd{M-g} +@vindex facemenu-keymap +@code{facemenu-keymap} is the global keymap used for the @kbd{M-g} +prefix key. + +@c Emacs 19 feature +@item +The other Emacs prefix keys are @kbd{C-x @@}, @kbd{C-x a i}, @kbd{C-x +@key{ESC}} and @kbd{@key{ESC} @key{ESC}}. They use keymaps that have no +special names. @end itemize The keymap binding of a prefix key is used for looking up the event @@ -615,7 +639,7 @@ elements of @code{minor-mode-map-alist}: @code{(@var{variable} . @var{keymap})}. -If a variable appears an element of +If a variable appears as an element of @code{minor-mode-overriding-map-alist}, the map specified by that element totally replaces any map specified for the same variable in @code{minor-mode-map-alist}. @@ -1179,16 +1203,15 @@ @smallexample @group - @dots{} - (setq dired-mode-map (make-keymap)) - (suppress-keymap dired-mode-map) - (define-key dired-mode-map "r" 'dired-rename-file) - (define-key dired-mode-map "\C-d" 'dired-flag-file-deleted) - (define-key dired-mode-map "d" 'dired-flag-file-deleted) - (define-key dired-mode-map "v" 'dired-view-file) - (define-key dired-mode-map "e" 'dired-find-file) - (define-key dired-mode-map "f" 'dired-find-file) - @dots{} +(setq dired-mode-map (make-keymap)) +(suppress-keymap dired-mode-map) +(define-key dired-mode-map "r" 'dired-rename-file) +(define-key dired-mode-map "\C-d" 'dired-flag-file-deleted) +(define-key dired-mode-map "d" 'dired-flag-file-deleted) +(define-key dired-mode-map "v" 'dired-view-file) +(define-key dired-mode-map "e" 'dired-find-file) +(define-key dired-mode-map "f" 'dired-find-file) +@dots{} @end group @end smallexample @end defun
--- a/lispref/loading.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/loading.texi Tue May 26 18:56:56 1998 +0000 @@ -148,7 +148,8 @@ functions should use @code{read}. @end defvar - For how @code{load} is used to build Emacs, see @ref{Building Emacs}. + For information about how @code{load} is used in building Emacs, see +@ref{Building Emacs}. @node Library Search @section Library Search @@ -176,16 +177,15 @@ Here is an example of how to set your @code{EMACSLOADPATH} variable from a @code{csh} @file{.login} file: -@c This overfull hbox is OK. --rjc 16mar92 @smallexample -setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/lib/emacs/lisp +setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/lib/emacs/20.3/lisp @end smallexample Here is how to set it using @code{sh}: @smallexample export EMACSLOADPATH -EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp +EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/20.3/lisp @end smallexample Here is an example of code you can place in a @file{.emacs} file to add
--- a/lispref/markers.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/markers.texi Tue May 26 18:56:56 1998 +0000 @@ -316,9 +316,9 @@ @defun set-marker-insertion-type marker type @tindex set-marker-insertion-type This function sets the insertion type of marker @var{marker} to -@var{type}. If @var{type} is @code{t}, @var{marker} will advances when -text is inserted at it. If @var{type} is @code{nil}, @var{marker} does -not advance when text is inserted there. +@var{type}. If @var{type} is @code{t}, @var{marker} will advance when +text is inserted at its position. If @var{type} is @code{nil}, +@var{marker} does not advance when text is inserted there. @end defun @defun marker-insertion-type marker
--- a/lispref/minibuf.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/minibuf.texi Tue May 26 18:56:56 1998 +0000 @@ -38,7 +38,7 @@ to minibuffers. The name of a minibuffer always has the form @w{@samp{ *Minibuf-@var{number}}}, and it cannot be changed. Minibuffers are displayed only in special windows used only for minibuffers; these -windows always appear at the bottom of a frame. (Sometime frames have +windows always appear at the bottom of a frame. (Sometimes frames have no minibuffer window, and sometimes a special kind of frame contains nothing but a minibuffer window; see @ref{Minibuffers and Frames}.) @@ -136,10 +136,10 @@ properties are stripped when the value is returned. If the argument @var{inherit-input-method} is non-@code{nil}, then the -minibuffer inherits the current buffer's input method (@pxref{Input -Methods}) and the setting of @code{enable-multibyte-characters} -(@pxref{Text Representations}) from whichever buffer was current before -entering the minibuffer. +minibuffer inherits the current input method (@pxref{Input Methods}) and +the setting of @code{enable-multibyte-characters} (@pxref{Text +Representations}) from whichever buffer was current before entering the +minibuffer. If @var{initial-contents} is a string, @code{read-from-minibuffer} inserts it into the minibuffer, leaving point at the end, before the @@ -191,10 +191,13 @@ @end defun @defvar minibuffer-allow-text-properties -If this variable is non-@code{nil}, then @code{read-from-minibuffer} -strips all text properties from the string before returning the string. +If this variable is @code{nil}, then @code{read-from-minibuffer} strips +all text properties from the minibuffer input before returning it. Since all minibuffer input uses @code{read-from-minibuffer}, this variable applies to all minibuffer input. + +Note that the completion functions discard text properties unconditionally, +regardless of the value of this variable. @end defvar @defvar minibuffer-local-map @@ -679,7 +682,7 @@ In most cases, we recommend using @var{default}, and not @var{initial}. If the argument @var{inherit-input-method} is non-@code{nil}, then the -minibuffer inherits the current buffer's input method (@pxref{Input +minibuffer inherits the current input method (@pxref{Input Methods}) and the setting of @code{enable-multibyte-characters} (@pxref{Text Representations}) from whichever buffer was current before entering the minibuffer. @@ -1003,7 +1006,7 @@ @end defun See also the functions @code{read-coding-system} and -@code{read-non-nil-coding-system}, in @ref{Lisp and Coding Systems}. +@code{read-non-nil-coding-system}, in @ref{User-Chosen Coding Systems}. @node Reading File Names @subsection Reading File Names @@ -1035,7 +1038,7 @@ @c Emacs 19 feature If you specify @var{initial}, that is an initial file name to insert in -the buffer (after with @var{directory}, if that is inserted). In this +the buffer (after @var{directory}, if that is inserted). In this case, point goes at the beginning of @var{initial}. The default for @var{initial} is @code{nil}---don't insert any file name. To see what @var{initial} does, try the command @kbd{C-x C-v}. @strong{Note:} we
--- a/lispref/modes.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/modes.texi Tue May 26 18:56:56 1998 +0000 @@ -60,7 +60,7 @@ Rmail Edit mode offers an example of changing the major mode temporarily for a buffer, so it can be edited in a different way (with -ordinary Emacs commands rather than Rmail). In such cases, the +ordinary Emacs commands rather than Rmail commands). In such cases, the temporary major mode usually has a command to switch back to the buffer's usual mode (Rmail mode, in this case). You might be tempted to present the temporary redefinitions inside a recursive edit and restore @@ -823,11 +823,11 @@ Make a variable whose name ends in @samp{-mode} to control the minor mode. We call this the @dfn{mode variable}. The minor mode command should set this variable (@code{nil} to disable; anything else to -enable.) +enable). If it is possible, implement the mode so that setting the variable automatically enables or disables the mode. Then the minor mode command -does not need to do anything except the variable. +does not need to do anything except set the variable. This variable is used in conjunction with the @code{minor-mode-alist} to display the minor mode name in the mode line. It can also enable @@ -887,6 +887,9 @@ @end smallexample @end itemize + You can also use @code{add-to-list} to add an element to this list +just once (@pxref{Setting Variables}). + @node Keymaps and Minor Modes @subsection Keymaps and Minor Modes @@ -1135,6 +1138,11 @@ @end group @end example +@noindent +(The variables @code{line-number-mode}, @code{column-number-mode} +and @code{which-func-mode} enable particular minor modes; as usual, +these variable names are also the minor mode command names.) + @node Mode Line Variables @subsection Variables Used in the Mode Line @@ -1174,12 +1182,8 @@ @defvar mode-line-buffer-identification This variable identifies the buffer being displayed in the window. Its -default value is @code{("%12b")}, which means that it usually -displays @samp{Emacs:} followed by seventeen characters of the buffer -name. (In a terminal frame, it displays the frame name instead of -@samp{Emacs}; this has the effect of showing the frame number.) You may -want to change this in modes such as Rmail that do not behave like a -``normal'' Emacs. +default value is @code{("%12b")}, which means that it usually displays +twelve characters of the buffer name. @end defvar @defvar global-mode-string @@ -1240,7 +1244,7 @@ status in modes used for communicating with subprocesses. It is displayed immediately following the major mode name, with no intervening space. For example, its value in the @samp{*shell*} buffer is -@code{(":@: %s")}, which allows the shell to display its status along +@code{(":%s")}, which allows the shell to display its status along with the major mode as: @samp{(Shell:@: run)}. Normally this variable is @code{nil}. @end defvar @@ -1456,8 +1460,8 @@ @defvar imenu-syntax-alist This variable is an alist of syntax table modifiers to use while -executing @code{imenu--generic-function} to override the syntax table of -the current buffer. Each element should have this form: +processing @code{imenu-generic-expression}, to override the syntax table +of the current buffer. Each element should have this form: @example (@var{characters} . @var{syntax-description}) @@ -1478,7 +1482,7 @@ @end example The @code{imenu-generic-expression} patterns can then use @samp{\\sw+} -instead of @samp{\\(\\sw\\|\\s_\\)\\}. Note that this technique may be +instead of @samp{\\(\\sw\\|\\s_\\)+}. Note that this technique may be inconvenient to use when the mode needs to limit the initial character of a name to a smaller set of characters @@ -2081,7 +2085,9 @@ This function is the way to run an abnormal hook which passes arguments to the hook functions, and stops as soon as any hook function fails. It calls each of the hook functions, passing each of them the arguments -@var{args}, until some hook function returns @code{nil}. Then it stops. +@var{args}, until some hook function returns @code{nil}. Then it stops, +and returns @code{nil} if some hook function did, and otherwise +returns a non-@code{nil} value. @end defun @defun run-hook-with-args-until-success hook &rest args @@ -2089,7 +2095,8 @@ to the hook functions, and stops as soon as any hook function succeeds. It calls each of the hook functions, passing each of them the arguments @var{args}, until some hook function returns non-@code{nil}. Then it -stops. +stops, and returns whatever was returned by the last hook function +that was called. @end defun @defun add-hook hook function &optional append local
--- a/lispref/nonascii.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/nonascii.texi Tue May 26 18:56:56 1998 +0000 @@ -46,13 +46,14 @@ @cindex leading code @cindex multibyte text +@cindex trailing codes In multibyte representation, a character may occupy more than one byte, and as a result, the full range of Emacs character codes can be stored. The first byte of a multibyte character is always in the range 128 through 159 (octal 0200 through 0237). These values are called @dfn{leading codes}. The second and subsequent bytes of a multibyte character are always in the range 160 through 255 (octal 0240 through -0377). +0377); these values are @dfn{trailing codes}. In a buffer, the buffer-local value of the variable @code{enable-multibyte-characters} specifies the representation used. @@ -156,14 +157,14 @@ @defun string-make-unibyte string @tindex string-make-unibyte This function converts the text of @var{string} to unibyte -representation, if it isn't already, and return the result. If +representation, if it isn't already, and returns the result. If @var{string} is a unibyte string, it is returned unchanged. @end defun @defun string-make-multibyte string @tindex string-make-multibyte This function converts the text of @var{string} to multibyte -representation, if it isn't already, and return the result. If +representation, if it isn't already, and returns the result. If @var{string} is a multibyte string, it is returned unchanged. @end defun @@ -280,18 +281,18 @@ @cindex dimension (of character set) In multibyte representation, each character occupies one or more bytes. Each character set has an @dfn{introduction sequence}, which is -one or two bytes long. The introduction sequence is the beginning of -the byte sequence for any character in the character set. (The -@sc{ASCII} character set has a zero-length introduction sequence.) The -rest of the character's bytes distinguish it from the other characters -in the same character set. Depending on the character set, there are -either one or two distinguishing bytes; the number of such bytes is -called the @dfn{dimension} of the character set. +normally one or two bytes long. (Exception: the @sc{ASCII} character +set has a zero-length introduction sequence.) The introduction sequence +is the beginning of the byte sequence for any character in the character +set. The rest of the character's bytes distinguish it from the other +characters in the same character set. Depending on the character set, +there are either one or two distinguishing bytes; the number of such +bytes is called the @dfn{dimension} of the character set. @defun charset-dimension charset @tindex charset-dimension This function returns the dimension of @var{charset}; -At present, the dimension is always 1 or 2. +at present, the dimension is always 1 or 2. @end defun This is the simplest way to determine the byte length of a character @@ -481,6 +482,7 @@ * Coding System Basics:: * Encoding and I/O:: * Lisp and Coding Systems:: +* User-Chosen Coding Systems:: * Default Coding Systems:: * Specifying Coding Systems:: * Explicit Encoding:: @@ -559,7 +561,7 @@ @node Encoding and I/O @subsection Encoding and I/O - The principal purpose coding systems is for use in reading and + The principal purpose of coding systems is for use in reading and writing files. The function @code{insert-file-contents} uses a coding system for decoding the file data, and @code{write-region} uses one to encode the buffer contents. @@ -632,7 +634,7 @@ @defun coding-system-change-eol-conversion coding-system eol-type @tindex coding-system-change-eol-conversion This function returns a coding system which is like @var{coding-system} -except for its in eol conversion, which is specified by @code{eol-type}. +except for its eol conversion, which is specified by @code{eol-type}. @var{eol-type} should be @code{unix}, @code{dos}, @code{mac}, or @code{nil}. If it is @code{nil}, the returned coding system determines the end-of-line conversion from the data. @@ -694,6 +696,31 @@ operates on the contents of @var{string} instead of bytes in the buffer. @end defun + @xref{Process Information}, for how to examine or set the coding +systems used for I/O to a subprocess. + +@node User-Chosen Coding Systems +@subsection User-Chosen Coding Systems + +@tindex select-safe-coding-system +@defun select-safe-coding-system from to &optional preferred-coding-system +This function selects a coding system for encoding the between +@var{from} and @var{to}, asking the user to choose if necessary. + +The optional argument @var{preferred-coding-system} specifies a coding +system try first. If it can handle the text in the specified region, +then it is used. If this argument is omitted, the current buffer's +value of @code{buffer-file-coding-system} is tried first. + +If the region contains some multibyte characters that the preferred +coding system cannot encode, this function asks the user to choose from +a list of coding systems which can encode the text, and returns the +user's choice. + +One other kludgy feature: if @var{from} is a string, the string is the +target text, and @var{to} is ignored. +@end defun + Here are two functions you can use to let the user specify a coding system, with completion. @xref{Completion}. @@ -713,15 +740,12 @@ @xref{Coding Systems}. @end defun - @xref{Process Information}, for how to examine or set the coding -systems used for I/O to a subprocess. - @node Default Coding Systems @subsection Default Coding Systems This section describes variables that specify the default coding system for certain files or when running certain subprograms, and the -function which which I/O operations use to access them. +function that I/O operations use to access them. The idea of these variables is that you set them once and for all to the defaults you want, and then do not change them again. To specify a @@ -738,7 +762,7 @@ expression that matches certain file names. The element applies to file names that match @var{pattern}. -The @sc{cdr} of the element, @var{val}, should be either a coding +The @sc{cdr} of the element, @var{coding}, should be either a coding system, a cons cell containing two coding systems, or a function symbol. If @var{val} is a coding system, that coding system is used for both reading the file and writing it. If @var{val} is a cons cell containing @@ -763,7 +787,7 @@ @strong{Warning:} Coding systems such as @code{undecided} which determine the coding system from the data do not work entirely reliably -with asynchronous subprocess output. This is because Emacs processes +with asynchronous subprocess output. This is because Emacs handles asynchronous subprocess output in batches, as it arrives. If the coding system leaves the character code conversion unspecified, or leaves the end-of-line conversion unspecified, Emacs must try to detect the proper @@ -917,6 +941,15 @@ suppress encoding for that @code{write-region} call by binding @code{coding-system-for-write} to @code{no-conversion}. + Raw bytes sometimes contain overlong byte-sequences that look like a +proper multibyte character plus extra bytes containing trailing codes. +For most purposes, Emacs treats such a sequence in a buffer or string as +a single character, and if you look at its character code, you get the +value that corresponds to the multibyte character sequence---the extra +bytes are disregarded. This behavior is not quite clean, but raw bytes +are used only in limited places in Emacs, so as a practical matter +problems can be avoided. + @defun encode-coding-region start end coding-system @tindex encode-coding-region This function encodes the text from @var{start} to @var{end} according @@ -1092,12 +1125,14 @@ Each element defines one input method, and should have the form: @example -(@var{input-method} @var{language-env} @var{activate-func} @var{title} @var{description} @var{args}...) +(@var{input-method} @var{language-env} @var{activate-func} + @var{title} @var{description} @var{args}...) @end example -Here @var{input-method} is the input method name, a string; @var{env} is -another string, the name of the language environment this input method -is recommended for. (That serves only for documentation purposes.) +Here @var{input-method} is the input method name, a string; +@var{language-env} is another string, the name of the language +environment this input method is recommended for. (That serves only for +documentation purposes.) @var{title} is a string to display in the mode line while this method is active. @var{description} is a string describing this method and what @@ -1107,6 +1142,6 @@ @var{args}, if any, are passed as arguments to @var{activate-func}. All told, the arguments to @var{activate-func} are @var{input-method} and the @var{args}. -@end defun +@end defvar
--- a/lispref/os.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/os.texi Tue May 26 18:56:56 1998 +0000 @@ -19,6 +19,7 @@ * Getting Out:: How exiting works (permanent or temporary). * System Environment:: Distinguish the name and kind of system. * User Identification:: Finding the name and user id of the user. +* Reading a Password:: Reading a password from the terminal. * Time of Day:: Getting the current time. * Time Conversion:: Converting a time from numeric form to a string, or to calendrical data (or vice versa). @@ -195,6 +196,7 @@ @defvar site-run-file This variable specifies the site-customization file to load before the user's init file. Its normal value is @code{"site-start"}. +(The only way to change it with real effect is before dumping Emacs.) @end defvar If there is a great deal of code in your @file{.emacs} file, you @@ -214,12 +216,13 @@ @end defopt @defvar before-init-hook -This normal hook is run, once, just before loading of all the init files +This normal hook is run, once, just before loading all the init files (the user's init file, @file{default.el}, and/or @file{site-start.el}). +(The only way to change it with real effect is before dumping Emacs.) @end defvar @defvar after-init-hook -This normal hook is run, once, just after loading of all the init files +This normal hook is run, once, just after loading all the init files (the user's init file, @file{default.el}, and/or @file{site-start.el}), before the terminal-specific initialization. @end defvar @@ -568,6 +571,9 @@ system Emacs is operating on. Here is a table of the possible values: @table @code +@item alpha-vms +VMS on the Alpha. + @item aix-v3 AIX. @@ -727,13 +733,13 @@ @end defvar @defun load-average &optional use-float -This function returns the current 1-minute, 5-minute and 15-minute load -averages in a list. +This function returns the current 1-minute, 5-minute, and 15-minute load +averages, in a list. By default, the values are integers that are 100 times the system load averages, which indicate the average number of processes trying to run. If @var{use-float} is non-@code{nil}, then they are returned -as floating point numbers instead. +as floating point numbers and without multiplying by 100. @example @group @@ -864,6 +870,29 @@ This function returns the effective @sc{uid} of the user. @end defun +@node Reading a Password +@section Reading a Password +@cindex passwords, reading + + To read a password to pass to another program, you can use the +function @code{read-passwd}. + +@tindex read-passwd +@defun read-passwd prompt &optional confirm default +This function reads a password, prompting with @var{prompt}. It does +not echo the password as the user types it; instead, it echoes @samp{.} +for each character in the password. + +The optional argument @var{confirm}, if non-@code{nil}, says to read the +password twice and insist it must be the same both times. If it isn't +the same, the user has to type it over and over until the last two +times match. + +The optional argument @var{default} specifies the default password to +return if the user enters empty input. If @var{default} is @code{nil}, +then @code{read-passwd} returns the null string in that case. +@end defun + @node Time of Day @section Time of Day @@ -1129,7 +1158,7 @@ Emacs cannot run timers at any arbitrary point in a Lisp program; it can run them only when Emacs could accept output from a subprocess: namely, while waiting or inside certain primitive functions such as -@code{sit-for} or @code{read-char} which @emph{can} wait. Therefore, a +@code{sit-for} or @code{read-event} which @emph{can} wait. Therefore, a timer's execution may be delayed if Emacs is busy. However, the time of execution is very precise if Emacs is idle. @@ -1139,8 +1168,9 @@ later, and @var{args} are the arguments to give it when it is called. The time @var{time} is specified as a string. -Absolute times may be specified in a wide variety of formats, and tries -to accept all common date formats. Valid formats include these two, +Absolute times may be specified in a wide variety of formats; this +function tries to accept all the commonly used date formats. Valid +formats include these two, @example @var{year}-@var{month}-@var{day} @var{hour}:@var{min}:@var{sec} @var{timezone} @@ -1664,7 +1694,7 @@ servers; those do no harm, as long as they don't conflict with the ones used by the X server actually in use. -The variable is always local to the current X terminal and cannot be +The variable is always local to the current terminal, and cannot be buffer-local. @xref{Multiple Displays}. @end defvar @@ -1684,7 +1714,7 @@ @code{C-s} and @kbd{C-q} for flow control. Therefore, the choice of @kbd{C-s} and @kbd{C-q} as command characters for searching and quoting was natural and uncontroversial. With so many commands needing key -assignments. of course we assigned meanings to nearly all @sc{ASCII} +assignments, of course we assigned meanings to nearly all @sc{ASCII} control characters. Later, some terminals were introduced which required these characters
--- a/lispref/positions.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/positions.texi Tue May 26 18:56:56 1998 +0000 @@ -180,13 +180,15 @@ @deffn Command forward-word count This function moves point forward @var{count} words (or backward if -@var{count} is negative). More precisely, it keeps moving until it -moves across a word-constituent character and encounters a -word-separator character, then returns @code{t}. +@var{count} is negative). ``Moving one word'' means moving until point +crosses a word-constituent character and then encounters a +word-separator character (or the boundary of the accessible part of the +buffer). -If this motion encounters the beginning or end of the buffer, or the -limits of the accessible portion when narrowing is in effect, point -stops there and the value is @code{nil}. +If it is possible to move @var{count} words, without being stopped by +the buffer boundary (except perhaps after the last word), the value is +@code{t}. Otherwise, the return value is @code{nil} and point stops +at the buffer boundary. In an interactive call, @var{count} is set to the numeric prefix argument. @@ -657,7 +659,7 @@ given set of characters. It examines the character following point, then advances point if the character matches @var{character-set}. This continues until it reaches a character that does not match. The -function returns @code{nil}. +function returns the number of characters moved over. The argument @var{character-set} is like the inside of a @samp{[@dots{}]} in a regular expression except that @samp{]} is never @@ -699,6 +701,9 @@ This function moves point backward, skipping characters that match @var{character-set}, until @var{limit}. It is just like @code{skip-chars-forward} except for the direction of motion. + +The return value indicates the distance traveled. It is an integer that +is zero or less. @end defun @node Excursions @@ -765,7 +770,7 @@ @strong{Warning:} Ordinary insertion of text adjacent to the saved point value relocates the saved value, just as it relocates all markers. Therefore, when the saved point value is restored, it normally comes -after the inserted text. +before the inserted text. Although @code{save-excursion} saves the location of the mark, it does not prevent functions which modify the buffer from setting
--- a/lispref/processes.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/processes.texi Tue May 26 18:56:56 1998 +0000 @@ -79,12 +79,12 @@ Each of the subprocess-creating functions has a @var{buffer-or-name} argument which specifies where the standard output from the program will -go. It should be a buffer or a buffer name (which will create the -buffer if it does not already exist). It can also be @code{nil}, which -says to discard the output unless a filter function handles it. -(@xref{Filter Functions}, and @ref{Read and Print}.) Normally, you -should avoid having multiple processes send output to the same buffer -because their output would be intermixed randomly. +go. It should be a buffer or a buffer name; if it is a buffer name, +that will create the buffer if it does not already exist. It can also +be @code{nil}, which says to discard the output unless a filter function +handles it. (@xref{Filter Functions}, and @ref{Read and Print}.) +Normally, you should avoid having multiple processes send output to the +same buffer because their output would be intermixed randomly. @cindex program arguments All three of the subprocess-creating functions have a @code{&rest} @@ -102,14 +102,14 @@ @code{default-directory} (@pxref{File Name Expansion}). @cindex environment variables, subprocesses - The subprocess inherits its environment from Emacs; but you can + The subprocess inherits its environment from Emacs, but you can specify overrides for it with @code{process-environment}. @xref{System Environment}. @defvar exec-directory @pindex movemail The value of this variable is the name of a directory (a string) that -contains programs that come with GNU Emacs, that are intended for Emacs +contains programs that come with GNU Emacs, programs intended for Emacs to invoke. The program @code{movemail} is an example of such a program; Rmail uses it to fetch new mail from an inbox. @end defvar @@ -224,7 +224,7 @@ Emacs is essentially finished with the subprocess as soon as this function returns. -@item (@var{real-destination} @var{error-destination}) +@item @code{(@var{real-destination} @var{error-destination})} Keep the standard output stream separate from the standard error stream; deal with the ordinary output as specified by @var{real-destination}, and dispose of the error output according to @var{error-destination}. @@ -365,8 +365,8 @@ @section Creating an Asynchronous Process @cindex asynchronous subprocess - After an @dfn{asynchronous process} is created, Emacs and the Lisp -program both continue running immediately. The process thereafter runs + After an @dfn{asynchronous process} is created, Emacs and the subprocess +both continue running immediately. The process thereafter runs in parallel with Emacs, and the two can communicate with each other using the functions described in following sections. However, communication is only partially asynchronous: Emacs sends data to the @@ -484,13 +484,13 @@ away. If you delete a terminated process explicitly before it is deleted automatically, no harm results. -@defvar delete-exited-processes +@defopt delete-exited-processes This variable controls automatic deletion of processes that have terminated (due to calling @code{exit} or to a signal). If it is @code{nil}, then they continue to exist until the user runs @code{list-processes}. Otherwise, they are deleted immediately after they exit. -@end defvar +@end defopt @defun delete-process name This function deletes the process associated with @var{name}, killing it @@ -505,10 +505,15 @@ @end smallexample @end defun -@defun process-kill-without-query process -This function declares that Emacs need not query the user if -@var{process} is still running when Emacs is exited. The process will -be deleted silently. The value is @code{t}. +@defun process-kill-without-query process &optional do-query +This function specifies whether Emacs should query the user if +@var{process} is still running when Emacs is exited. If @var{do-query} +is @code{nil}, the process will be deleted silently. +Otherwise, Emacs will query about killing it. + +The value is @code{t} if the process was formerly set up to require +query. @code{nil} otherwise. A newly-created process always requires +query. @smallexample @group @@ -1145,9 +1150,7 @@ The argument @var{seconds} need not be an integer. If it is a floating point number, this function waits for a fractional number of seconds. Some systems support only a whole number of seconds; on these systems, -@var{seconds} is rounded down. If the system doesn't support waiting -fractions of a second, you get an error if you specify nonzero -@var{millisec}. +@var{seconds} is rounded down. Not all operating systems support waiting periods other than multiples of a second; on those that do not, you get an error if you specify
--- a/lispref/searching.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/searching.texi Tue May 26 18:56:56 1998 +0000 @@ -234,7 +234,7 @@ expression @samp{\(x+y*\)*a} to try to match the sequence @samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz}, before it ultimately fails. The slowness is because Emacs must try each imaginable way of grouping -the 35 @samp{x}'s before concluding that none of them can work. To make +the 35 @samp{x}s before concluding that none of them can work. To make sure your regular expressions run fast, check nested repetitions carefully. @@ -266,9 +266,9 @@ You can also include character ranges in a character alternative, by writing the starting and ending characters with a @samp{-} between them. -Thus, @samp{[a-z]} matches any lower-case ASCII letter. Ranges may be +Thus, @samp{[a-z]} matches any lower-case @sc{ASCII} letter. Ranges may be intermixed freely with individual characters, as in @samp{[a-z$%.]}, -which matches any lower case ASCII letter or @samp{$}, @samp{%} or +which matches any lower case @sc{ASCII} letter or @samp{$}, @samp{%} or period. You cannot always match all non-@sc{ASCII} characters with the regular @@ -280,9 +280,9 @@ representations, because only the @sc{ASCII} characters are excluded. The beginning and end of a range must be in the same character set -(@pxref{Character Sets}). Thus, @samp{[a-\x8c0]} is invalid because -@samp{a} is in the @sc{ASCII} character set but the character 0x8c0 -(@samp{A} with grave accent) is in the Emacs character set for Latin-1. +(@pxref{Character Sets}). Thus, @samp{[a-\x8e0]} is invalid because +@samp{a} is in the @sc{ASCII} character set but the character 0x8e0 +(@samp{a} with grave accent) is in the Emacs character set for Latin-1. Note that the usual regexp special characters are not special inside a character alternative. A completely different set of characters are @@ -1286,7 +1286,7 @@ You can save and restore the match data with @code{save-match-data}: @defmac save-match-data body@dots{} -This special form executes @var{body}, saving and restoring the match +This macro executes @var{body}, saving and restoring the match data around it. @end defmac
--- a/lispref/sequences.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/sequences.texi Tue May 26 18:56:56 1998 +0000 @@ -637,7 +637,7 @@ @defun set-char-table-range char-table range value @tindex set-char-table-range -This function set the value in @var{char-table} for a range of +This function sets the value in @var{char-table} for a range of characters @var{range}. Here are the possibilities for @var{range}: @table @asis @@ -678,11 +678,13 @@ here is how to examine each element of the syntax table: @example -(map-char-table - #'(lambda (key value) - (setq accumulator - (cons (list key value) accumulator))) - (syntax-table)) +(let (accumulator) + (map-char-table + #'(lambda (key value) + (setq accumulator + (cons (list key value) accumulator))) + (syntax-table)) + accumulator) @result{} ((475008 nil) (474880 nil) (474752 nil) (474624 nil) ... (5 (3)) (4 (3)) (3 (3)) (2 (3)) (1 (3)) (0 (3)))
--- a/lispref/streams.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/streams.texi Tue May 26 18:56:56 1998 +0000 @@ -390,11 +390,6 @@ @cindex print example @example @group -(setq m (set-marker (make-marker) 10 (get-buffer "foo"))) - @result{} #<marker at 10 in foo> -@end group - -@group ---------- Buffer: foo ---------- This is t@point{}he contents of foo. ---------- Buffer: foo ---------- @@ -404,10 +399,6 @@ @result{} "This is the output" @group -m - @result{} #<marker at 32 in foo> -@end group -@group ---------- Buffer: foo ---------- This is t "This is the output" @@ -431,8 +422,8 @@ @end group @group -m - @result{} #<marker at 11 in foo> +(setq m (copy-marker 10)) + @result{} #<marker at 10 in foo> @end group @group @@ -450,7 +441,7 @@ @group m - @result{} #<marker at 35 in foo> + @result{} #<marker at 34 in foo> @end group @end example @@ -723,6 +714,14 @@ @code{prin1}, but not during the printing of the result. @end defvar +@tindex print-escape-nonascii +@defvar print-escape-nonascii +If this variable is non-@code{nil}, then unibyte non-@sc{ASCII} +characters in strings are unconditionally printed as backslash sequences +by the print functions @code{prin1} and @code{print} that print with +quoting. +@end defvar + @defvar print-length @cindex printing limits The value of this variable is the maximum number of elements to print in
--- a/lispref/strings.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/strings.texi Tue May 26 18:56:56 1998 +0000 @@ -439,9 +439,9 @@ @var{start2} up to index @var{end2} (default, the end of the string). The strings are both converted to multibyte for the comparison -(@pxref{Text Representations}) so that a unibyte string can be usefully -compared with a multibyte string. If @var{ignore-case} is -non-@code{nil}, then case is ignored as well. +(@pxref{Text Representations}) so that a unibyte string can be equal to +a multibyte string. If @var{ignore-case} is non-@code{nil}, then case +is ignored, so that upper case letters can be equal to lower case letters. If the specified portions of the two strings match, the value is @code{t}. Otherwise, the value is an integer which indicates how many
--- a/lispref/syntax.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/syntax.texi Tue May 26 18:56:56 1998 +0000 @@ -362,7 +362,7 @@ @item @samp{*/} This is a comment-end sequence for ``a'' style because the first -character, @samp{*}, does not have the @samp{b} flag +character, @samp{*}, does not have the @samp{b} flag. @item newline This is a comment-end sequence for ``b'' style, because the newline @@ -542,10 +542,8 @@ mentioned in @var{syntaxes}. It stops when it encounters the end of the buffer, or position @var{limit} (if specified), or a character it is not supposed to skip. -@ignore @c may want to change this. The return value is the distance traveled, which is a nonnegative integer. -@end ignore @end defun @defun skip-syntax-backward syntaxes &optional limit @@ -553,10 +551,9 @@ classes are mentioned in @var{syntaxes}. It stops when it encounters the beginning of the buffer, or position @var{limit} (if specified), or a character it is not supposed to skip. -@ignore @c may want to change this. + The return value indicates the distance traveled. It is an integer that is zero or less. -@end ignore @end defun @defun backward-prefix-chars @@ -598,7 +595,7 @@ @var{stop-comment} is non-@code{nil}, parsing stops when it comes to the start of a comment. If @var{stop-comment} is the symbol @code{syntax-table}, parsing stops after the start of a comment or a -string, or the of a comment or a string, whichever comes first. +string, or the end of a comment or a string, whichever comes first. @cindex parse state The fifth argument @var{state} is a nine-element list of the same form @@ -893,7 +890,7 @@ @defun get-unused-category table This function returns a category name (a character) which is not currently defined in @var{table}. If all possible categories are in use -in @var{table}, it returns @code{nil}, +in @var{table}, it returns @code{nil}. @end defun @defun category-table
--- a/lispref/text.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/text.texi Tue May 26 18:56:56 1998 +0000 @@ -42,6 +42,7 @@ How to control how much information is kept. * Filling:: Functions for explicit filling. * Margins:: How to specify margins for filling commands. +* Adaptive Fill: Adaptive Fill mode chooses a fill prefix from context. * Auto Filling:: How auto-fill mode is implemented to break lines. * Sorting:: Functions for sorting parts of the buffer. * Columns:: Computing horizontal positions, and using them. @@ -62,11 +63,12 @@ Several simple functions are described here. See also @code{looking-at} in @ref{Regexp Search}. -@defun char-after position +@defun char-after &optional position This function returns the character in the current buffer at (i.e., immediately after) position @var{position}. If @var{position} is out of range for this purpose, either before the beginning of the buffer, or at -or beyond the end, then the value is @code{nil}. +or beyond the end, then the value is @code{nil}. The default for +@var{position} is point. In the following example, assume that the first character in the buffer is @samp{@@}: @@ -79,11 +81,12 @@ @end example @end defun -@defun char-before position +@defun char-before &optional position This function returns the character in the current buffer immediately before position @var{position}. If @var{position} is out of range for this purpose, either before the beginning of the buffer, or at or beyond -the end, then the value is @code{nil}. +the end, then the value is @code{nil}. The default for +@var{position} is point. @end defun @defun following-char @@ -449,9 +452,12 @@ @end deffn @defvar overwrite-mode -This variable controls whether overwrite mode is in effect: a -non-@code{nil} value enables the mode. It is automatically made -buffer-local when set in any fashion. +This variable controls whether overwrite mode is in effect. The value +should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary}, +or @code{nil}. @code{overwrite-mode-textual} specifies textual +overwrite mode (treats newlines and tabs specially), and +@code{overwrite-mode-binary} specifies binary overwrite mode (treats +newlines and tabs like any other characters). @end defvar @node Deletion @@ -467,7 +473,7 @@ All of the deletion functions operate on the current buffer, and all return a value of @code{nil}. -@defun erase-buffer +@deffn Command erase-buffer This function deletes the entire text of the current buffer, leaving it empty. If the buffer is read-only, it signals a @code{buffer-read-only} error. Otherwise, it deletes the text without asking for any @@ -478,7 +484,7 @@ @code{erase-buffer} does not do this, the idea being that the future text is not really related to the former text, and its size should not be compared with that of the former text. -@end defun +@end deffn @deffn Command delete-region start end This command deletes the text in the current buffer in the region @@ -779,6 +785,12 @@ text into the kill ring from a read-only buffer. @end deffn +@defopt kill-read-only-ok +If this option is non-@code{nil}, @code{kill-region} does not get an +error if the buffer is read-only. Instead, it simply returns, updating +the kill ring but not changing the buffer. +@end defopt + @deffn Command copy-region-as-kill start end This command saves the region defined by @var{start} and @var{end} on the kill ring (including text properties), but does not delete the text @@ -1000,10 +1012,11 @@ Here are the kinds of elements an undo list can have: @table @code -@item @var{integer} -This kind of element records a previous value of point. Ordinary cursor -motion does not get any sort of undo record, but deletion operations use -these entries to record where point was before the command. +@item @var{position} +This kind of element records a previous value of point; undoing this +element moves point to @var{position}. Ordinary cursor motion does not +make any sort of undo record, but deletion operations use these entries +to record where point was before the command. @item (@var{beg} . @var{end}) This kind of element indicates how to delete text that was inserted. @@ -1037,11 +1050,6 @@ @var{adjustment} character positions. Undoing this element moves @var{marker} @minus{} @var{adjustment} characters. -@item @var{position} -This element indicates where point was at an earlier time. Undoing this -element sets point to @var{position}. Deletion normally creates an -element of this kind as well as a reinsertion element. - @item nil This element is a boundary. The elements between two boundaries are called a @dfn{change group}; normally, each change group corresponds to @@ -1185,11 +1193,16 @@ boundaries. @xref{Paragraphs,,, emacs, The Emacs Manual}. @end deffn -@deffn Command fill-region start end &optional justify +@deffn Command fill-region start end &optional justify nosqueeze This command fills each of the paragraphs in the region from @var{start} to @var{end}. It justifies as well if @var{justify} is non-@code{nil}. +If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace +other than line breaks untouched. If @var{to-eop} is non-@code{nil}, +that means to keep filling to the end of the paragraph---or next hard +newline, if @code{use-hard-newlines} is enabled (see below). + The variable @code{paragraph-separate} controls how to distinguish paragraphs. @xref{Standard Regexps}. @end deffn @@ -1220,7 +1233,7 @@ described above. @end defopt -@deffn Command fill-region-as-paragraph start end &optional justify +@deffn Command fill-region-as-paragraph start end &optional justify nosqueeze squeeze-after This command considers a region of text as a single paragraph and fills it. If the region was made up of many paragraphs, the blank lines between paragraphs are removed. This function justifies as well as @@ -1228,11 +1241,13 @@ In an interactive call, any prefix argument requests justification. -@cindex Adaptive Fill mode -In Adaptive Fill mode, which is enabled by default, calling the function -@code{fill-region-as-paragraph} on an indented paragraph when there is -no fill prefix uses the indentation of the second line of the paragraph -as the fill prefix. +If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace +other than line breaks untouched. If @var{squeeze-after} is +non-@code{nil}, specifies a position in the region, and means don't +canonicalize spaces before that position. + +In Adaptive Fill mode, this command calls @code{fill-context-prefix} to +choose a fill prefix by default. @xref{Adaptive Fill}. @end deffn @deffn Command justify-current-line how eop nosqueeze @@ -1267,6 +1282,12 @@ the text around point. @end defun +@defopt sentence-end-double-space +If this variable is non-@code{nil}, a period followed by just one space +does not count as the end of a sentence, and the filling functions +avoid breaking the line at such a place. +@end defopt + @defvar fill-paragraph-function This variable provides a way for major modes to override the filling of paragraphs. If the value is non-@code{nil}, @code{fill-paragraph} calls @@ -1306,7 +1327,7 @@ The fill prefix follows the left margin whitespace, if any. @end defopt -@defvar fill-column +@defopt fill-column This buffer-local variable specifies the maximum width of filled lines. Its value should be an integer, which is a number of columns. All the filling, justification, and centering commands are affected by this @@ -1316,7 +1337,7 @@ read, you should set @code{fill-column} to no more than 70. Otherwise the line will be too long for people to read comfortably, and this can make the text seem clumsy. -@end defvar +@end defopt @defvar default-fill-column The value of this variable is the default value for @code{fill-column} in @@ -1392,6 +1413,50 @@ non-@code{nil}, then the line won't be broken there. @end defvar +@node Adaptive Fill +@section Adaptive Fill Mode +@cindex Adaptive Fill mode + + Adaptive Fill mode chooses a fill prefix automatically from the text +in each paragraph being filled. + +@defopt adaptive-fill-mode +Adaptive Fill mode is enabled when this variable is non-@code{nil}. +It is @code{t} by default. +@end defopt + +@defun fill-context-prefix from to +This function implements the heart of Adaptive Fill mode; it chooses a +fill prefix based on the text between @var{from} and @var{to}. It does +this by looking at the first two lines of the paragraph, based on the +variables described below. +@end defun + +@defopt adaptive-fill-regexp +This variable holds a regular expression to control Adaptive Fill mode. +Whichever characters starting after the line's left margin match this +regular expression, those are the candidate for the fill prefix. +@end defopt + +@defopt adaptive-fill-first-line-regexp +In a one-line paragraph, if the candidate fill prefix matches +this regular expression, or if it matches @code{comment-start-skip}, +then it is used---otherwise, it is replaced with an equivalent +number of spaces. + +However, the fill prefix is never taken from a one-line paragraph +if it would act as a paragraph starter on subsequent lines. +@end defopt + +@defopt adaptive-fill-function +You can specify more complex ways of choosing a fill prefix +automatically by setting this variable to a function. The function is +called when @code{adaptive-fill-regexp} does not match, with point after +the left margin of a line, and it should return the appropriate fill +prefix based on that line. If it returns @code{nil}, that means it sees +no fill prefix in that line. +@end defopt + @node Auto Filling @comment node-name, next, previous, up @section Auto Filling @@ -1513,10 +1578,11 @@ @end group @group (interactive "P\nr") - (save-restriction - (narrow-to-region beg end) - (goto-char (point-min)) - (sort-subr reverse 'forward-line 'end-of-line))) + (save-excursion + (save-restriction + (narrow-to-region beg end) + (goto-char (point-min)) + (sort-subr reverse 'forward-line 'end-of-line)))) @end group @end example @@ -1531,8 +1597,11 @@ @example @group (sort-subr reverse - (function - (lambda () (skip-chars-forward "\n \t\f"))) + (function + (lambda () + (while (and (not (eobp)) + (looking-at paragraph-separate)) + (forward-line 1)))) 'forward-paragraph) @end group @end example @@ -1541,6 +1610,11 @@ position after @code{sort-subr} returns. @end defun +@defopt sort-fold-case +If this variable is non-@code{nil}, @code{sort-subr} and the other +buffer sorting functions ignore case when comparing strings. +@end defopt + @deffn Command sort-regexp-fields reverse record-regexp key-regexp start end This command sorts the region between @var{start} and @var{end} alphabetically as specified by @var{record-regexp} and @var{key-regexp}. @@ -1823,7 +1897,7 @@ @deffn Command reindent-then-newline-and-indent @comment !!SourceFile simple.el This command reindents the current line, inserts a newline at point, -and then reindents the new line (the one following the newline just +and then indents the new line (the one following the newline just inserted). This command does indentation on both lines according to the current @@ -3177,7 +3251,7 @@ before the change. All three arguments are integers. The buffer that's about to change is always the current buffer. -The length of the old text the difference between the buffer positions +The length of the old text is the difference between the buffer positions before and after that text as it was before the change. As for the changed text, its length is simply the difference between the first two arguments.
--- a/lispref/tips.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/tips.texi Tue May 26 18:56:56 1998 +0000 @@ -354,7 +354,7 @@ @end example @item -If calling a small function accounts for a substantial part of your +If calling a small function accounts for a substantial part of your program's running time, make the function inline. This eliminates the function call overhead. Since making a function inline reduces the flexibility of changing the program, don't do it unless it gives @@ -396,7 +396,7 @@ @item For consistency, phrase the verb in the first sentence of a -documentation string as an infinitive with ``to'' omitted. For +function's documentation string as an infinitive with ``to'' omitted. For instance, use ``Return the cons of A and B.'' in preference to ``Returns the cons of A and B@.'' Usually it looks good to do likewise for the rest of the first paragraph. Subsequent paragraphs usually look better @@ -478,8 +478,8 @@ convention, with single-quotes for all symbols.) @end ifinfo -Help mode automatically creates hyperlinks when documentation strings -use symbol names inside single quotes, when the symbol has either a +Help mode automatically creates a hyperlink when a documentation string +uses a symbol name inside single quotes, if the symbol has either a function or a variable definition. You do not need to do anything special to make use of this feature. However, when a symbol has both a function definition and a variable definition, and you want to refer to
--- a/lispref/variables.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/variables.texi Tue May 26 18:56:56 1998 +0000 @@ -1073,7 +1073,7 @@ This section describes buffer-local bindings; for frame-local bindings, see the following section, @ref{Frame-Local Variables}. (A few -variables have bindings that are local to each X terminal; see +variables have bindings that are local to each terminal; see @ref{Multiple Displays}.) @menu
--- a/lispref/windows.texi Tue May 26 18:27:47 1998 +0000 +++ b/lispref/windows.texi Tue May 26 18:56:56 1998 +0000 @@ -252,10 +252,13 @@ @end deffn @deffn Command split-window-vertically size -This function splits the selected window into two windows, one above -the other, leaving the selected window with @var{size} lines. +This function splits the selected window into two windows, one above the +other, leaving the upper of the two window selected, with @var{size} +lines. (If @var{size} is negative, then the lower of the two windows +gets @minus{} @var{size} lines and the upper window gets the rest, but +the upper window is still the one selected.) -This function is simply an interface to @code{split-windows}. +This function is simply an interface to @code{split-window}. Here is the complete function definition for it: @smallexample @@ -272,7 +275,7 @@ This function splits the selected window into two windows side-by-side, leaving the selected window with @var{size} columns. -This function is simply an interface to @code{split-windows}. Here is +This function is simply an interface to @code{split-window}. Here is the complete definition for @code{split-window-horizontally} (except for part of the documentation string): @@ -366,16 +369,20 @@ single window showing another buffer chosen with @code{other-buffer}. @xref{The Buffer List}. -The argument @var{frame} controls which frames to operate on: +The argument @var{frame} controls which frames to operate on. This +function does not use it in quite the same way as the other functions +which scan all windows; specifically, the values @code{t} and @code{nil} +have the opposite of their meanings in other functions. Here are the +full details: @itemize @bullet @item -If it is @code{nil}, operate on the selected frame. +If it is @code{nil}, operate on all frames. @item -If it is @code{t}, operate on all frames. +If it is @code{t}, operate on the selected frame. @item If it is @code{visible}, operate on all visible frames. -@item 0 +@item If it is 0, operate on all visible or iconified frames. @item If it is a frame, operate on that frame. @@ -463,8 +470,8 @@ the window that is first in the cyclic ordering of windows (see following section), starting from the selected window. -The argument @var{frame} controls which set of windows are -considered. See @code{get-lru-window}, above. +The argument @var{frame} controls which set of windows to +consider. See @code{get-lru-window}, above. @end defun @node Cyclic Window Ordering @@ -677,7 +684,7 @@ in a window. It is always local in each buffer; each time @code{set-window-buffer} is called, it sets this variable to @code{(current-time)} in the specified buffer (@pxref{Time of Day}). -When a buffer is first created, @code{buffer-display-count} starts out +When a buffer is first created, @code{buffer-display-time} starts out with the value @code{nil}. @end defvar @@ -704,9 +711,9 @@ current so that a Lisp program can access or modify it; they are too drastic for that purpose, since they change the display of buffers in windows, which would be gratuitous and surprise the user. Instead, use -@code{set-buffer} (@pxref{Current Buffer}) and @code{save-excursion} -(@pxref{Excursions}), which designate buffers as current for programmed -access without affecting the display of buffers in windows. +@code{set-buffer} and @code{save-current-buffer} (@pxref{Current +Buffer}), which designate buffers as current for programmed access +without affecting the display of buffers in windows. @deffn Command switch-to-buffer buffer-or-name &optional norecord This function makes @var{buffer-or-name} the current buffer, and also @@ -824,11 +831,23 @@ @var{buffer-or-name}. If the argument @var{frame} is non-@code{nil}, it specifies which frames -to check when deciding whether the buffer is already displayed. Its -value means the same thing as in functions @code{get-buffer-window} -(@pxref{Buffers and Windows}). If the buffer is already displayed -in some window on one of these frames, @code{display-buffer} simply -returns that window. +to check when deciding whether the buffer is already displayed. If the +buffer is already displayed in some window on one of these frames, +@code{display-buffer} simply returns that window. Here are the possible +values of @var{frame}: + +@itemize @bullet +@item +If it is @code{nil}, consider windows on the selected frame. +@item +If it is @code{t}, consider windows on all frames. +@item +If it is @code{visible}, consider windows on all visible frames. +@item +If it is 0, consider windows on all visible or iconified frames. +@item +If it is a frame, consider windows on that frame. +@end itemize Precisely how @code{display-buffer} finds or creates a window depends on the variables described below. @@ -882,7 +901,7 @@ more information about frame parameters. @end defvar -@defvar special-display-buffer-names +@defopt special-display-buffer-names A list of buffer names for buffers that should be displayed specially. If the buffer's name is in this list, @code{display-buffer} handles the buffer specially. @@ -895,9 +914,9 @@ an alist, specifying frame parameters, or it can contain a function and arguments to give to it. (The function's first argument is always the buffer to be displayed; the arguments from the list come after that.) -@end defvar +@end defopt -@defvar special-display-regexps +@defopt special-display-regexps A list of regular expressions that specify buffers that should be displayed specially. If the buffer's name matches any of the regular expressions in this list, @code{display-buffer} handles the buffer @@ -908,7 +927,7 @@ If an element is a list, instead of a string, then the @sc{car} of the list is the regular expression, and the rest of the list says how to create the frame. See above, under @code{special-display-buffer-names}. -@end defvar +@end defopt @defvar special-display-function This variable holds the function to call to display a buffer specially. @@ -1084,7 +1103,7 @@ Emacs does not know the position of the end of display in that window. In that case, this function returns @code{nil}. -If you @var{update} is non-@code{nil}, @code{window-end} always returns +If @var{update} is non-@code{nil}, @code{window-end} always returns an up-to-date value for where the window ends. If the saved value is valid, @code{window-end} returns that; otherwise it computes the correct value by scanning the buffer text. @@ -1253,13 +1272,38 @@ which buffer to scroll. @end defvar -@defopt scroll-step +@tindex scroll-margin +@defopt scroll-margin +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, +the window scrolls automatically (if possible) to move point out of the +margin, closer to the center of the window. +@end defopt + +@tindex scroll-conservatively +@defopt scroll-conservatively This variable controls how scrolling is done automatically when point -moves off the screen. If the value is zero, then redisplay scrolls the -text to center point vertically in the window. If the value is a -positive integer @var{n}, then redisplay brings point back on screen by -scrolling @var{n} lines in either direction, if possible; otherwise, it -centers point. The default value is zero. +moves off the screen (or into the scroll margin). If the value is zero, +then redisplay scrolls the text to center point vertically in the +window. If the value is a positive integer @var{n}, then redisplay +scrolls the window up to @var{n} lines in either direction, if that will +bring point back into view. Otherwise, it centers point. The default +value is zero. +@end defopt + +@defopt scroll-step +This variable is an older variant of @code{scroll-conservatively}. The +difference is that it if its value is @var{n}, that permits scrolling +only by precisely @var{n} lines, not a smaller number. This feature +does not work with @code{scroll-margin}. The default value is zero. +@end defopt + +@tindex scroll-preserve-screen-position +@defopt scroll-preserve-screen-position +If this option is non-@code{nil}, the scroll functions move point so +that the vertical position of the cursor is unchanged, when that is +possible. @end defopt @defopt next-screen-context-lines @@ -1608,6 +1652,17 @@ @end example @end deffn +@deffn Command shrink-window-if-larger-than-buffer window +This command shrinks @var{window} to be as small as possible while still +showing the full contents of its buffer---but not less than +@code{window-min-height} lines. + +However, the command does nothing if the window is already too small to +display the whole text of the buffer, or if part of the contents are +currently scrolled off screen, or if the window is not the full width of +its frame, or if the window is the only window in its frame. +@end deffn + @cindex minimum window size The following two variables constrain the window-size-changing functions to a minimum height and width. @@ -1624,7 +1679,7 @@ @defopt window-min-width The value of this variable determines how narrow a window may become -before it automatically deleted. Making a window smaller than +before it is automatically deleted. Making a window smaller than @code{window-min-width} automatically deletes it, and no window may be created narrower than this. The absolute minimum width is one; any value below that is ignored. The default value is 10. @@ -1813,12 +1868,9 @@ Displaying a different buffer in the window also runs these functions. -These functions cannot expect @code{window-end} (@pxref{Window Start}) -to return a meaningful value, because that value is updated only by -redisplaying the buffer. So if one of these functions needs to know the -last character that will fit in the window with its current -display-start position, it has to find that character using -@code{vertical-motion} (@pxref{Screen Lines}). +These functions must be careful in using @code{window-end} +(@pxref{Window Start}); if you need an up-to-date value, you must use +the @var{update} argument to ensure you get it. @end defvar @defvar window-size-change-functions @@ -1846,7 +1898,7 @@ @defvar redisplay-end-trigger-functions @tindex redisplay-end-trigger-functions -This abnormal hook is run whenever redisplay in window uses text that +This abnormal hook is run whenever redisplay in a window uses text that extends past a specified end trigger position. You set the end trigger position with the function @code{set-window-redisplay-end-trigger}. The functions are called with two arguments: the window, and the end trigger