diff options
Diffstat (limited to 'lispref')
42 files changed, 1533 insertions, 1122 deletions
diff --git a/lispref/backups.texi b/lispref/backups.texi index ec1980957e2..d25908fe57c 100644 --- a/lispref/backups.texi +++ b/lispref/backups.texi @@ -65,11 +65,12 @@ permanent local; @code{kill-local-variables} does not alter it. @end defvar @defopt make-backup-files - This variable determines whether or not to make backup files. If it +This variable determines whether or not to make backup files. If it is non-@code{nil}, then Emacs creates a backup of each file when it is -saved for the first time. +saved for the first time---provided that @code{backup-inhibited} +is @code{nil} (see below). - The following example shows how to change the @code{make-backup-files} +The following example shows how to change the @code{make-backup-files} variable only in the @file{RMAIL} buffer and not elsewhere. Setting it @code{nil} stops Emacs from making backups of the @file{RMAIL} file, which may save disk space. (You would put this code in your @@ -107,10 +108,12 @@ The default value is this: If this variable is non-@code{nil}, backups are inhibited. It records the result of testing @code{backup-enable-predicate} on the visited file name. It can also coherently be used by other mechanisms that inhibit -backups based on which file is visited. This is a permanent local, -so that changing the major mode does not lose its value. +backups based on which file is visited. For example, VC sets this +variable non-@code{nil} to prevent making backups for files managed +with a version control system. -Major modes should not set this variable---they should set +This is a permanent local, so that changing the major mode does not lose +its value. Major modes should not set this variable---they should set @code{make-backup-files} instead. @end defvar @@ -506,7 +509,7 @@ If this variable is non-@code{nil}, buffers that are visiting files have auto-saving enabled by default. Otherwise, they do not. @end defopt -@deffn Command do-auto-save &optional no-message +@deffn Command do-auto-save &optional no-message current-only This function auto-saves all buffers that need to be auto-saved. It saves all buffers for which auto-saving is enabled and that have been changed since the previous auto-save. @@ -515,6 +518,9 @@ Normally, if any buffers are auto-saved, a message that says @samp{Auto-saving...} is displayed in the echo area while auto-saving is going on. However, if @var{no-message} is non-@code{nil}, the message is inhibited. + +If @var{current-only} is non-@code{nil}, only the current buffer +is auto-saved. @end deffn @defun delete-auto-save-file-if-necessary @@ -545,17 +551,22 @@ in response. If it is -1, that means auto-saving is temporarily shut off in this buffer due to a substantial deletion. Explicitly saving the buffer -stores a positive value in this variable, thus reenabling auto-save. +stores a positive value in this variable, thus reenabling auto-saving. Turning auto-save mode off or on also alters this variable. @end defvar @defvar auto-save-list-file-name This variable (if non-@code{nil}) specifies a file for recording the names of all the auto-save files. Each time Emacs does auto-saving, it -writes into this file the names of all the auto-save files of all the -buffers that have auto-save enabled. If Emacs crashes, you can look in -this file to find all the auto-save files that might contain work that -was otherwise lost. The @code{multi-replace} command uses these files. +writes two lines into this file for each buffer that has auto-saving +enabled. The first line gives the name of the visited file (it's empty +if the buffer has none), and the second gives the name of the auto-save +file. + +If Emacs exits normally, it deletes this file. If Emacs crashes, you +can look in the file to find all the auto-save files that might contain +work that was otherwise lost. The @code{recover-session} command uses +these files. The default name for this file is in your home directory and starts with @samp{.saves-}. It also contains the Emacs process @sc{id} and the host @@ -612,9 +623,9 @@ regenerate the contents. @defvar revert-buffer-insert-file-contents-function The value of this variable, if non-@code{nil}, is the function to use to -insert contents when reverting this buffer. The function receives two -arguments, first the file name to use; second, @code{t} if the user has -asked to read the auto-save file. +insert the updated contents when reverting this buffer. The function +receives two arguments: first the file name to use; second, @code{t} if +the user has asked to read the auto-save file. @end defvar @defvar before-revert-hook @@ -635,16 +646,3 @@ Font Lock mode uses this hook to recompute the fonts for the updated buffer contents. @end defvar -@deffn Command recover-file filename -This function visits @var{filename}, but gets the contents from its -last auto-save file. This is useful after the system has crashed, to -resume editing the same file without losing all the work done in the -previous session. - -An error is signaled if there is no auto-save file for @var{filename}, -or if @var{filename} is newer than its auto-save file. If -@var{filename} does not exist, but its auto-save file does, then the -auto-save file is read as usual. This last situation may occur if you -visited a nonexistent file and never actually saved it. -@end deffn - diff --git a/lispref/buffers.texi b/lispref/buffers.texi index bfa8f020c62..801698408aa 100644 --- a/lispref/buffers.texi +++ b/lispref/buffers.texi @@ -45,11 +45,11 @@ current buffer. Each buffer, including the current buffer, may or may not be displayed in any windows. @end ifinfo - Buffers in Emacs editing are objects that have distinct names and -hold text that can be edited. Buffers appear to Lisp programs as a -special data type. The contents of a buffer may be viewed as an -extendable string; insertions and deletions may occur in any part of the -buffer. @xref{Text}. + Buffers in Emacs editing are objects that have distinct names and hold +text that can be edited. Buffers appear to Lisp programs as a special +data type. You can think of the contents of a buffer as an extendable +string; insertions and deletions may occur in any part of the buffer. +@xref{Text}. A Lisp buffer object contains numerous pieces of information. Some of this information is directly accessible to the programmer through @@ -212,7 +212,7 @@ Any argument called @var{buffer} must be an actual buffer object, not a name. Buffers that are ephemeral and generally uninteresting to the user -have names starting with a space, so that the @code{list-buffers} or +have names starting with a space, so that the @code{list-buffers} and @code{buffer-menu} commands don't mention them. A name starting with space also initially disables recording undo information; see @ref{Undo}. @@ -567,7 +567,7 @@ A buffer visiting a write-protected file is normally read-only. Here, the purpose is to show the user that editing the buffer with the aim of saving it in the file may be futile or undesirable. The user who wants to change the buffer text despite this can do so after clearing -the read-only flag with @kbd{C-M-q}. +the read-only flag with @kbd{C-x C-q}. @item Modes such as Dired and Rmail make buffers read-only when altering the @@ -779,6 +779,9 @@ Therefore, when you kill a buffer, you should also take the precautions associated with changing the current buffer (unless you happen to know that the buffer being killed isn't current). @xref{Current Buffer}. + If you kill a buffer that is the base buffer of one or more indirect +buffers, the indirect buffers are automatically killed as well. + The @code{buffer-name} of a killed buffer is @code{nil}. You can use this feature to test whether a buffer has been killed: @@ -853,7 +856,7 @@ when set for any reason. @xref{Buffer-Local Variables}. An @dfn{indirect buffer} shares the text of some other buffer, which is called the @dfn{base buffer} of the indirect buffer. In some ways it -is the equivalent, for buffers, of a symbolic link among files. The base +is the analogue, for buffers, of a symbolic link among files. The base buffer may not itself be an indirect buffer. The text of the indirect buffer is always identical to the text of its diff --git a/lispref/commands.texi b/lispref/commands.texi index aa7ad7d2852..c03e9169ad6 100644 --- a/lispref/commands.texi +++ b/lispref/commands.texi @@ -82,40 +82,10 @@ and also when the command loop is first entered. At that time, @code{last-command} describes the command before that. @xref{Hooks}. @end defvar - An erroneous function in the @code{pre-command-hook} list could easily -make Emacs go into an infinite loop of errors. To protect you from this -sort of painful problem, Emacs sets the hook variable to @code{nil} -temporarily while running the functions in the hook. Thus, if a hook -function gets an error, the hook variable is left as @code{nil}. Emacs -does the same thing for @code{post-command-hook}. - Quitting is suppressed while running @code{pre-command-hook} and -@code{post-command-hook}; this is because otherwise a quit, happening by -chance within one of these hooks, would turn off the hook. - - One inconvenient result of these protective features is that you -cannot have a function in @code{post-command-hook} or -@code{pre-command-hook} which changes the value of that variable. But -that's not a real limitation. If you want hook functions to change the -hook, simply add one fixed function to the hook, and code that function -to look in another hook variable for other functions to call. Here is -an example: - -@example -;; @r{Set up the mechanism.} -(defvar current-post-command-function nil) -(defun run-current-post-command-function () - (if current-post-command-function - (funcall current-post-command-function))) -(add-hooks 'post-command-hook - 'run-current-post-command-function) - -;; @r{Here's a hook function which replaces itself} -;; @r{with a different hook function to run next time.} -(defun first-post-command-function () - (setq current-post-command-function - 'second-post-command-function)) -@end example +@code{post-command-hook}. If an error happens while executing one of +these hooks, it terminates execution of the hook, but that is all it +does. @node Defining Commands @section Defining Commands @@ -502,7 +472,7 @@ that is, if @var{object} is a command. Otherwise, returns @code{nil}. The interactively callable objects include strings and vectors (treated as keyboard macros), lambda expressions that contain a top-level call to -@code{interactive}, compiled function objects made from such lambda +@code{interactive}, byte-code function objects made from such lambda expressions, autoload objects that are declared as interactive (non-@code{nil} fourth argument to @code{autoload}), and some of the primitive functions. @@ -647,6 +617,9 @@ is a symbol with a function definition, but this is not guaranteed. The value is copied from @code{this-command} when a command returns to the command loop, except when the command specifies a prefix argument for the following command. + +This variable is always local to the current terminal and cannot be +buffer-local. @xref{Multiple Displays}. @end defvar @defvar this-command @@ -662,7 +635,7 @@ command). @cindex kill command repetition Some commands set this variable during their execution, as a flag for -whatever command runs next. In particular, the functions that kill text +whatever command runs next. In particular, the functions for killing text set @code{this-command} to @code{kill-region} so that any kill commands immediately following will know to append the killed text to the previous kill. @@ -737,17 +710,6 @@ frame, the value is the frame to which the event was redirected. @xref{Input Focus}. @end defvar -@defvar echo-keystrokes -This variable determines how much time should elapse before command -characters echo. Its value must be an integer, which specifies the -number of seconds to wait before echoing. If the user types a prefix -key (such as @kbd{C-x}) and then delays this many seconds before -continuing, the prefix key is echoed in the echo area. Any subsequent -characters in the same command will be echoed as well. - -If the value is zero, then command input is not echoed. -@end defvar - @node Input Events @section Input Events @cindex events @@ -798,11 +760,25 @@ An input character event consists of a @dfn{basic code} between 0 and @table @asis @item meta -The 2**23 bit in the character code indicates a character +The +@iftex +$2^{27}$ +@end iftex +@ifinfo +2**27 +@end ifinfo +bit in the character code indicates a character typed with the meta key held down. @item control -The 2**22 bit in the character code indicates a non-@sc{ASCII} +The +@iftex +$2^{26}$ +@end iftex +@ifinfo +2**26 +@end ifinfo +bit in the character code indicates a non-@sc{ASCII} control character. @sc{ASCII} control characters such as @kbd{C-a} have special basic @@ -811,42 +787,95 @@ Thus, the code for @kbd{C-a} is just 1. But if you type a control combination not in @sc{ASCII}, such as @kbd{%} with the control key, the numeric value you get is the code -for @kbd{%} plus 2**22 (assuming the terminal supports non-@sc{ASCII} +for @kbd{%} plus +@iftex +$2^{26}$ +@end iftex +@ifinfo +2**26 +@end ifinfo +(assuming the terminal supports non-@sc{ASCII} control characters). @item shift -The 2**21 bit in the character code indicates an @sc{ASCII} control +The +@iftex +$2^{25}$ +@end iftex +@ifinfo +2**25 +@end ifinfo +bit in the character code indicates an @sc{ASCII} control character typed with the shift key held down. For letters, the basic code indicates upper versus lower case; for digits and punctuation, the shift key selects an entirely different character with a different basic code. In order to keep within the @sc{ASCII} character set whenever possible, Emacs avoids using -the 2**21 bit for those characters. +the +@iftex +$2^{25}$ +@end iftex +@ifinfo +2**25 +@end ifinfo +bit for those characters. However, @sc{ASCII} provides no way to distinguish @kbd{C-A} from -@kbd{C-a}, so Emacs uses the 2**21 bit in @kbd{C-A} and not in +@kbd{C-a}, so Emacs uses the +@iftex +$2^{25}$ +@end iftex +@ifinfo +2**25 +@end ifinfo +bit in @kbd{C-A} and not in @kbd{C-a}. @item hyper -The 2**20 bit in the character code indicates a character +The +@iftex +$2^{24}$ +@end iftex +@ifinfo +2**24 +@end ifinfo +bit in the character code indicates a character typed with the hyper key held down. @item super -The 2**19 bit in the character code indicates a character +The +@iftex +$2^{23}$ +@end iftex +@ifinfo +2**23 +@end ifinfo +bit in the character code indicates a character typed with the super key held down. @item alt -The 2**18 bit in the character code indicates a character typed with +The +@iftex +$2^{22}$ +@end iftex +@ifinfo +2**22 +@end ifinfo +bit in the character code indicates a character typed with the alt key held down. (On some terminals, the key labeled @key{ALT} is actually the meta key.) @end table - In the future, Emacs may support a larger range of basic codes. We -may also move the modifier bits to larger bit numbers. Therefore, you -should avoid mentioning specific bit numbers in your program. -Instead, the way to test the modifier bits of a character is with the -function @code{event-modifiers} (@pxref{Classifying Events}). + It is best to avoid mentioning specific bit numbers in your program. +To test the modifier bits of a character, use the function +@code{event-modifiers} (@pxref{Classifying Events}). When making key +bindings, you can use the read syntax for characters with modifier bits +(@samp{\C-}, @samp{\M-}, and so on). For making key bindings with +@code{define-key}, you can use lists such as @code{(control hyper ?x)} to +specify the characters (@pxref{Changing Key Bindings}). The function +@code{event-convert-list} converts such a list into an event type +(@pxref{Classifying Events}). @node Function Keys @subsection Function Keys @@ -1258,6 +1287,11 @@ the window manager. Its standard definition is @code{ignore}; since the frame has already been iconified, Emacs has no work to do. @end table + If one of these events arrives in the middle of a key sequence---that +is, after a prefix key---then Emacs reorders the events so that this +event comes either before or after the multi-event key sequence, not +within it. + @node Event Examples @subsection Event Examples @@ -1380,6 +1414,20 @@ This function returns non-@code{nil} if @var{object} is a mouse movement event. @end defun +@defun event-convert-list list +This function converts a list of modifier names and a basic event type +to an event type which specifies all of them. For example, + +@example +(event-convert-list '(control ?a)) + @result{} 1 +(event-convert-list '(control meta ?a)) + @result{} -134217727 +(event-convert-list '(control super f1)) + @result{} C-s-f1 +@end example +@end defun + @node Accessing Events @subsection Accessing Events @@ -1476,7 +1524,13 @@ limited to the range of 0 to 255 as text characters are. A keyboard character typed using the @key{META} key is called a @dfn{meta character}. The numeric code for such an event includes the -2**23 bit; it does not even come close to fitting in a string. However, +@iftex +$2^{27}$ +@end iftex +@ifinfo +2**27 +@end ifinfo +bit; it does not even come close to fitting in a string. However, earlier Emacs versions used a different representation for these characters, which gave them codes in the range of 128 to 255. That did fit in a string, and many Lisp programs contain string constants that @@ -1493,9 +1547,36 @@ If the keyboard character value is in the range of 0 to 127, it can go in the string unchanged. @item -The meta variants of those characters, with codes in the range of 2**23 -to 2**23+127, can also go in the string, but you must change their -numeric values. You must set the 2**7 bit instead of the 2**23 bit, +The meta variants of those characters, with codes in the range of +@iftex +$2^{27}$ +@end iftex +@ifinfo +2**27 +@end ifinfo +to +@iftex +$2^{27} + 127$, +@end iftex +@ifinfo +2**27+127, +@end ifinfo +can also go in the string, but you must change their +numeric values. You must set the +@iftex +$2^{7}$ +@end iftex +@ifinfo +2**7 +@end ifinfo +bit instead of the +@iftex +$2^{27}$ +@end iftex +@ifinfo +2**27 +@end ifinfo +bit, resulting in a value between 128 and 255. @item @@ -1609,8 +1690,9 @@ not perform case conversion in this way. The function @code{read-key-sequence} also transforms some mouse events. It converts unbound drag events into click events, and discards unbound -button-down events entirely. It also reshuffles focus events so that they -never appear in a key sequence with any other events. +button-down events entirely. It also reshuffles focus events and +miscellaneous window events so that they never appear in a key sequence +with any other events. When mouse events occur in special parts of a window, such as a mode line or a scroll bar, the event type shows nothing special---it is the @@ -1626,7 +1708,7 @@ You can define meanings for mouse clicks in special window parts by defining key sequences using these imaginary prefix keys. For example, if you call @code{read-key-sequence} and then click the -mouse on the window's mode line, you get an event like this: +mouse on the window's mode line, you get two events, like this: @example (read-key-sequence "Click on the mode line: ") @@ -1686,8 +1768,9 @@ the echo area. @end group @group +;; @r{We assume here you use @kbd{M-:} to evaluate this.} (symbol-function 'foo) - @result{} "^[^[(read-char)^M1" + @result{} "^[:(read-char)^M1" @end group @group (execute-kbd-macro 'foo) @@ -1794,8 +1877,8 @@ as part of a command or explicitly by a Lisp program. In the example below, the Lisp program reads the character @kbd{1}, @sc{ASCII} code 49. It becomes the value of @code{last-input-event}, -while @kbd{C-e} (from the @kbd{C-x C-e} command used to evaluate this -expression) remains the value of @code{last-command-event}. +while @kbd{C-e} (we assume @kbd{C-x C-e} command is used to evaluate +this expression) remains the value of @code{last-command-event}. @example @group @@ -1852,12 +1935,15 @@ available. The value is @code{t} if @code{sit-for} waited the full time with no input arriving (see @code{input-pending-p} in @ref{Event Input Misc}). Otherwise, the value is @code{nil}. -@c Emacs 19 feature ??? maybe not working yet +The argument @var{seconds} need not be an integer. If it is a floating +point number, @code{sit-for} waits for a fractional number of seconds. +Some systems support only a whole number of seconds; on these systems, +@var{seconds} is rounded down. + The optional argument @var{millisec} specifies an additional waiting period measured in milliseconds. This adds to the period specified by -@var{seconds}. 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 nonzero @var{millisec}. +@var{seconds}. If the system doesn't support waiting fractions of a +second, you get an error if you specify nonzero @var{millisec}. @cindex forcing redisplay Redisplay is always preempted if input arrives, and does not happen at @@ -1882,12 +1968,15 @@ This function simply pauses for @var{seconds} seconds without updating the display. It pays no attention to available input. It returns @code{nil}. -@c Emacs 19 feature ??? maybe not working yet +The argument @var{seconds} need not be an integer. If it is a floating +point number, @code{sleep-for} waits for a fractional number of seconds. +Some systems support only a whole number of seconds; on these systems, +@var{seconds} is rounded down. + The optional argument @var{millisec} specifies an additional waiting period measured in milliseconds. This adds to the period specified by -@var{seconds}. 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 nonzero @var{millisec}. +@var{seconds}. If the system doesn't support waiting fractions of a +second, you get an error if you specify nonzero @var{millisec}. Use @code{sleep-for} when you wish to guarantee a delay. @end defun @@ -2312,7 +2401,7 @@ the user whether to proceed. been executed, to make it convenient to repeat these commands. A @dfn{complex command} is one for which the interactive argument reading uses the minibuffer. This includes any @kbd{M-x} command, any -@kbd{M-ESC} command, and any command whose @code{interactive} +@kbd{M-:} command, and any command whose @code{interactive} specification reads an argument from the minibuffer. Explicit use of the minibuffer during the execution of the command itself does not cause the command to be considered complex. @@ -2374,14 +2463,6 @@ executed once. If it is 0, @var{macro} is executed over and over until it encounters an error or a failing search. @end defun -@defvar last-kbd-macro -This variable is the definition of the most recently defined keyboard -macro. Its value is a string or vector, or @code{nil}. - -The variable is always local to the current X terminal and cannot be -buffer-local. @xref{Multiple Displays}. -@end defvar - @defvar executing-macro This variable contains the string or vector that defines the keyboard macro that is currently executing. It is @code{nil} if no macro is @@ -2396,7 +2477,15 @@ command can test this variable to behave differently while a macro is being defined. The commands @code{start-kbd-macro} and @code{end-kbd-macro} set this variable---do not set it yourself. -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 + +@defvar last-kbd-macro +This variable is the definition of the most recently defined keyboard +macro. Its value is a string or vector, or @code{nil}. + +The variable is always local to the current terminal and cannot be buffer-local. @xref{Multiple Displays}. @end defvar diff --git a/lispref/compile.texi b/lispref/compile.texi index 413adc085a3..7fcaf0f9b76 100644 --- a/lispref/compile.texi +++ b/lispref/compile.texi @@ -24,6 +24,12 @@ however, as fast as true compiled code. by recent earlier versions of Emacs, but the reverse is not true. In particular, if you compile a program with Emacs 19.29, the compiled code does not run in earlier versions. +@iftex +@xref{Docs and Compilation}. +@end iftex +Files compiled in versions before 19.29 may not work in 19.29 if they +contain character constants with modifier bits, because the bits were +renumbered in Emacs 19.29. @xref{Compilation Errors}, for how to investigate errors occurring in byte compilation. @@ -98,10 +104,13 @@ expanded when they are compiled, so the macros must already be defined for proper compilation. For more details, see @ref{Compiling Macros}. Normally, compiling a file does not evaluate the file's contents or -load the file. But it does execute any @code{require} calls at -top level in the file. One way to ensure that necessary macro -definitions are available during compilation is to require the file that -defines them. @xref{Features}. +load the file. But it does execute any @code{require} calls at top +level in the file. One way to ensure that necessary macro definitions +are available during compilation is to require the file that defines +them (@pxref{Named Features}). To avoid loading the macro definition files +when someone @emph{runs} the compiled program, write +@code{eval-when-compile} around the @code{require} calls (@pxref{Eval +During Compile}). @defun byte-compile symbol This function byte-compiles the function definition of @var{symbol}, @@ -191,10 +200,10 @@ This function recompiles every @samp{.el} file in @var{directory} that needs recompilation. A file needs recompilation if a @samp{.elc} file exists but is older than the @samp{.el} file. -If a @samp{.el} file exists, but there is no corresponding @samp{.elc} -file, then @var{flag} says what to do. If it is @code{nil}, the file is +When a @samp{.el} file has no corresponding @samp{.elc} file, then +@var{flag} says what to do. If it is @code{nil}, these files are ignored. If it is non-@code{nil}, the user is asked whether to compile -the file. +each such file. The returned value of this command is unpredictable. @end deffn @@ -265,7 +274,7 @@ turn off this feature by setting @code{byte-compile-dynamic-docstrings} to @code{nil}. Once this is done, you can compile files that will load into older Emacs versions. You can do this globally, or for one source file by specifying a file-local binding for the variable. Here's one -way: +way to do that: @example -*-byte-compile-dynamic-docstrings: nil;-*- @@ -372,7 +381,7 @@ At top level, this is analogous to the Common Lisp idiom @end defspec @node Byte-Code Objects -@section Byte-Code Objects +@section Byte-Code Function Objects @cindex compiled function @cindex byte-code function @@ -408,10 +417,10 @@ symbols used as function names and variable names. The maximum stack size this function needs. @item docstring -The documentation string (if any); otherwise, @code{nil}. For functions -preloaded before Emacs is dumped, this is usually an integer which is an -index into the @file{DOC} file; use @code{documentation} to convert this -into a string (@pxref{Accessing Documentation}). +The documentation string (if any); otherwise, @code{nil}. The value may +be a number or a list, in case the documentation string is stored in a +file. Use the function @code{documentation} to get the real +documentation string (@pxref{Accessing Documentation}). @item interactive The interactive spec (if any). This can be a string or a Lisp diff --git a/lispref/control.texi b/lispref/control.texi index aea1c535588..c7367894919 100644 --- a/lispref/control.texi +++ b/lispref/control.texi @@ -940,11 +940,11 @@ including those signaled with @code{error}: (if (eq baz 35) t ;; @r{This is a call to the function @code{error}.} - (error "Rats! The variable %s was %s, not 35." 'baz baz)) + (error "Rats! The variable %s was %s, not 35" 'baz baz)) ;; @r{This is the handler; it is not a form.} (error (princ (format "The error was: %s" err)) 2)) -@print{} The error was: (error "Rats! The variable baz was 34, not 35.") +@print{} The error was: (error "Rats! The variable baz was 34, not 35") @result{} 2 @end group @end smallexample @@ -1005,6 +1005,9 @@ message @samp{peculiar error} is used. This error has three condition names: @code{new-error}, the narrowest classification; @code{my-own-errors}, which we imagine is a wider classification; and @code{error}, which is the widest of all. + + The error string should start with a capital letter but it should +not end with a period. This is for consistency with the rest of Emacs. Naturally, Emacs will never signal @code{new-error} on its own; only an explicit call to @code{signal} (@pxref{Signaling Errors}) in your diff --git a/lispref/debugging.texi b/lispref/debugging.texi index 3fa300d02f9..6775323049d 100644 --- a/lispref/debugging.texi +++ b/lispref/debugging.texi @@ -172,8 +172,8 @@ for @var{function-name} in the minibuffer. If the function is already set up to invoke the debugger on entry, @code{debug-on-entry} does nothing. - Caveat: if you redefine a function after using @code{debug-on-entry} -on it, the code to enter the debugger is lost. + @strong{Note:} if you redefine a function after using +@code{debug-on-entry} on it, the code to enter the debugger is lost. @code{debug-on-entry} returns @var{function-name}. @@ -217,7 +217,8 @@ Entering: @deffn Command cancel-debug-on-entry function-name This function undoes the effect of @code{debug-on-entry} on @var{function-name}. When called interactively, it prompts for -@var{function-name} in the minibuffer. +@var{function-name} in the minibuffer. If @var{function-name} is +@code{nil} or the empty string, it cancels debugging for all functions. If @code{cancel-debug-on-entry} is called more than once on the same function, the second call does nothing. @code{cancel-debug-on-entry} @@ -329,12 +330,12 @@ cancels a @kbd{b} command on that frame. @item e Read a Lisp expression in the minibuffer, evaluate it, and print the -value in the echo area. The debugger alters certain important variables -as part of its operation; @kbd{e} temporarily restores their -outside-the-debugger values so you can examine them. This makes the -debugger more transparent. By contrast, @kbd{M-@key{ESC}} does nothing -special in the debugger; it shows you the variable values within the -debugger. +value in the echo area. The debugger alters certain important +variables, and the current buffer, as part of its operation; @kbd{e} +temporarily restores their outside-the-debugger values so you can +examine them. This makes the debugger more transparent. By contrast, +@kbd{M-:} does nothing special in the debugger; it shows you the +variable values within the debugger. @item q Terminate the program being debugged; return to top-level Emacs @@ -376,7 +377,7 @@ whatever called @code{debug}. This is the only way the function If the first of the @var{debugger-args} passed to @code{debug} is @code{nil} (or if it is not one of the special values in the table -below), then @code{debug} displays the rest of its arguments at the the +below), then @code{debug} displays the rest of its arguments at the top of the @samp{*Backtrace*} buffer. This mechanism is used to display a message to the user. @@ -564,7 +565,7 @@ This function is used only by the debugger. @end defun @defvar command-debug-status -This variable records the debugging status of current interactive +This variable records the debugging status of the current interactive command. Each time a command is called interactively, this variable is bound to @code{nil}. The debugger can set this variable to leave information for future debugger invocations during the same command. diff --git a/lispref/display.texi b/lispref/display.texi index 146dee69531..8545f23b8c2 100644 --- a/lispref/display.texi +++ b/lispref/display.texi @@ -45,6 +45,11 @@ Even more powerful is @code{redraw-display}: This function clears and redisplays all visible frames. @end deffn + Processing user input takes absolute priority over redisplay. If you +call these functions when input is available, they do nothing +immediately, but a full redisplay does happen eventually---after all the +input has been processed. + Normally, suspending and resuming Emacs also refreshes the screen. Some terminal emulators record separate contents for display-oriented programs such as Emacs and for ordinary sequential display. If you are @@ -59,11 +64,6 @@ has been suspended and resumed. Non-@code{nil} means yes, @code{nil} means no. @end defvar - Processing user input takes absolute priority over redisplay. If you -call these functions when input is available, they do nothing -immediately, but a full redisplay does happen eventually---after all the -input has been processed. - @node Screen Size @section Screen Size @cindex size of screen @@ -154,10 +154,10 @@ then truncation is always used for side-by-side windows (within one frame) regardless of the value of @code{truncate-lines}. @end defopt -@defvar default-truncate-lines +@defopt default-truncate-lines This variable is the default value for @code{truncate-lines}, for buffers that do not have local values for it. -@end defvar +@end defopt @defopt truncate-partial-width-windows This variable controls display of lines that extend beyond the right @@ -171,15 +171,17 @@ with the display table; see @ref{Display Tables}. If your buffer contains @strong{very} long lines, and you use continuation to display them, just thinking about them can make Emacs -redisplay slow. +redisplay slow. The column computation and indentation functions also +become slow. Then you might find it advisable to set +@code{cache-long-line-scans} to @code{t}. @defvar cache-long-line-scans If this variable is non-@code{nil}, various indentation and motion -functions, and Emacs redisplay, cache the results of their scans for -newlines, and consult the cache to avoid rescanning regions of the -buffer unless they are modified. +functions, and Emacs redisplay, cache the results of scanning the +buffer, and consult the cache to avoid rescanning regions of the buffer +unless they are modified. -Turning on the newline cache slows down processing of short lines. +Turning on the cache slows down processing of short lines somewhat. This variable is automatically local in every buffer. @end defvar @@ -248,6 +250,17 @@ how to display a message and prevent it from being logged: @end example @end defopt +@defvar echo-keystrokes +This variable determines how much time should elapse before command +characters echo. Its value must be an integer, which specifies the +number of seconds to wait before echoing. If the user types a prefix +key (such as @kbd{C-x}) and then delays this many seconds before +continuing, the prefix key is echoed in the echo area. Any subsequent +characters in the same command will be echoed as well. + +If the value is zero, then command input is not echoed. +@end defvar + @defvar cursor-in-echo-area This variable controls where the cursor appears when a message is displayed in the echo area. If it is non-@code{nil}, then the cursor @@ -284,7 +297,7 @@ especially useful in a program to display the list of entries in a data base. It permits the implementation of convenient filtering commands to view just a part of the entries in the data base. Setting this variable is very fast, much faster than scanning all the text in the buffer -looking for things to change. +looking for properties to change. @defvar buffer-invisibility-spec This variable specifies which kinds of @code{invisible} properties @@ -314,13 +327,16 @@ by a visible newline, it displays an ellipsis. @end table @end defvar + Ordinarily, commands that operate on text or move point do not care +whether the text is invisible. However, the user-level line motion +commands explicitly ignore invisible newlines. + @node Selective Display @section Selective Display @cindex selective display - @dfn{Selective display} is a class of minor modes in which specially -marked lines do not appear on the screen, or in which highly indented -lines do not appear. + @dfn{Selective display} is a pair of features that hide certain +lines on the screen. The first variant, explicit selective display, is designed for use in a Lisp program. The program controls which lines are hidden by altering @@ -329,7 +345,7 @@ been partially replaced by the invisible text feature (@pxref{Invisible Text}); there is a new version of Outline mode which uses that instead. In the second variant, the choice of lines to hide is made -automatically based on indentation. This variant is designed as a +automatically based on indentation. This variant is designed to be a user-level feature. The way you control explicit selective display is by replacing a @@ -469,9 +485,7 @@ given time. Temporary displays are used by commands to put output into a buffer and then present it to the user for perusal rather than for editing. -Many of the help commands use this feature. Nowadays you can do the -same job by creating an overlay with a @code{before-string} property. -@xref{Overlay Properties}. +Many of the help commands use this feature. @defspec with-output-to-temp-buffer buffer-name forms@dots{} This function executes @var{forms} while arranging to insert any @@ -539,6 +553,10 @@ the display and later (presumably) move point forward. The argument The return value of @code{momentary-string-display} is not meaningful. +If the string @var{string} does not contain control characters, you can +do the same job in a more general way by creating an overlay with a +@code{before-string} property. @xref{Overlay Properties}. + If @var{message} is non-@code{nil}, it is displayed in the echo area while @var{string} is displayed in the buffer. If it is @code{nil}, a default message says to type @var{char} to continue. @@ -580,10 +598,10 @@ Type RET when done reading @cindex overlays You can use @dfn{overlays} to alter the appearance of a buffer's text on -the screen. An overlay is an object that belongs to a particular -buffer, and has a specified beginning and end. It also has properties -that you can examine and set; these affect the display of the text -within the overlay. +the screen, for the sake of presentation features. An overlay is an +object that belongs to a particular buffer, and has a specified +beginning and end. It also has properties that you can examine and set; +these affect the display of the text within the overlay. @menu * Overlay Properties:: How to read and set properties. @@ -626,7 +644,7 @@ applies only on that window. @item category @kindex category @r{(overlay property)} If an overlay has a @code{category} property, we call it the -@dfn{category} of the character. It should be a symbol. The properties +@dfn{category} of the overlay. It should be a symbol. The properties of the symbol serve as defaults for the properties of the overlay. @item face @@ -662,7 +680,7 @@ overlay, @code{t}, the beginning and end of the text range just modified, and the length of the pre-change text replaced by that range. (For an insertion, the pre-change length is zero; for a deletion, that length is the number of characters deleted, and the post-change -beginning and end are at the same place.) +beginning and end are equal.) @item insert-in-front-hooks @kindex insert-in-front-hooks @r{(overlay property)} @@ -685,7 +703,7 @@ invisible, which means that it does not appear on the screen. @item intangible @kindex intangible @r{(overlay property)} The @code{intangible} property on an overlay works just like the -@code{intangible} text propert. @xref{Special Properties}, for details. +@code{intangible} text property. @xref{Special Properties}, for details. @item before-string @kindex before-string @r{(overlay property)} @@ -891,6 +909,10 @@ With overlays. An overlay may have @code{face} and @code{mouse-face} properties too; they apply to all the text covered by the overlay. @item +With a region that is active. In Transient Mark mode, the region is +highlighted with a particular face (see @code{region-face}, below). + +@item With special glyphs. Each glyph can specify a particular face id number. @xref{Glyphs}. @end itemize @@ -898,6 +920,7 @@ number. @xref{Glyphs}. If these various sources together specify more than one face for a particular character, Emacs merges the attributes of the various faces specified. The attributes of the faces of special glyphs come first; +then comes the face for region highlighting, if appropriate; then come attributes of faces from overlays, followed by those from text properties, and last the default face. @@ -951,6 +974,19 @@ new frames. These functions set the foreground (or background, respectively) color of face @var{face} to @var{color}. The argument @var{color} should be a string, the name of a color. + +Certain shades of gray are implemented by stipple patterns on +black-and-white screens. +@end defun + +@defun set-face-stipple face pattern &optional frame +This function sets the background stipple pattern of face @var{face} to +@var{pattern}. The argument @var{pattern} should be the name of a +stipple pattern defined by the X server, or @code{nil} meaning don't use +stipple. + +Normally there is no need to pay attention to stipple patterns, because +they are used automatically to handle certain shades of gray. @end defun @defun set-face-font face font &optional frame @@ -979,6 +1015,11 @@ These functions return the foreground color (or background color, respectively) of face @var{face}, as a string. @end defun +@defun face-stipple face &optional frame +This function returns the name of the background stipple pattern of face +@var{face}, or @code{nil} if it doesn't have one. +@end defun + @defun face-font face &optional frame This function returns the name of the font of face @var{face}. @end defun @@ -987,7 +1028,7 @@ This function returns the name of the font of face @var{face}. This function returns the underline attribute of face @var{face}. @end defun -@defun face-id-number face +@defun face-id face This function returns the face id number of face @var{face}. @end defun @@ -1048,6 +1089,12 @@ This variable specifies the maximum distance to scan for a matching parenthesis before giving up. @end defvar +@defvar blink-matching-paren-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 + @defun 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 @@ -1089,10 +1136,13 @@ default is @code{nil}. @defopt mode-line-inverse-video This variable controls the use of inverse video for mode lines. If it -is non-@code{nil}, then mode lines are displayed in inverse video (under -X, this uses the face named @code{modeline}, which you can set as you -wish). Otherwise, mode lines are displayed normally, just like text. -The default is @code{t}. +is non-@code{nil}, then mode lines are displayed in inverse video. +Otherwise, mode lines are displayed normally, just like text. The +default is @code{t}. + +For X window frames, this displays mode lines using the face named +@code{modeline}, which is normally the inverse of the default face +unless you change it. @end defopt @node Usual Display @@ -1132,7 +1182,7 @@ specify a glyph to use instead of @samp{\}.) The usual display conventions apply even when there is a display table, for any character whose entry in the active display table is @code{nil}. Thus, when you set up a display table, you need only -specify the the characters for which you want unusual behavior. +specify the characters for which you want unusual behavior. These variables affect the way certain characters are displayed on the screen. Since they change the number of columns the characters occupy, @@ -1390,11 +1440,6 @@ running under X) or @code{nil} (if Emacs is running on an ordinary terminal). @end defvar -@defvar window-system-version -This variable distinguishes between different versions of the X Window -System. Its value is 10 or 11 when using X; @code{nil} otherwise. -@end defvar - @defvar window-setup-hook This variable is a normal hook which Emacs runs after loading your @file{.emacs} file and the default initialization file (if any), after diff --git a/lispref/edebug.texi b/lispref/edebug.texi index f32b516199e..5aec9f96f46 100644 --- a/lispref/edebug.texi +++ b/lispref/edebug.texi @@ -214,7 +214,7 @@ must tell it; @xref{Instrumenting Macro Calls}, for details. definition in a way that does not instrument. There are two ways of evaluating forms that never instrument them: from a file with @code{load}, and from the minibuffer with @code{eval-expression} -(@kbd{M-ESC}). +(@kbd{M-:}). If Edebug detects a syntax error while instrumenting, it leaves point at the erroneous code and signals an @code{invalid-read-syntax} error. @@ -626,7 +626,7 @@ Evaluate expression @var{exp} in the context outside of Edebug (@code{edebug-eval-expression}). That is, Edebug tries to minimize its interference with the evaluation. -@item M-@key{ESC} @var{exp} @key{RET} +@item M-: @var{exp} @key{RET} Evaluate expression @var{exp} in the context of Edebug itself. @item C-x C-e diff --git a/lispref/elisp.texi b/lispref/elisp.texi index e1e21b9417c..5ac4053d662 100644 --- a/lispref/elisp.texi +++ b/lispref/elisp.texi @@ -180,8 +180,6 @@ Appendices * Standard Keymaps:: List of standard keymaps. * Standard Hooks:: List of standard hook variables. -* Antinews:: Information about Emacs 18. - * Index:: Index including concepts, functions, variables, and other terms. @@ -422,7 +420,7 @@ Loading * How Programs Do Loading:: The @code{load} function and others. * Autoload:: Setting up a function to autoload. -* Features:: Loading a library if it isn't already loaded. +* Named Features:: Loading a library if it isn't already loaded. * Repeated Loading:: Precautions about loading a file twice. Byte Compilation @@ -650,6 +648,32 @@ Windows * Resizing Windows:: Changing the size of a window. * Window Configurations:: Saving and restoring the state of the screen. +Frames + +* Creating Frames:: Creating additional frames. +* Multiple Displays:: Creating frames on other X displays. +* Frame Parameters:: Controlling frame size, position, font, etc. +* Frame Titles:: Automatic updating of frame titles. +* Deleting Frames:: Frames last until explicitly deleted. +* Finding All Frames:: How to examine all existing frames. +* Frames and Windows:: A frame contains windows; + display of text always works through windows. +* Minibuffers and Frames:: How a frame finds the minibuffer to use. +* 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. +* 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. +* X Selections:: Transferring text to and from other X clients. +* Color Names:: Getting the definitions of color names. +* Resources:: Getting resource values from the server. +* Server Data:: Getting info about the X server. + Positions * Point:: The special position where editing takes place. @@ -664,8 +688,6 @@ Motion * Buffer End Motion:: Moving to the beginning or end of the buffer. * Text Lines:: Moving in terms of lines of text. * Screen Lines:: Moving in terms of lines as displayed. -* Vertical Motion:: Implementation of @code{next-line} and - @code{previous-line}. * List Motion:: Moving by parsing lists and sexps. * Skipping Characters:: Skipping characters belonging to a certain set. @@ -693,6 +715,7 @@ Text * Undo:: Undoing changes to the text of a buffer. * Auto Filling:: How auto-fill mode is implemented to break lines. * Filling:: Functions for explicit filling. +* Margins:: How to specify margins for filling commands. * Sorting:: Functions for sorting parts of the buffer. * Indentation:: Functions to insert or adjust indentation. * Columns:: Computing horizontal positions, and using them. @@ -769,7 +792,7 @@ Processes an asynchronous subprocess. * Output from Processes:: Collecting output from an asynchronous subprocess. * Sentinels:: Sentinels run when process run-status changes. -* TCP:: Opening network connections. +* Network:: Opening network connections. Receiving Output from Processes @@ -886,7 +909,6 @@ Object Internals @include locals.texi @include maps.texi @include hooks.texi -@include anti.texi @include index.texi diff --git a/lispref/errors.texi b/lispref/errors.texi index 8cedced5c32..36290012285 100644 --- a/lispref/errors.texi +++ b/lispref/errors.texi @@ -52,6 +52,10 @@ See @code{/} and @code{%} in @ref{Numbers}. @code{"Buffer is read-only"}@* @xref{Read Only Buffers}. +@item cyclic-function-indirection +@code{"Symbol's chain of function indirections contains a loop"}@* +@xref{Function Indirection}. + @item end-of-buffer @code{"End of buffer"}@* @xref{Motion}. @@ -105,6 +109,10 @@ The values of the symbols @code{nil} and @code{t} may not be changed.@* @xref{Constant Variables, , Variables that Never Change}. +@item undefined-color +@code{"Undefined color"}@* +@xref{Color Names}. + @item void-function @code{"Symbol's function definition is void"}@* @xref{Function Cells}. @@ -121,3 +129,29 @@ may not be changed.@* @code{"Wrong type argument"}@* @xref{Type Predicates}. @end table + + These error types, which are all classified as special cases of +@code{arith-error}, can occur on certain systems for invalid use of +mathematical functions. + +@table @code +@item domain-error +@code{"Arithmetic domain error"}@* +@xref{Math Functions}. + +@item overflow-error +@code{"Arithmetic overflow error"}@* +@xref{Math Functions}. + +@item range-error +@code{"Arithmetic range error"}@* +@xref{Math Functions}. + +@item singularity-error +@code{"Arithmetic singularity error"}@* +@xref{Math Functions}. + +@item underflow-error +@code{"Arithmetic underflow error"}@* +@xref{Math Functions}. +@end table diff --git a/lispref/eval.texi b/lispref/eval.texi index 1bbd672f5fc..494a8145baf 100644 --- a/lispref/eval.texi +++ b/lispref/eval.texi @@ -73,6 +73,12 @@ of the form @code{(car x)}: the subform @code{x} must first be evaluated recursively, so that its value can be passed as an argument to the function @code{car}. + Evaluation of a function call ultimately calls the function specified +in it. @xref{Functions}. The execution of the function may itself work +by evaluating the function definition; or the function may be a Lisp +primitive implemented in C, or it may be a byte-compiled function +(@pxref{Byte Compilation}). + @cindex environment The evaluation of forms takes place in a context called the @dfn{environment}, which consists of the current values and bindings of @@ -90,17 +96,12 @@ is complete. The form may also make changes that persist; these changes are called @dfn{side effects}. An example of a form that produces side effects is @code{(setq foo 1)}. - Finally, evaluation of one particular function call, @code{byte-code}, -invokes the @dfn{byte-code interpreter} on its arguments. Although the -byte-code interpreter is not the same as the Lisp interpreter, it uses -the same environment as the Lisp interpreter, and may on occasion invoke -the Lisp interpreter. (@xref{Byte Compilation}.) - The details of what evaluation means for each kind of form are described below (@pxref{Forms}). @node Eval @section Eval +@c ??? Perhaps this should be the last section in the chapter. Most often, forms are evaluated automatically, by virtue of their occurrence in a program being run. On rare occasions, you may need to @@ -108,10 +109,14 @@ write code that evaluates a form that is computed at run time, such as after reading a form from text being edited or getting one from a property list. On these occasions, use the @code{eval} function. - The functions and variables described in this section evaluate -forms, specify limits to the evaluation process, or record recently -returned values. Loading a file also does evaluation -(@pxref{Loading}). + @strong{Note:} it is generally cleaner and more flexible to call +functions that are stored in data structures, rather than to evaluate +expressions stored in data structures. Using functions provides the +ability to pass information to them as arguments. + + The functions and variables described in this section evaluate forms, +specify limits to the evaluation process, or record recently returned +values. Loading a file also does evaluation (@pxref{Loading}). @defun eval form This is the basic function for performing evaluation. It evaluates @@ -143,19 +148,6 @@ The number of currently active calls to @code{eval} is limited to @code{max-lisp-eval-depth} (see below). @end defun -@cindex evaluation of buffer contents -@deffn Command eval-current-buffer &optional stream -This function evaluates the forms in the current buffer. It reads -forms from the buffer and calls @code{eval} on them until the end of the -buffer is reached, or until an error is signaled and not handled. - -If @var{stream} is supplied, the variable @code{standard-output} is -bound to @var{stream} during the evaluation (@pxref{Output -Functions}). - -@code{eval-current-buffer} always returns @code{nil}. -@end deffn - @deffn Command eval-region start end &optional stream This function evaluates the forms in the current buffer in the region defined by the positions @var{start} and @var{end}. It reads forms from @@ -172,6 +164,12 @@ expressions. @xref{How Programs Do Loading}. @code{eval-region} always returns @code{nil}. @end deffn +@cindex evaluation of buffer contents +@deffn Command eval-current-buffer &optional stream +This is like @code{eval-region} except that it operates on the whole +buffer. +@end deffn + @defvar max-lisp-eval-depth This variable defines the maximum depth allowed in calls to @code{eval}, @code{apply}, and @code{funcall} before an error is signaled (with error @@ -296,9 +294,9 @@ unchanged. It is common to write numbers, characters, strings, and even vectors in Lisp code, taking advantage of the fact that they self-evaluate. However, it is quite unusual to do this for types that lack a read -syntax, because there's no way to write them textually; however, it is -possible to construct Lisp expressions containing these types by means -of a Lisp program. Here is an example: +syntax, because there's no way to write them textually. It is possible +to construct Lisp expressions containing these types by means of a Lisp +program. Here is an example: @example @group @@ -654,14 +652,15 @@ definition loaded from that file. @xref{Autoload}. @section Quoting @cindex quoting - The special form @code{quote} returns its single argument -``unchanged''. + The special form @code{quote} returns its single argument, as written, +without evaluating it. This provides a way to include constant symbols +and lists, which are not self-evaluating objects, in a program. (It is +not necessary to quote self-evaluating objects such as numbers, strings, +and vectors.) @defspec quote object -This special form returns @var{object}, without evaluating it. This -provides a way to include constant symbols and lists, which are not -self-evaluating objects, in a program. (It is not necessary to quote -self-evaluating objects such as numbers, strings, and vectors.) +This special form returns @var{object}, without evaluating it. +@end defspec @cindex @samp{'} for quoting @cindex quoting using apostrophe @@ -700,9 +699,8 @@ Here are some examples of expressions that use @code{quote}: @result{} [(quote foo)] @end group @end example -@end defspec Other quoting constructs include @code{function} (@pxref{Anonymous Functions}), which causes an anonymous lambda expression written in Lisp -to be compiled, and @code{`} (@pxref{Backquote}), which is used to quote +to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote only part of a list, while computing and substituting other parts. diff --git a/lispref/files.texi b/lispref/files.texi index cfcab286d7b..1fa70df853d 100644 --- a/lispref/files.texi +++ b/lispref/files.texi @@ -79,6 +79,11 @@ For historical reasons, these functions have names starting with functions and variables that access the visited file name of a buffer or that find an existing buffer by its visited file name. + In a Lisp program, if you want to look at the contents of a file but +not alter it, the fastest way is to use @code{insert-file-contents} in a +temporary buffer. Visiting the file is not necessary and takes longer. +@xref{Reading from Files}. + @deffn Command find-file filename This command selects a buffer visiting the file @var{filename}, using an existing buffer if there is one, and otherwise creating a @@ -132,16 +137,6 @@ visiting the file @var{filename}. @end example @end defun -@deffn Command find-alternate-file filename -This command selects a buffer visiting the file @var{filename}, then -kills the buffer that was previously displayed in the selected window. -It is useful if you have visited the wrong file by mistake, so that you -can get rid of the buffer that you did not want to create, at the same -time as you visit the file you intended. - -When this command is called interactively, it prompts for @var{filename}. -@end deffn - @deffn Command find-file-other-window filename This command selects a buffer visiting the file @var{filename}, but does so in a window other than the selected window. It may use another @@ -161,10 +156,11 @@ When this command is called interactively, it prompts for @end deffn @deffn Command view-file filename -This command visits @var{filename} in View mode, returning to the -previous buffer when done. View mode is a mode that allows you to skim -rapidly through the file but does not let you modify it. Entering View -mode runs the normal hook @code{view-mode-hook}. @xref{Hooks}. +This command visits @var{filename} in View mode, and displays it in a +recursive edit, returning to the previous buffer when done. View mode +is a mode that allows you to skim rapidly through the file but does not +let you modify it. Entering View mode runs the normal hook +@code{view-mode-hook}. @xref{Hooks}. When @code{view-file} is called interactively, it prompts for @var{filename}. @@ -208,6 +204,7 @@ as the name if that name is free; otherwise, it appends a string such as @strong{Please note:} @code{create-file-buffer} does @emph{not} associate the new buffer with a file and does not select the buffer. +It also does not use the default major mode. @example @group @@ -368,9 +365,11 @@ the intended name after it is clear there are no errors. This procedure prevents problems such as a lack of disk space from resulting in an invalid file. -(This feature worked differently in older Emacs versions.) +As a side effect, backups must be made by copying. +@xref{Rename or Copy}. -Some modes set this non-@code{nil} locally in particular buffers. +Some modes set this variable non-@code{nil} locally in particular +buffers. @end defvar @defopt require-final-newline @@ -401,9 +400,11 @@ current buffer after point. It returns a list of the absolute file name and the length of the data inserted. An error is signaled if @var{filename} is not the name of a file that can be read. -To set up saved text properties, @code{insert-file-contents} calls the -functions in the list @code{after-insert-file-functions}. For more -information, see @ref{Saving Properties}. +The function @code{insert-file-contents} checks the file contents +against the defined file formats, and converts the file contents if +appropriate. @xref{Format Conversion}. It also calls the functions in +the list @code{after-insert-file-functions}; see @ref{Saving +Properties}. If @var{visit} is non-@code{nil}, this function additionally marks the buffer as unmodified and sets up various fields in the buffer so that it @@ -427,10 +428,6 @@ contents of the buffer (actually, just the accessible portion) with the contents of the file. This is better than simply deleting the buffer contents and inserting the whole file, because (1) it preserves some marker positions and (2) it puts less data in the undo list. - -The function @code{insert-file-contents} checks the file contents -against the defined file formats, and converts the file contents if -appropriate. @xref{Format Conversion}. @end defun If you want to pass a file name to another process so that another @@ -484,19 +481,16 @@ the buffer as visiting another file (@var{visit}). The argument to implement @code{file-precious-flag}; don't use it yourself unless you really know what you're doing. -To output information about text properties, @code{write-region} calls -the functions in the list @code{write-region-annotation-functions}. For -more information, see @ref{Saving Properties}. +The function @code{write-region} converts the data which it writes to +the appropriate file formats specified by @code{buffer-file-format}. +@xref{Format Conversion}. It also calls the functions in the list +@code{write-region-annotate-functions}; see @ref{Saving Properties}. Normally, @code{write-region} displays a message @samp{Wrote file @var{filename}} in the echo area. If @var{visit} is neither @code{t} nor @code{nil} nor a string, then this message is inhibited. This feature is useful for programs that use files for internal purposes, files that the user does not need to know about. - -The function @code{write-region} converts the data which it writes to -the appropriate file formats specified by @code{buffer-file-format}. -@xref{Format Conversion}. @end deffn @node File Locks @@ -737,8 +731,8 @@ time as a list of two numbers. @xref{File Attributes}. @comment node-name, next, previous, up @subsection Distinguishing Kinds of Files - This section describes how to distinguish directories and symbolic -links from ordinary files. + This section describes how to distinguish various kinds of files, such +as directories, symbolic links, and ordinary files. @defun file-symlink-p filename @cindex file symbolic links @@ -1330,9 +1324,16 @@ backup version numbers, or trailing tildes. @end defun @defun file-name-sans-extension filename -This function returns @var{filename} sans its final ``extension'', if -any. The extension, in a file name, is the part that follows the last -@samp{.}. +This function returns @var{filename} minus its ``extension,'' if any. +The extension, in a file name, is the part that starts with the last +@samp{.} in the last name component. For example, + +@example +(file-name-sans-extension "foo.lose.c") + @result{} "foo.lose" +(file-name-sans-extension "big.hack/foo") + @result{} "big.hack/foo" +@end example @end defun @node Directory Names @@ -1825,7 +1826,8 @@ This function creates a directory named @var{dirname}. @defun delete-directory dirname This function deletes the directory named @var{dirname}. The function @code{delete-file} does not work for files that are directories; you -must use @code{delete-directory} in that case. +must use @code{delete-directory} for them. If the directory contains +any files, @code{delete-directory} signals an error. @end defun @node Magic File Names @@ -1887,7 +1889,8 @@ Here are the operations that a magic file name handler gets to handle: @code{file-name-directory}, @code{file-name-nondirectory}, @code{file-name-sans-versions}, @code{file-newer-than-file-p}, @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p}, -@code{file-truename}, @code{file-writable-p}, @code{insert-directory}, +@code{file-truename}, @code{get-file-buffer}, @code{file-writable-p}, +@code{insert-directory}, @code{insert-file-contents}, @code{load}, @code{make-directory}, @code{make-symbolic-link}, @code{rename-file}, @code{set-file-modes}, @code{set-visited-file-modtime}, @code{unhandled-file-name-directory}, @@ -1977,9 +1980,10 @@ is a good way to come up with one. @cindex encoding file formats @cindex decoding file formats The variable @code{format-alist} defines a list of @dfn{file formats}, -which are textual representations used in files for the data (text, +which describe textual representations used in files for the data (text, text-properties, and possibly other information) in an Emacs buffer. -Emacs performs format conversion when reading and writing files. +Emacs performs format conversion if appropriate when reading and writing +files. @defvar format-alist This list contains one format definition for each defined file format. @@ -2014,7 +2018,7 @@ which specify the part of the buffer it should convert. It should convert the text by editing it in place. Since this can change the length of the text, @var{from-fn} should return the modified end position. -One responsibility of @var{from-fm} is to make sure that the beginning +One responsibility of @var{from-fn} is to make sure that the beginning of the file no longer matches @var{regexp}. Otherwise it is likely to get called again. @@ -2061,23 +2065,26 @@ It keeps checking them until none of them is applicable. Visiting a file, with @code{find-file-noselect} or the commands that use it, performs conversion likewise (because it calls -@code{insert-file-contents}); but it also calls the mode function for -each format that it decodes. It stores a list of the format names -in the buffer-local variable @code{buffer-file-format}. +@code{insert-file-contents}); it also calls the mode function for each +format that it decodes. It stores a list of the format names in the +buffer-local variable @code{buffer-file-format}. @defvar buffer-file-format -This variable holds a list of the file formats that were decoded in the -course of visiting the current buffer's file. It is always local in all +This variable states the format of the visited file. More precisely, +this is a list of the file format names that were decoded in the course +of visiting the current buffer's file. It is always local in all buffers. @end defvar When @code{write-region} writes data into a file, it first calls the -encoding functions for the formats listed in @code{buffer-file-format}. +encoding functions for the formats listed in @code{buffer-file-format}, +in the order of appearance in the list. @defun format-write-file file format This command writes the current buffer contents into the file @var{file} in format @var{format}, and makes that format the default for future -saves of the buffer. +saves of the buffer. The argument @var{format} is a list of format +names. @end defun @defvar auto-save-file-format @@ -2098,7 +2105,7 @@ is always local in all buffers. Emacs on MS-DOS makes a distinction between text files and binary files. This is necessary because ordinary text files on MS-DOS use a two character sequence between lines: carriage-return and linefeed -(CRLF). Emacs expects just a newline character (a linefeed) between +(@sc{crlf}). Emacs expects just a newline character (a linefeed) between lines. When Emacs reads or writes a text file on MS-DOS, it needs to convert the line separators. This means it needs to know which files are text files and which are binary. It makes this decision when diff --git a/lispref/frames.texi b/lispref/frames.texi index 97d8e3e940a..b7d64e55332 100644 --- a/lispref/frames.texi +++ b/lispref/frames.texi @@ -18,9 +18,10 @@ horizontally into smaller windows. @dfn{terminal frames}. If you create additional ones, Emacs displays one and only one at any given time---on the terminal screen, of course. - When Emacs uses X for display, it does not have a terminal frame; -instead, it starts with a single @dfn{X window frame}. It can display -multiple X window frames at the same time, each in its own X window. + When Emacs communicates directly with an X server, it does not have a +terminal frame; instead, it starts with a single @dfn{X window frame}. +It can display multiple X window frames at the same time, each in its +own X window. @defun framep object This predicate returns @code{t} if @var{object} is a frame, and @@ -48,7 +49,7 @@ This predicate returns @code{t} if @var{object} is a frame, and * Dialog Boxes:: Displaying a box to ask yes or no. * Pointer Shapes:: Specifying the shape of the mouse pointer. * X Selections:: Transferring text to and from other X clients. -* X Connections:: Opening and closing the X server connection. +* 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 @@ -66,8 +67,8 @@ an X window frame; otherwise, it makes a terminal frame. The argument is an alist specifying frame parameters. Any parameters not mentioned in @var{alist} default according to the value of the -variable @code{default-frame-alist}; parameters not specified there -either default from the standard X defaults file and X resources. +variable @code{default-frame-alist}; parameters not specified even there +default from the standard X defaults file and X resources. The set of possible parameters depends in principle on what kind of window system Emacs uses to display its frames. @xref{X Frame @@ -120,7 +121,8 @@ argument, it is like @code{make-frame} (@pxref{Creating Frames}). @defun x-display-list This returns a list that indicates which X displays Emacs has a -connection to. The elements of the list are display names (strings). +connection to. The elements of the list are strings, and each one is +a display name. @end defun @defun x-open-connection display &optional xrm-string @@ -128,9 +130,18 @@ This function opens a connection to the X display @var{display}. It does not create a frame on that display, but it permits you to check that communication can be established with that display. -The optional second argument @var{xrm-string} should be a string of -resources in xrdb format, or @code{nil}. The resources, if specified, -apply to all Emacs frames created on this display. +The optional argument @var{resource-string}, if not @code{nil}, is a +string of resource names and values, in the same format used in the +@file{.Xresources} file. The values you specify override the resource +values recorded in the X server itself; they apply to all Emacs frames +created on this display. Here's an example of what this string might +look like: + +@example +"*BorderWidth: 3\n*InternalBorder: 2\n" +@end example + +@xref{Resources}. @end defun @defun x-close-connection display @@ -147,9 +158,8 @@ Just what parameters a frame has depends on what display mechanism it uses. Frame parameters exist for the sake of window systems. A terminal frame -has a few parameters, for compatibility's sake only. You can't change -these parameters directly; the only ones that ever change are the height -and width. +has a few parameters, mostly for compatibility's sake; only the height, +width and @code{buffer-predicate} parameters really do something. @menu * Parameter Access:: How to change a frame's parameters. @@ -196,11 +206,11 @@ file. After reading that file, Emacs checks @code{initial-frame-alist}, and applies the parameter settings in the altered value to the already created initial frame. -If these settings affect the frame geometry, you'll see the frame appear -with the wrong geometry and then change to the specified one. If you -like, you can specify the same geometry with X resources; those do take -affect before the frame is created. @xref{Resources X,, X Resources, -emacs, The GNU Emacs Manual}. +If these settings affect the frame geometry and appearance, you'll see +the frame appear with the wrong ones and then change to the specified +ones. If that bothers you, you can specify the same geometry and +appearance with X resources; those do take affect before the frame is +created. @xref{Resources X,, X Resources, emacs, The GNU Emacs Manual}. X resource settings typically apply to all frames. If you want to specify some X resources solely for the sake of the initial frame, and @@ -211,8 +221,9 @@ the initial frame, specify the same parameters in @code{initial-frame-alist} with values that match the X resources. @end defvar -If these parameters specify a separate minibuffer-only frame, -and you have not created one, Emacs creates one for you. +If these parameters specify a separate minibuffer-only frame with +@code{(minibuffer . nil)}, and you have not created one, Emacs creates +one for you. @defvar minibuffer-frame-alist This variable's value is an alist of parameter values used when creating @@ -220,20 +231,18 @@ an initial minibuffer-only frame---if such a frame is needed, according to the parameters for the main initial frame. @end defvar -@defvar special-display-frame-alist -The variable @code{special-display-frame-alist} specifies the frame -parameters for special display frames. -@end defvar - @defvar default-frame-alist This is an alist specifying default values of frame parameters for subsequent Emacs frames (not the initial ones). @end defvar +See also @code{special-display-frame-alist}, in @ref{Choosing Window}. + If you use options that specify window appearance when you invoke Emacs, they take effect by adding elements to @code{default-frame-alist}. One -exception is @samp{-geometry}, which adds to @code{initial-frame-alist} -instead. @xref{Command Arguments,,, emacs, The GNU Emacs Manual}. +exception is @samp{-geometry}, which adds the specified position to +@code{initial-frame-alist} instead. @xref{Command Arguments,,, emacs, +The GNU Emacs Manual}. @node X Frame Parameters @subsection X Window Frame Parameters @@ -267,8 +276,9 @@ negative @var{pos} value. A negative number @minus{}@var{pos}, or a list of the form @code{(- @var{pos})}, actually specifies the position of the right edge of the -window with respect to the right edge of the screen, counting toward the -left. +window with respect to the right edge of the screen. A positive value +of @var{pos} counts toward the left. If the parameter is a negative +integer @minus{}@var{pos} then @var{pos} is positive! @item top The screen position of the top edge, in pixels, with respect to the @@ -278,8 +288,9 @@ negative @var{pos} value. A negative number @minus{}@var{pos}, or a list of the form @code{(- @var{pos})}, actually specifies the position of the bottom edge of the -window with respect to the bottom edge of the screen, counting toward the -top. +window with respect to the bottom edge of the screen. A positive value +of @var{pos} counts toward the top. If the parameter is a negative +integer @minus{}@var{pos} then @var{pos} is positive! @item icon-left The screen position of the left edge @emph{of the frame's icon}, in @@ -312,8 +323,8 @@ The number of the X window for the frame. @item minibuffer Whether this frame has its own minibuffer. The value @code{t} means yes, @code{nil} means no, @code{only} means this frame is just a -minibuffer, a minibuffer window (in some other frame) means the new -frame uses that minibuffer. +minibuffer. If the value is a minibuffer window (in some other frame), +the new frame uses that minibuffer. @item buffer-predicate The buffer-predicate function for this frame. The function @@ -351,6 +362,10 @@ value is a string, that specifies a file containing a bitmap to use. Any other non-@code{nil} value specifies the default bitmap icon (a picture of a gnu); @code{nil} specifies a text icon. +@item icon-name +The name to use in the icon for this frame, when and if the icon +appears. If this is @code{nil}, the frame's title is used. + @item foreground-color The color to use for the image of a character. This is a string; the X server defines the meaningful color names. @@ -414,9 +429,10 @@ by the window manager in its usual fashion. Here are some special features for working with sizes and positions: @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, counting from the top left corner of the screen. +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. @end defun @defun frame-height &optional frame @@ -479,13 +495,13 @@ the left or top edge of the screen. A negative integer relates the right or bottom edge of the window to the right or bottom edge of the screen. -@item (+ @var{position}) +@item @code{(+ @var{position})} This specifies the position of the left or top edge of the window relative to the left or top edge of the screen. The integer @var{position} may be positive or negative; a negative value specifies a position outside the screen. -@item (- @var{position}) +@item @code{(- @var{position})} This specifies the position of the right or bottom edge of the window relative to the right or bottom edge of the screen. The integer @var{position} may be positive or negative; a negative value specifies a @@ -494,10 +510,11 @@ position outside the screen. Here is an example: -@smallexample +@example (x-parse-geometry "35x70+0-0") - @result{} ((width . 35) (height . 70) (left . 0) (top - 0)) -@end smallexample + @result{} ((width . 35) (height . 70) + (left . 0) (top - 0)) +@end example @end defun @ignore @@ -538,7 +555,7 @@ invisible frames). The default value of @code{frame-title-format} uses @code{multiple-frames} so as to put the buffer name in the frame title only when there is more than one frame. -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 @@ -598,6 +615,8 @@ The second argument, @var{minibuf}, says which frames to consider: Exclude minibuffer-only frames. @item @code{visible} Consider all visible frames. +@item 0 +Consider all visible or iconified frames. @item a window Consider only the frames using that particular window as their minibuffer. @@ -611,6 +630,9 @@ Like @code{next-frame}, but cycles through all frames in the opposite direction. @end defun + See also @code{next-window} and @code{previous-window}, in @ref{Cyclic +Window Ordering}. + @node Frames and Windows @section Frames and Windows @@ -644,6 +666,9 @@ This function returns the window on @var{frame} that is selected within Conversely, selecting a window for Emacs with @code{select-window} also makes that window selected within its frame. @xref{Selecting Windows}. +Another function that (usually) returns one of the windows in a frame is +@code{minibuffer-window}. @xref{Minibuffer Misc}. + @node Minibuffers and Frames @section Minibuffers and Frames @@ -653,11 +678,10 @@ you can get it with @code{minibuffer-window} (@pxref{Minibuffer Misc}). However, you can also create a frame with no minibuffer. Such a frame must use the minibuffer window of some other frame. When you create the -frame, you can specify explicitly the frame on which to find the -minibuffer to use. If you don't, then the minibuffer is found in the -frame which is the value of the variable -@code{default-minibuffer-frame}. Its value should be a frame that does -have a minibuffer. +frame, you can specify explicitly the minibuffer window to use (in some +other frame). If you don't, then the minibuffer is found in the frame +which is the value of the variable @code{default-minibuffer-frame}. Its +value should be a frame that does have a minibuffer. If you use a minibuffer-only frame, you might want that frame to raise when you enter the minibuffer. If so, set the variable @@ -665,7 +689,7 @@ when you enter the minibuffer. If so, set the variable @defvar default-minibuffer-frame This variable specifies the frame to use for the minibuffer window, by -default. It is always local to the current X terminal and cannot be +default. It is always local to the current terminal and cannot be buffer-local. @xref{Multiple Displays}. @end defvar @@ -697,7 +721,7 @@ lasts until overridden by a subsequent call to @code{switch-frame}. Only the selected terminal frame is actually displayed on the terminal. 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}. +@samp{Emacs} (@pxref{Mode Line Variables}). @c ??? This is not yet implemented properly. @defun select-frame frame @@ -758,7 +782,7 @@ change it. @cindex iconified frame @cindex frame visibility -An X windo frame may be @dfn{visible}, @dfn{invisible}, or +An X window frame may be @dfn{visible}, @dfn{invisible}, or @dfn{iconified}. If it is visible, you can see its contents. If it is iconified, the frame's contents do not appear on the screen, but an icon does. If the frame is invisible, it doesn't show on the screen, not @@ -882,6 +906,11 @@ The usual purpose of tracking mouse motion is to indicate on the screen the consequences of pushing or releasing a button at the current position. +In many cases, you can avoid the need to track the mouse by using +the @code{mouse-face} text property (@pxref{Special Properties}). +That works at a much lower level and runs more smoothly than +Lisp-level mouse tracking. + @ignore @c These are not implemented yet. @@ -991,7 +1020,7 @@ can have the following form: where each pane is a list of form @example -(@var{title} (@var{line} @var{item})...) +(@var{title} (@var{line} . @var{item})...) @end example Each @var{line} should be a string, and each @var{item} should be the @@ -1005,8 +1034,8 @@ individual items in that menu and provide help for them. If instead you implement the menu by defining a command that calls @code{x-popup-menu}, the help facilities cannot know what happens inside that command, so they cannot give any help for the menu's items. This is the reason why -all the menu bar items except @samp{Buffers} are implemented with menu -keymaps (@pxref{Menu Keymaps}). +all the menu bar items are normally implemented with menu keymaps +(@pxref{Menu Keymaps}). @node Dialog Boxes @section Dialog Boxes @@ -1144,40 +1173,8 @@ This function stores @var{string} into the first cut buffer (cut buffer like the way successive kills in Emacs move down the kill ring. @end defun -@node X Connections -@section X Connections - -You can close the connection with the X server with the function -@code{x-close-current-connection}, and open a new one with -@code{x-open-connection} (perhaps with a different server and display). - -@defun x-close-current-connection -This function closes the connection to the X server. It deletes all -frames, making Emacs effectively inaccessible to the user; therefore, a -Lisp program that closes the connection should open another one. -@end defun - -@defun x-open-connection display &optional resource-string -This function opens a connection to an X server, for use of display -@var{display}. - -The optional argument @var{resource-string} is a string of resource -names and values, in the same format used in the @file{.Xresources} -file. The values you specify override the resource values recorded in -the X server itself. Here's an example of what this string might look -like: - -@example -"*BorderWidth: 3\n*InternalBorder: 2\n" -@end example - -@xref{Resources}. -@end defun - -@defun x-display-color-p -This returns @code{t} if the connected X display has color, and -@code{nil} otherwise. -@end defun +@node Color Names +@section Color Names @defun x-color-defined-p color This function reports whether a color name is meaningful. It returns @@ -1221,39 +1218,27 @@ defined, the value is @code{nil}. @end example @end defun -@defun x-synchronize flag -The function @code{x-synchronize} enables or disables synchronous -communication with the X server. It enables synchronous communication -if @var{flag} is non-@code{nil}, and disables it if @var{flag} is -@code{nil}. - -In synchronous mode, Emacs waits for a response to each X protocol -command before doing anything else. This is useful for debugging Emacs, -because protocol errors are reported right away, which helps you find -the erroneous command. Synchronous mode is not the default because it -is much slower. -@end defun - @node Resources @section X Resources -@defun x-get-resource attribute &optional component subclass +@defun x-get-resource attribute class &optional component subclass The function @code{x-get-resource} retrieves a resource value from the X Windows defaults database. Resources are indexed by a combination of a @dfn{key} and a @dfn{class}. This function searches using a key of the form @samp{@var{instance}.@var{attribute}} (where @var{instance} is the name -under which Emacs was invoked), and using @samp{Emacs} as the class. +under which Emacs was invoked), and using @samp{Emacs.@var{class}} as +the class. The optional arguments @var{component} and @var{subclass} add to the key and the class, respectively. You must specify both of them or neither. If you specify them, the key is @samp{@var{instance}.@var{component}.@var{attribute}}, and the class is -@samp{Emacs.@var{subclass}}. +@samp{Emacs.@var{class}.@var{subclass}}. @end defun - @xref{Resources X, X Resources,, emacs, The GNU Emacs Manual}. + @xref{Resources X,, X Resources, emacs, The GNU Emacs Manual}. @node Server Data @section Data about the X Server @@ -1263,8 +1248,8 @@ get information about the capabilities and origin of an X display that Emacs is using. Each of these functions lets you specify the display you are interested in: the @var{display} argument can be either a display name, or a frame (meaning use the display that frame is on). If -you omit the @var{display} argument, that means to use the selected -frame's display. +you omit the @var{display} argument, or specify @code{nil}, that means +to use the selected frame's display. @defun x-display-screens &optional display This function returns the number of screens associated with the display. diff --git a/lispref/functions.texi b/lispref/functions.texi index 0f596cb6216..27a521df702 100644 --- a/lispref/functions.texi +++ b/lispref/functions.texi @@ -79,7 +79,9 @@ Structures}. A @dfn{macro} is a construct defined in Lisp by the programmer. It differs from a function in that it translates a Lisp expression that you write into an equivalent expression to be evaluated instead of the -original expression. @xref{Macros}, for how to define and use macros. +original expression. Macros enable Lisp programmers to do the sorts of +things that special forms can do. @xref{Macros}, for how to define and +use macros. @item command @cindex command @@ -150,9 +152,11 @@ function. For example: @end example @noindent -(Such a list is called a @dfn{lambda expression} for historical reasons, -even though it is not really an expression at all---it is not a form -that can be evaluated meaningfully.) +Such a list is called a @dfn{lambda expression}. In Emacs Lisp, it +actually is valid as an expression---it evaluates to itself. In some +other Lisp dialects, a lambda expression is not a valid expression at +all. In either case, its main use is not to be evaluated as an +expression, but to be called as a function. @menu * Lambda Components:: The parts of a lambda expression. @@ -374,17 +378,17 @@ actually appears inside the Lisp world and can be used by the Emacs help facilities. @xref{Documentation}, for how the @var{documentation-string} is accessed. - It is a good idea to provide documentation strings for all commands, -and for all other functions in your program that users of your program -should know about; internal functions might as well have only comments, -since comments don't take up any room when your program is loaded. + It is a good idea to provide documentation strings for all the +functions in your program, even those that are only called from within +your program. Documentation strings are like comments, except that they +are easier to access. The first line of the documentation string should stand on its own, because @code{apropos} displays just this first line. It should consist of one or two complete sentences that summarize the function's purpose. - The start of the documentation string is usually indented, but since -these spaces come before the starting double-quote, they are not part of + The start of the documentation string is usually indented in the source file, +but since these spaces come before the starting double-quote, they are not part of the string. Some people make a practice of indenting any additional lines of the string so that the text lines up in the program source. @emph{This is a mistake.} The indentation of the following lines is @@ -532,11 +536,21 @@ deliberate redefinition from unintentional redefinition. @defun defalias name definition This special form defines the symbol @var{name} as a function, with definition @var{definition} (which can be any valid Lisp function). -It's best to use this rather than @code{fset} when defining a function -in a file, because @code{defalias} records which file defined the -function (@pxref{Unloading}), while @code{fset} does not. + +The proper place to use @code{defalias} is where a specific function +name is being defined---especially where that name appears explicitly in +the source file being loaded. This is because @code{defalias} records +which file defined the function, just like @code{defun} +(@pxref{Unloading}). + +By contrast, in programs that manipulate function definitions for other +purposes, it is better to use @code{fset}, which does not keep such +records. @end defun + See also @code{defsubst}, which defines a function like @code{defun} +and tells the Lisp compiler to open-code it. @xref{Inline Functions}. + @node Calling Functions @section Calling Functions @cindex function invocation @@ -645,8 +659,8 @@ find them in data structures (especially in hook variables and property lists) and call them using @code{funcall} or @code{apply}. Functions that accept function arguments are often called @dfn{functionals}. - Sometimes, when you call such a function, it is useful to supply a -no-op function as the argument. Here are two different kinds of no-op + Sometimes, when you call a functional, it is useful to supply a no-op +function as the argument. Here are two different kinds of no-op function: @defun identity arg @@ -1007,7 +1021,7 @@ Functions}. @end defun When writing a function that extends a previously defined function, -the following idiom is often used: +the following idiom is sometimes used: @example (fset 'old-foo (symbol-function 'foo)) @@ -1027,6 +1041,9 @@ defines @code{foo} rather than @code{old-foo}, it does not produce the proper results. The only way to avoid this problem is to make sure the file is loaded before moving aside the old definition of @code{foo}. + But it is unmodular and unclean, in any case, for a Lisp file to +redefine a function defined elsewhere. + @node Inline Functions @section Inline Functions @cindex inline functions @@ -1063,7 +1080,7 @@ Evaluation}.) Inline functions can be used and open-coded later on in the same file, following the definition, just like macros. -Emacs versions prior to 19 did not have inline functions. +@c Emacs versions prior to 19 did not have inline functions. @node Related Topics @section Other Topics Related to Functions diff --git a/lispref/help.texi b/lispref/help.texi index 396d11b01ed..b0466962a6c 100644 --- a/lispref/help.texi +++ b/lispref/help.texi @@ -60,7 +60,7 @@ documentation is displayed. This allows documentation strings to refer to the keys for related commands and be accurate even when a user rearranges the key bindings. (@xref{Accessing Documentation}.) - Within the Lisp world, a documentation string is kept with the + Within the Lisp world, a documentation string accessible through the function or variable that it describes: @itemize @bullet @@ -81,14 +81,17 @@ function @code{documentation-property} knows how to extract it. @cindex @file{etc/DOC-@var{version}} To save space, the documentation for preloaded functions and variables (including primitive functions and autoloaded functions) is stored in -the file @file{emacs/etc/DOC-@var{version}}. The data structure inside -Emacs has an integer offset into the file, where the documentation -string ought to be. The functions @code{documentation} and -@code{documentation-property} read the documentation from the file -@file{emacs/etc/DOC-@var{version}} when they notice the integer there; -this is transparent to the user. Keeping the documentation strings out -of the Emacs core image saves a significant amount of space. -@xref{Building Emacs}. +the file @file{emacs/etc/DOC-@var{version}}. The documentation for +functions and variables loaded during the Emacs session from +byte-compiled files is stored in those files (@pxref{Docs and +Compilation}). + +The data structure inside Emacs has an integer offset into the file, or +a list containing a string and an integer, in place of the documentation +string. The functions @code{documentation} and +@code{documentation-property} use that information to read the +documentation from the appropriate file; this is transparent to the +user. For information on the uses of documentation strings, see @ref{Help, , Help, emacs, The GNU Emacs Manual}. @@ -105,10 +108,10 @@ use to print nice-looking hardcopy for the file @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 -retrieves the text from the file @file{emacs/etc/DOC-@var{version}} 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}; the @var{verbatim} argument exists only as of Emacs 19.) +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}; the +@var{verbatim} argument exists only as of Emacs 19.) @smallexample @group @@ -124,14 +127,10 @@ non-@code{nil}; the @var{verbatim} argument exists only as of Emacs 19.) @end defun @defun documentation function &optional verbatim -This function returns the documentation string of @var{function}. -This function will access the documentation string if it is stored in -the @file{emacs/etc/DOC-@var{version}} file. - -In addition, @code{documentation} runs @code{substitute-command-keys} -on the resulting string, so the value contains the actual (current) key -bindings. (This is not done if @var{verbatim} is non-@code{nil}; the -@var{verbatim} argument exists only as of Emacs 19.) +This function returns the documentation string of @var{function}. It +reads the text from a file if necessary. Then (unless @var{verbatim} is +non-@code{nil}) it calls @code{substitute-command-keys}, to return a +value containing the actual (current) key bindings. The function @code{documentation} signals a @code{void-function} error if @var{function} has no function definition. However, it is ok if diff --git a/lispref/hooks.texi b/lispref/hooks.texi index 472b57fd1a6..18f8bcfcad5 100644 --- a/lispref/hooks.texi +++ b/lispref/hooks.texi @@ -3,7 +3,7 @@ @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/hooks -@node Standard Hooks, Antinews, Standard Keymaps, Top +@node Standard Hooks, Index, Standard Keymaps, Top @appendix Standard Hooks The following is a list of hook variables that let you provide @@ -122,5 +122,5 @@ special way (they are passed arguments, or else their values are used). @item window-setup-hook @item write-contents-hooks @item write-file-hooks -@item write-region-annotation-functions +@item write-region-annotate-functions @end table diff --git a/lispref/internals.texi b/lispref/internals.texi index 352dd226d28..c1b17f62b4a 100644 --- a/lispref/internals.texi +++ b/lispref/internals.texi @@ -103,8 +103,8 @@ running. It is useful to include this string in bug reports. @example @group (emacs-version) - @result{} "GNU Emacs 19.22.1 of Fri Feb 27 1994 \ -on slug (berkeley-unix)" + @result{} "GNU Emacs 19.29.1 (i386-debian-linux) \ + of Tue Jun 6 1995 on balloon" @end group @end example @@ -113,20 +113,20 @@ echo area. @end deffn @defvar emacs-build-time - The value of this variable is the time at which Emacs was built at the +The value of this variable is the time at which Emacs was built at the local site. @example @group emacs-build-time - @result{} "Fri Feb 27 14:55:57 1994" + @result{} "Tue Jun 6 14:55:57 1995" @end group @end example @end defvar @defvar emacs-version The value of this variable is the version of Emacs being run. It is a -string such as @code{"19.22.1"}. +string such as @code{"19.29.1"}. @end defvar The following two variables did not exist before Emacs version 19.23, @@ -135,12 +135,12 @@ convenient in the future. @defvar emacs-major-version The major version number of Emacs, as an integer. For Emacs version -19.23, the value is 19. +19.29, the value is 19. @end defvar @defvar emacs-minor-version The minor version number of Emacs, as an integer. For Emacs version -19.23, the value is 23. +19.29, the value is 29. @end defvar @node Pure Storage, Garbage Collection, Building Emacs, GNU Emacs Internals @@ -332,7 +332,7 @@ that the subsequent garbage collection does not happen immediately when the threshold is exhausted, but only the next time the Lisp evaluator is called. -The initial threshold value is 100,000. If you specify a larger +The initial threshold value is 300,000. If you specify a larger value, garbage collection will happen less often. This reduces the amount of time spent garbage collecting, but increases total memory use. You may want to do this when running a program that creates lots of @@ -727,6 +727,10 @@ in this buffer, and their values, with the exception of local variables that have special slots in the buffer object. (Those slots are omitted from this table.) @xref{Buffer-Local Variables}. +@item base_buffer +This field holds the buffer's base buffer (if it is an indirect buffer), +or @code{nil}. + @item keymap This field holds the buffer's local keymap. @xref{Keymaps}. @@ -920,4 +924,8 @@ The file descriptor for output to the process. The file descriptor for the terminal that the subprocess is using. (On some systems, there is no need to record this, so the value is @code{nil}.) + +@item tty_name +The name of the terminal that the subprocess is using, +or @code{nil} if it is using pipes. @end table diff --git a/lispref/intro.texi b/lispref/intro.texi index f6fe12dfa88..3b310cdf3ed 100644 --- a/lispref/intro.texi +++ b/lispref/intro.texi @@ -536,7 +536,7 @@ manual. You may want to skip this section and refer back to it later. Throughout this manual, the phrases ``the Lisp reader'' and ``the Lisp printer'' are used to refer to those routines in Lisp that convert -textual representations of Lisp objects into actual objects, and vice +textual representations of Lisp objects into actual Lisp objects, and vice versa. @xref{Printed Representation}, for more details. You, the person reading this manual, are thought of as ``the programmer'' and are addressed as ``you''. ``The user'' is the person who uses Lisp programs, @@ -554,7 +554,7 @@ in this font or form: @var{first-number}. @cindex boolean @cindex false - In Lisp, the symbol @code{nil} is overloaded with three meanings: it + In Lisp, the symbol @code{nil} has three separate meanings: it is a symbol with the name @samp{nil}; it is the logical truth value @var{false}; and it is the empty list---the list of zero elements. When used as a variable, @code{nil} always has the value @code{nil}. diff --git a/lispref/keymaps.texi b/lispref/keymaps.texi index 8e09e3e4dfc..274e36f451f 100644 --- a/lispref/keymaps.texi +++ b/lispref/keymaps.texi @@ -74,7 +74,7 @@ intermediate bindings (found for the events before the last) are all keymaps; if this is not so, the sequence of events does not form a unit---it is not really a key sequence. In other words, removing one or more events from the end of any valid key must always yield a prefix -key. For example, @kbd{C-f C-f} is not a key; @kbd{C-f} is not a prefix +key. For example, @kbd{C-f C-n} is not a key; @kbd{C-f} is not a prefix key, so a longer sequence starting with @kbd{C-f} cannot be a key. Note that the set of possible multi-event key sequences depends on the @@ -207,6 +207,7 @@ otherwise. More precisely, this function tests for a list whose Here we describe the functions for creating keymaps. +@c ??? This should come after makr-sparse-keymap @defun make-keymap &optional prompt This function creates and returns a new full keymap (i.e., one containing a vector of length 128 for defining all the @sc{ASCII} @@ -570,9 +571,8 @@ is the order of @code{minor-mode-map-alist}. But you should design minor modes so that they don't interfere with each other. If you do this properly, the order will not matter. -See also @code{minor-mode-key-binding} in @ref{Functions for Key -Lookup}. See @ref{Keymaps and Minor Modes}, for more information about -minor modes. +See also @code{minor-mode-key-binding}, above. See @ref{Keymaps and +Minor Modes}, for more information about minor modes. @end defvar @defvar overriding-local-map @@ -594,7 +594,7 @@ menu bar display. So if a menu bar key sequence comes in, you should clear @code{overriding-local-map} before looking up and executing that key sequence. Modes that use @code{overriding-local-map} would typically do this anyway; normally they respond to events that they do -not handle by ``unreading'' them and and exiting. +not handle by ``unreading'' them and exiting. @end defvar @node Key Lookup @@ -650,12 +650,11 @@ event of the key sequence is looked up in @var{keymap}. The events used so far in the lookup form a complete key, and @var{command} is its binding. @xref{What Is a Function}. -@item @var{string} -@itemx @var{vector} +@item @var{array} @cindex string in keymap -The events used so far in the lookup form a complete key, whose -binding is a keyboard macro. See @ref{Keyboard Macros}, for more -information. +The array (either a string or a vector) is a keyboard macro. The events +used so far in the lookup form a complete key, and the array is its +binding. See @ref{Keyboard Macros}, for more information. @item @var{list} @cindex list in keymap @@ -685,7 +684,7 @@ binding of @var{othertype} in @var{othermap} and uses that. This feature permits you to define one key as an alias for another key. For example, an entry whose @sc{car} is the keymap called @code{esc-map} -and whose @sc{cdr} is 32 (the code for space) means, ``Use the global +and whose @sc{cdr} is 32 (the code for @key{SPC}) means, ``Use the global binding of @kbd{Meta-@key{SPC}}, whatever that may be.'' @end itemize @@ -935,6 +934,10 @@ key name). For example, @code{(control ?a)} is equivalent to @code{?\C-a} and @code{(hyper control left)} is equivalent to @code{C-H-left}. + One advantage of using a list to represent the event type is that the +precise numeric codes for the modifier bits don't appear in compiled +files. + For the functions below, an error is signaled if @var{keymap} is not a keymap or if @var{key} is not a string or vector representing a key sequence. You can use event types (symbols) as shorthand for events @@ -1146,6 +1149,13 @@ or @end smallexample @noindent +or + +@smallexample +(global-set-key [(control ?x) (control ?\\)] 'next-line) +@end smallexample + +@noindent redefines @kbd{C-x C-\} to move down a line. @smallexample @@ -1431,8 +1441,8 @@ You can also supply a second string, called the help string, as follows: Currently Emacs does not actually use @var{help-string}; it knows only how to ignore @var{help-string} in order to extract @var{real-binding}. -In the future we hope to make @var{help-string} serve as extended -documentation for the menu item, available on request. +In the future we may use @var{help-string} as extended documentation for +the menu item, available on request. If @var{real-binding} is @code{nil}, then @var{string} appears in the menu but cannot be selected. @@ -1445,6 +1455,11 @@ the menu item only if the expression's value is non-@code{nil}. When a menu item is disabled, it is displayed in a ``fuzzy'' fashion, and cannot be selected with the mouse. +The menu bar does not recalculate which items are enabled every time you +look at a menu. This is because the X toolkit requires the whole tree +of menus in advance. To force recalculation of the menu bar, call +@code{force-mode-line-update} (@pxref{Mode Line Format}). + Sometimes it is useful to make menu items that use the ``same'' command but with different enable conditions. You can do this by defining alias commands. Here's an example that makes two aliases for @@ -1539,10 +1554,14 @@ When the user has found the desired alternative from the menu, he or she should type the corresponding character---the one whose binding is that alternative. +@ignore In a menu intended for keyboard use, each menu item must clearly indicate what character to type. The best convention to use is to make -the character the first letter of the item string. That is something -users will understand without being told. +the character the first letter of the item string---that is something +users will understand without being told. We plan to change this; by +the time you read this manual, keyboard menus may explicitly name the +key for each alternative. +@end ignore This way of using menus in an Emacs-like editor was inspired by the Hierarkey system. @@ -1616,8 +1635,8 @@ were @code{nil}. @xref{Active Keymaps}. parameter must be greater than zero. Emacs uses just one line for the menu bar itself; if you specify more than one line, the other lines serve to separate the menu bar from the windows in the frame. We -recommend you try 1 or 2 as the value of @code{menu-bar-lines}. @xref{X -Frame Parameters}. +recommend 1 or 2 as the value of @code{menu-bar-lines}. @xref{X Frame +Parameters}. Here's an example of setting up a menu bar item: diff --git a/lispref/lists.texi b/lispref/lists.texi index 55ce93c9547..6bb33b80126 100644 --- a/lispref/lists.texi +++ b/lispref/lists.texi @@ -543,9 +543,9 @@ Here are some examples where the final argument is not a list: @example (append '(x y) 'z) - @result{} (x y z) + @result{} (x y . z) (append '(x y) [z]) - @result{} (x y [z]) + @result{} (x y . [z]) @end example @noindent @@ -980,11 +980,6 @@ sorted order. If you wish to make a sorted copy without destroying the original, copy it first with @code{copy-sequence} and then sort. Sorting does not change the @sc{car}s of the cons cells in @var{list}; -each cons cell in the result contains the same element that it contained -before. The result differs from the argument @var{list} because the -cells themselves have been reordered. - -Sorting does not change the @sc{car}s of the cons cells in @var{list}; the cons cell that originally contained the element @code{a} in @var{list} still has @code{a} in its @sc{car} after sorting, but it now appears in a different position in the list due to the change of @@ -1106,8 +1101,8 @@ sample-list @end group @end example -Note that @code{(delq 'b sample-list)} modifies @code{sample-list} to -splice out the second element, but @code{(delq 'a sample-list)} does not +Note that @code{(delq 'c sample-list)} modifies @code{sample-list} to +splice out the third element, but @code{(delq 'a sample-list)} does not splice anything---it just returns a shorter list. Don't assume that a variable which formerly held the argument @var{list} now has fewer elements, or that it still holds the original list! Instead, save the @@ -1178,6 +1173,9 @@ GNU Emacs Lisp are derived from Maclisp, not Common Lisp. The Common Lisp versions do not use @code{equal} to compare elements. @end quotation + See also the function @code{add-to-list}, in @ref{Setting Variables}, +for another way to add an element to a list stored in a variable. + @node Association Lists @section Association Lists @cindex association list diff --git a/lispref/loading.texi b/lispref/loading.texi index 645ada83976..3f88132b20b 100644 --- a/lispref/loading.texi +++ b/lispref/loading.texi @@ -37,7 +37,7 @@ containing Lisp code. * How Programs Do Loading:: The @code{load} function and others. * Autoload:: Setting up a function to autoload. * Repeated Loading:: Precautions about loading a file twice. -* Features:: Loading a library if it isn't already loaded. +* Named Features:: Loading a library if it isn't already loaded. * Unloading:: How to ``unload'' a library that was loaded. * Hooks for Loading:: Providing code to be run when particular libraries are loaded. @@ -50,7 +50,7 @@ containing Lisp code. @code{autoload} creates a placeholder object for a function in a file; trying to call the autoloading function loads the file to get the function's real definition (@pxref{Autoload}). @code{require} loads a -file if it isn't already loaded (@pxref{Features}). Ultimately, all +file if it isn't already loaded (@pxref{Named Features}). Ultimately, all these facilities call the @code{load} function to do the work. @defun load filename &optional missing-ok nomessage nosuffix @@ -136,9 +136,10 @@ default value is specified in @file{emacs/src/paths.h} when Emacs is built. The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH}; -@samp{:} separates directory names, and @samp{.} is used for the current -default directory. Here is an example of how to set your -@code{EMACSLOADPATH} variable from a @code{csh} @file{.login} file: +@samp{:} (or @samp{;}, according to the operating system) separates +directory names, and @samp{.} is used for the current default directory. +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 @@ -192,9 +193,7 @@ calls to @code{load}. @defvar load-in-progress This variable is non-@code{nil} if Emacs is in the process of loading a -file, and it is @code{nil} otherwise. This is how @code{defun} and -@code{provide} determine whether a load is in progress, so that their -effect can be undone if the load fails. +file, and it is @code{nil} otherwise. @end defvar @defvar load-read-function @@ -213,9 +212,9 @@ functions should use @code{read}. @cindex autoload The @dfn{autoload} facility allows you to make a function or macro -available but put off loading its actual definition. The first call to -the function automatically reads the proper file to install the real -definition and other associated code, then runs the real definition +known in Lisp, but put off loading the file that defines it. The first +call to the function automatically reads the proper file to install the +real definition and other associated code, then runs the real definition as if it had been loaded all along. There are two ways to set up an autoloaded function: by calling @@ -378,11 +377,16 @@ To avoid the problem, write this: (cons '(leif-mode " Leif") minor-mode-alist))) @end example + To add an element to a list just once, use @code{add-to-list} +(@pxref{Setting Variables}). + Occasionally you will want to test explicitly whether a library has already been loaded. Here's one way to test, in a library, whether it has been loaded before: @example +(defvar foo-was-loaded) + (if (not (boundp 'foo-was-loaded)) @var{execute-first-time-only}) @@ -393,10 +397,10 @@ has been loaded before: If the library uses @code{provide} to provide a named feature, you can use @code{featurep} to test whether the library has been loaded. @ifinfo -@xref{Features}. +@xref{Named Features}. @end ifinfo -@node Features +@node Named Features @section Features @cindex features @cindex requiring features @@ -500,9 +504,10 @@ features @result{} (foo bar bish) @end smallexample -If the file isn't completely loaded, due to an error in the evaluating -its contents, any function definitions or @code{provide} calls that -occurred during the load are undone. @xref{Autoload}. +When a file is loaded to satisfy an autoload, and it stops due to an +error in the evaluating its contents, any function definitions or +@code{provide} calls that occurred during the load are undone. +@xref{Autoload}. @end defun @defun require feature &optional filename @@ -544,7 +549,8 @@ This command unloads the library that provided feature @var{feature}. It undefines all functions, macros, and variables defined in that library with @code{defconst}, @code{defvar}, @code{defun}, @code{defmacro}, @code{defsubst} and @code{defalias}. It then restores -any autoloads formerly associated with those symbols. +any autoloads formerly associated with those symbols. (Loading +saves these in the @code{autoload} property of the symbol.) Ordinarily, @code{unload-feature} refuses to unload a library on which other loaded libraries depend. (A library @var{a} depends on library @@ -615,7 +621,7 @@ do (1), you can do it immediately---there is no need to wait for when the library is loaded. To do (2), you must load the library (preferably with @code{require}). -But it is to use @code{eval-after-load} in your personal customizations +But it is ok to use @code{eval-after-load} in your personal customizations if you don't feel they must meet the design standards of programs to be released. diff --git a/lispref/locals.texi b/lispref/locals.texi index 24db38d7f60..86e6750248c 100644 --- a/lispref/locals.texi +++ b/lispref/locals.texi @@ -28,6 +28,9 @@ define such variables for their internal use; we don't list them here. @item buffer-display-table @pxref{Display Tables} +@item buffer-file-format +@pxref{Format Conversion} + @item buffer-file-name @pxref{Buffer File Name} @@ -40,6 +43,9 @@ define such variables for their internal use; we don't list them here. @item buffer-file-type @pxref{Files and MS-DOS} +@item buffer-invisibility-spec +@pxref{Invisible Text} + @item buffer-offer-save @pxref{Saving Buffers} @@ -121,6 +127,9 @@ define such variables for their internal use; we don't list them here. @item paragraph-start @pxref{Standard Regexps} +@item point-before-scroll +Used for communication between mouse commands and scroll-bar commands. + @item require-final-newline @pxref{Insertion} diff --git a/lispref/macros.texi b/lispref/macros.texi index c5cf625c8c7..22a07f14dbe 100644 --- a/lispref/macros.texi +++ b/lispref/macros.texi @@ -163,8 +163,11 @@ macro in the same file where it is used and before its first use. Byte-compiling a file executes any @code{require} calls at top-level in the file. This is in case the file needs the required packages for proper compilation. One way to ensure that necessary macro definitions -are available during compilation is to require the file that defines -them. @xref{Features}. +are available during compilation is to require the files that define +them (@pxref{Named Features}). To avoid loading the macro definition files +when someone @emph{runs} the compiled program, write +@code{eval-when-compile} around the @code{require} calls (@pxref{Eval +During Compile}). @node Defining Macros @section Defining Macros @@ -176,9 +179,9 @@ from the macro call. It is possible to use an anonymous Lisp macro just like an anonymous function, but this is never done, because it does not make sense to pass -an anonymous macro to mapping functions such as @code{mapcar}. In -practice, all Lisp macros have names, and they are usually defined with -the special form @code{defmacro}. +an anonymous macro to functionals such as @code{mapcar}. In practice, +all Lisp macros have names, and they are usually defined with the +special form @code{defmacro}. @defspec defmacro name argument-list body-forms@dots{} @code{defmacro} defines the symbol @var{name} as a macro that looks @@ -207,7 +210,7 @@ called interactively. Macros often need to construct large list structures from a mixture of constants and nonconstant parts. To make this easier, use the macro -@code{`} (often called @dfn{backquote}). +@samp{`} (often called @dfn{backquote}). Backquote allows you to quote a list, but selectively evaluate elements of that list. In the simplest case, it is identical to the @@ -226,9 +229,9 @@ two forms yield identical results: @end example @findex , @r{(with Backquote)} -The special marker @code{,} inside of the argument to backquote +The special marker @samp{,} inside of the argument to backquote indicates a value that isn't constant. Backquote evaluates the -argument of @code{,} and puts the value in the list structure: +argument of @samp{,} and puts the value in the list structure: @example @group @@ -244,9 +247,9 @@ argument of @code{,} and puts the value in the list structure: @findex ,@@ @r{(with Backquote)} @cindex splicing (with backquote) You can also @dfn{splice} an evaluated value into the resulting list, -using the special marker @code{,@@}. The elements of the spliced list +using the special marker @samp{,@@}. The elements of the spliced list become elements at the same level as the other elements of the resulting -list. The equivalent code without using @code{`} is often unreadable. +list. The equivalent code without using @samp{`} is often unreadable. Here are some examples: @example @@ -280,12 +283,12 @@ Here are some examples: @end example @quotation -Before Emacs version 19.29, @code{`} used a different syntax which +Before Emacs version 19.29, @samp{`} used a different syntax which required an extra level of parentheses around the entire backquote -construct. Likewise, each @code{,} or @code{,@@} substition required an -extra level of parentheses surrounding both the @code{,} or @code{,@@} +construct. Likewise, each @samp{,} or @samp{,@@} substition required an +extra level of parentheses surrounding both the @samp{,} or @samp{,@@} and the following expression. The old syntax required whitespace -between the @code{`}, @code{,} or @code{,@@} and the following +between the @samp{`}, @samp{,} or @samp{,@@} and the following expression. This syntax is still accepted, but no longer recommended except for @@ -363,10 +366,10 @@ Here's an equivalent definition simplified through use of backquote: (defmacro for (var from init to final do &rest body) "Execute a simple \"for\" loop. For example, (for i from 1 to 10 do (print i))." - (` (let (((, var) (, init))) - (while (<= (, var) (, final)) - (,@@ body) - (inc (, var)))))) + `(let ((,var ,init)) + (while (<= ,var ,final) + ,@@body + (inc ,var)))) @end group @end smallexample @@ -400,11 +403,11 @@ Here is a macro definition that creates this expansion: @group (defmacro for (var from init to final do &rest body) "Execute a simple for loop: (for i from 1 to 10 do (print i))." - (` (let (((, var) (, init)) - (max (, final))) - (while (<= (, var) max) - (,@@ body) - (inc (, var)))))) + `(let ((,var ,init) + (max ,final)) + (while (<= ,var max) + ,@@body + (inc ,var)))) @end group @end smallexample @@ -427,11 +430,11 @@ number of times: "Execute a simple for loop: (for i from 1 to 10 do (print i))." @end group @group - (` (let (((, var) (, init)) - (max (, final))) - (while (<= (, var) max) - (,@@ body) - (inc (, var)))))) + `(let ((,var ,init) + (max ,final)) + (while (<= ,var max) + ,@@body + (inc ,var)))) @end group @end smallexample @end ifinfo @@ -469,11 +472,11 @@ this way: (defmacro for (var from init to final do &rest body) "Execute a simple for loop: (for i from 1 to 10 do (print i))." (let ((tempvar (make-symbol "max"))) - (` (let (((, var) (, init)) - ((, tempvar) (, final))) - (while (<= (, var) (, tempvar)) - (,@@ body) - (inc (, var))))))) + `(let ((,var ,init) + (,tempvar ,final)) + (while (<= ,var ,tempvar) + ,@@body + (inc ,var))))) @end group @end smallexample diff --git a/lispref/maps.texi b/lispref/maps.texi index d27be34d76e..77dc80001b9 100644 --- a/lispref/maps.texi +++ b/lispref/maps.texi @@ -29,9 +29,15 @@ A sparse keymap used by C mode. A full keymap used by Command History mode. @item ctl-x-4-map +@vindex ctl-x-4-map A sparse keymap for subcommands of the prefix @kbd{C-x 4}. +@item ctl-x-5-map +@vindex ctl-x-5-map +A sparse keymap for subcommands of the prefix @kbd{C-x 5}. + @item ctl-x-map +@vindex ctl-x-map A full keymap for @kbd{C-x} commands. @item debugger-mode-map @@ -42,10 +48,6 @@ A full keymap used by Debugger mode. @vindex dired-mode-map A full keymap for @code{dired-mode} buffers. -@item doctor-mode-map -@vindex doctor-mode-map -A sparse keymap used by Doctor mode. - @item edit-abbrevs-map @vindex edit-abbrevs-map A sparse keymap used in @code{edit-abbrevs}. @@ -66,6 +68,38 @@ A full keymap used by Electric Command History mode. @vindex emacs-lisp-mode-map A sparse keymap used by Emacs Lisp mode. +@item facemenu-menu +@vindex facemenu-menu +The keymap that displays the Text Properties menu. + +@item facemenu-background-menu +@vindex facemenu-background-menu +The keymap that displays the Background Color submenu of the Text +Properties menu. + +@item facemenu-face-menu +@vindex facemenu-face-menu +The keymap that displays the Face submenu of the Text Properties menu. + +@item facemenu-foreground-menu +@vindex facemenu-foreground-menu +The keymap that displays the Foreground Color submenu of the Text +Properties menu. + +@item facemenu-indentation-menu +@vindex facemenu-indentation-menu +The keymap that displays the Indentation submenu of the Text Properties menu. + +@item facemenu-justification-menu +@vindex facemenu-justification-menu +The keymap that displays the Justification submenu of the Text +Properties menu. + +@item facemenu-special-menu +@vindex facemenu-special-menu +The keymap that displays the Special Props submenu of the Text +Properties menu. + @item function-key-map @vindex function-key-map The keymap for translating keypad and function keys.@* @@ -91,6 +125,7 @@ A sparse keymap used by the @kbd{e} command of Info. A sparse keymap containing Info commands. @item isearch-mode-map +@vindex isearch-mode-map A keymap that defines the characters you can type within incremental search. @@ -107,7 +142,28 @@ A sparse keymap used by Lisp mode. @vindex lisp-mode-map A sparse keymap used by Lisp mode. +@item menu-bar-edit-menu +@vindex menu-bar-edit-menu +The keymap which displays the Edit menu in the menu bar. + +@item menu-bar-files-menu +@vindex menu-bar-files-menu +The keymap which displays the Files menu in the menu bar. + +@item menu-bar-help-menu +@vindex menu-bar-help-menu +The keymap which displays the Help menu in the menu bar. + +@item menu-bar-search-menu +@vindex menu-bar-search-menu +The keymap which displays the Search menu in the menu bar. + +@item menu-bar-tools-menu +@vindex menu-bar-tools-menu +The keymap which displays the Tools menu in the menu bar. + @item mode-specific-map +@vindex mode-specific-map The keymap for characters following @kbd{C-c}. Note, this is in the global map. This map is not actually mode specific: its name was chosen to be informative for the user in @kbd{C-h b} (@code{display-bindings}), @@ -118,6 +174,7 @@ where it describes the main use of the @kbd{C-c} prefix key. A local keymap used by Occur mode. @item query-replace-map +@vindex query-replace-map A local keymap used for responses in @code{query-replace} and related commands; also for @code{y-or-n-p} and @code{map-y-or-n-p}. The functions that use this map do not support prefix keys; they look up one event at a diff --git a/lispref/markers.texi b/lispref/markers.texi index ef991890a18..8c41fa17f17 100644 --- a/lispref/markers.texi +++ b/lispref/markers.texi @@ -496,10 +496,10 @@ The return value is not meaningful. @defopt transient-mark-mode @cindex Transient Mark mode -This variable enables Transient Mark mode, in which every -buffer-modifying primitive sets @code{deactivate-mark}. The consequence -of this is that commands that modify the buffer normally make the mark -inactive. +This variable if non-@code{nil} enables Transient Mark mode, in which +every buffer-modifying primitive sets @code{deactivate-mark}. The +consequence of this is that commands that modify the buffer normally +make the mark inactive. @end defopt @defvar deactivate-mark diff --git a/lispref/minibuf.texi b/lispref/minibuf.texi index 10dc146535e..17efa0e8dc8 100644 --- a/lispref/minibuf.texi +++ b/lispref/minibuf.texi @@ -61,7 +61,7 @@ name on command symbols (@pxref{Minibuffer Misc}). Like other buffers, a minibuffer may use any of several local keymaps (@pxref{Keymaps}); these contain various exit commands and in some cases -completion commands. @xref{Completion}. +completion commands (@pxref{Completion}). @itemize @bullet @item @@ -87,6 +87,11 @@ also be used to read a Lisp object in textual form. The most basic primitive for minibuffer input is @code{read-from-minibuffer}; it can do either one. + In most cases, you should not call minibuffer input functions in the +middle of a Lisp function. Instead, do all minibuffer input as part of +reading the arguments for a command, in the @code{interactive} spec. +@xref{Defining Commands}. + @defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist This function is the most general way to get input through the minibuffer. By default, it accepts arbitrary text and returns it as a @@ -199,12 +204,9 @@ possible to put a space into the string, by quoting it. @defvar minibuffer-local-ns-map This built-in variable is the keymap used as the minibuffer local keymap in the function @code{read-no-blanks-input}. By default, it makes the -following bindings: +following bindings, in addition to those of @code{minibuffer-local-map}: @table @asis -@item @key{LFD} -@code{exit-minibuffer} - @item @key{SPC} @cindex @key{SPC} in minibuffer @code{exit-minibuffer} @@ -213,27 +215,9 @@ following bindings: @cindex @key{TAB} in minibuffer @code{exit-minibuffer} -@item @key{RET} -@code{exit-minibuffer} - -@item @kbd{C-g} -@code{abort-recursive-edit} - @item @kbd{?} @cindex @kbd{?} in minibuffer @code{self-insert-and-exit} - -@item @kbd{M-n} -@code{next-history-element} - -@item @kbd{M-p} -@code{previous-history-element} - -@item @kbd{M-r} -@code{next-matching-history-element} - -@item @kbd{M-s} -@code{previous-matching-history-element} @end table @end defvar @@ -805,6 +789,11 @@ can be completed because the next character is not uniquely determined. This section describes the higher-level convenient functions for reading certain sorts of names with completion. + In most cases, you should not call these functions in the middle of a +Lisp function. When possible, do all minibuffer input as part of +reading the arguments for a command, in the @code{interactive} spec. +@xref{Defining Commands}. + @defun read-buffer prompt &optional default existing This function reads the name of a buffer and returns it as a string. The argument @var{default} is the default name to use, the value to @@ -1000,7 +989,8 @@ This variable is used by @code{read-file-name}. Its value controls whether @code{read-file-name} starts by placing the name of the default directory in the minibuffer, plus the initial file name if any. If the value of this variable is @code{nil}, then @code{read-file-name} does -not place any initial input in the minibuffer. In that case, the +not place any initial input in the minibuffer (unless you specify +initial input with the @var{initial} argument). In that case, the default directory is still used for completion of relative file names, but is not displayed. @@ -1085,7 +1075,7 @@ match for some possibility; @code{nil} otherwise. @end itemize It would be consistent and clean for completion functions to allow -lambda expressions (lists tha are functions) as well as function +lambda expressions (lists that are functions) as well as function symbols as @var{collection}, but this is impossible. Lists as completion tables are already assigned another meaning---as alists. It would be unreliable to fail to handle an alist normally because it is @@ -1357,6 +1347,16 @@ This command replaces the minibuffer contents with the value of the next expression). @end deffn +@defun minibuffer-prompt +This function returns the prompt string of the currently active +minibuffer. If no minibuffer is active, it returns @code{nil}. +@end defun + +@defun minibuffer-prompt-width +This function returns the display width of the prompt string of the +currently active minibuffer. If no minibuffer is active, it returns 0. +@end defun + @defvar minibuffer-setup-hook This is a normal hook that is run whenever the minibuffer is entered. @xref{Hooks}. @@ -1415,16 +1415,6 @@ minibuffer, a nonnegative integer. If no minibuffers are active, it returns zero. @end defun -@defun minibuffer-prompt -This function returns the prompt string of the currently active -minibuffer. If no minibuffer is active, it returns @code{nil}. -@end defun - -@defun minibuffer-prompt-width -This function returns the display width of the prompt string of the -currently active minibuffer. If no minibuffer is active, it returns 0. -@end defun - @defopt enable-recursive-minibuffers If this variable is non-@code{nil}, you can invoke commands (such as @code{find-file}) that use minibuffers even while in the minibuffer @@ -1442,5 +1432,5 @@ window is selected. If a command name has a property @code{enable-recursive-minibuffers} that is non-@code{nil}, then the command can use the minibuffer to read arguments even if it is invoked from the minibuffer. The minibuffer -command @code{next-matching-history-element} (normally bound to -@kbd{M-s} in the minibuffer) uses this feature. +command @code{next-matching-history-element} (normally @kbd{M-s} in the +minibuffer) uses this feature. diff --git a/lispref/modes.texi b/lispref/modes.texi index 1927797080b..77cb11302a0 100644 --- a/lispref/modes.texi +++ b/lispref/modes.texi @@ -395,6 +395,8 @@ rest of @code{lisp-mode-variables}. @smallexample @group (make-local-variable 'paragraph-start) + ;; @r{Having @samp{^} is not clean, but @code{page-delimiter}} + ;; @r{has them too, and removing those is a pain.} (setq paragraph-start (concat "^$\\|" page-delimiter)) @dots{} @end group @@ -486,25 +488,25 @@ state of Emacs.) @end deffn @deffn Command normal-mode &optional find-file - This function establishes the proper major mode and local variable +This function establishes the proper major mode and local variable bindings for the current buffer. First it calls @code{set-auto-mode}, then it runs @code{hack-local-variables} to parse, and bind or evaluate as appropriate, any local variables. - If the @var{find-file} argument to @code{normal-mode} is +If the @var{find-file} argument to @code{normal-mode} is non-@code{nil}, @code{normal-mode} assumes that the @code{find-file} function is calling it. In this case, it may process a local variables -list at the end of the file. The variable @code{enable-local-variables} -controls whether to do so. +list at the end of the file and in the @samp{-*-} line. The variable +@code{enable-local-variables} controls whether to do so. - If you run @code{normal-mode} interactively, the argument +If you run @code{normal-mode} interactively, the argument @var{find-file} is normally @code{nil}. In this case, @code{normal-mode} unconditionally processes any local variables list. @xref{File variables, , Local Variables in Files, emacs, The GNU Emacs Manual}, for the syntax of the local variables section of a file. @cindex file mode specification error - @code{normal-mode} uses @code{condition-case} around the call to the +@code{normal-mode} uses @code{condition-case} around the call to the major mode function, so errors are caught and reported as a @samp{File mode specification error}, followed by the original error message. @end deffn @@ -516,6 +518,15 @@ lists unconditionally; @code{nil} means ignore them; anything else means ask the user what to do for each file. The default value is @code{t}. @end defopt +@defvar ignored-local-variables +This variable holds a list of variables that should not be +set by a local variables list. Any value specified +for one of these variables is ignored. +@end defvar + +In addition to this list, any variable whose name has a non-@code{nil} +@code{risky-local-variable} property is also ignored. + @defopt enable-local-eval This variable controls processing of @samp{Eval:} in local variables lists in files being visited. A value of @code{t} means process them @@ -553,8 +564,8 @@ This function sets the major mode of @var{buffer} to the value of the current buffer's major mode (if that is suitable). The low-level primitives for creating buffers do not use this function, -but medium-level commands such as @code{switch-to-buffer} should use it -whenever they create buffers. +but medium-level commands such as @code{switch-to-buffer} and +@code{find-file-noselect} use it whenever they create buffers. @end defun @defvar initial-major-mode @@ -757,7 +768,7 @@ minor modes in effect. Often the biggest problem in implementing a minor mode is finding a way to insert the necessary hook into the rest of Emacs. Minor mode -keymaps make this easier in Emacs 19 than it used to be. +keymaps make this easier than it used to be. @menu * Minor Mode Conventions:: Tips for writing a minor mode. @@ -805,15 +816,15 @@ a positive integer, a symbol other than @code{nil} or @code{-}, or a list whose @sc{car} is such an integer or symbol; it should turn the mode off otherwise. -Here is an example taken from the definition of @code{overwrite-mode}. -It shows the use of @code{overwrite-mode} as a variable that enables or +Here is an example taken from the definition of @code{transient-mark-mode}. +It shows the use of @code{transient-mark-mode} as a variable that enables or disables the mode's behavior, and also shows the proper way to toggle, enable or disable the minor mode based on the raw prefix argument value. @smallexample @group -(setq overwrite-mode - (if (null arg) (not overwrite-mode) +(setq transient-mark-mode + (if (null arg) (not transient-mark-mode) (> (prefix-numeric-value arg) 0))) @end group @end smallexample @@ -847,10 +858,9 @@ check for an existing element, to avoid duplication. For example: @node Keymaps and Minor Modes @subsection Keymaps and Minor Modes -As of Emacs version 19, each minor mode can have its own keymap, which is -active when the mode is enabled. @xref{Active Keymaps}. To set up a -keymap for a minor mode, add an element to the alist -@code{minor-mode-map-alist}. + Each minor mode can have its own keymap, which is active when the mode +is enabled. To set up a keymap for a minor mode, add an element to the +alist @code{minor-mode-map-alist}. @xref{Active Keymaps}. @cindex @code{self-insert-command}, minor modes One use of minor mode keymaps is to modify the behavior of certain @@ -861,34 +871,6 @@ special cases (designed for abbrevs and Auto Fill mode). (Do not try substituting your own definition of @code{self-insert-command} for the standard one. The editor command loop handles this function specially.) -@defvar minor-mode-map-alist -This variable is an alist of elements that look like this: - -@example -(@var{variable} . @var{keymap}) -@end example - -@noindent -where @var{variable} is the variable that indicates whether the minor -mode is enabled, and @var{keymap} is the keymap. The keymap -@var{keymap} is active whenever @var{variable} has a non-@code{nil} -value. - -Note that elements of @code{minor-mode-map-alist} do not have the same -structure as elements of @code{minor-mode-alist}. The map must be the -@sc{cdr} of the element; a list with the map as the second element will -not do. - -What's more, the keymap itself must appear in the @sc{cdr}. It does not -work to store a variable in the @sc{cdr} and make the map the value of -that variable. - -When more than one minor mode keymap is active, their order of priority -is the order of @code{minor-mode-map-alist}. But you should design -minor modes so that they don't interfere with each other. If you do -this properly, the order will not matter. -@end defvar - @node Mode Line Format @section Mode Line Format @cindex mode line @@ -906,8 +888,8 @@ minor modes. @code{mode-line-format} is a buffer-local variable that holds a template used to display the mode line of the current buffer. All -windows for the same buffer use the same @code{mode-line-format} and the -mode lines will appear the same (except for scrolling percentages and +windows for the same buffer use the same @code{mode-line-format} and +their mode lines appear the same (except for scrolling percentages and line numbers). The mode line of a window is normally updated whenever a different @@ -940,7 +922,7 @@ strings, symbols, and numbers kept in the buffer-local variable @code{mode-line-format}. The data structure is called a @dfn{mode line construct}, and it is built in recursive fashion out of simpler mode line constructs. The same data structure is used for constructing -frame titles (pxref{Frame Titles}). +frame titles (@pxref{Frame Titles}). @defvar mode-line-format The value of this variable is a mode line construct with overall @@ -967,7 +949,7 @@ value is a list, each element may be a list, a symbol, or a string. @cindex percent symbol in mode line @item @var{string} A string as a mode line construct is displayed verbatim in the mode line -except for @dfn{@code{%}-constructs}. Decimal digits after the @code{%} +except for @dfn{@code{%}-constructs}. Decimal digits after the @samp{%} specify the field width for space filling on the right (i.e., the data is left justified). @xref{%-Constructs}. @@ -1010,8 +992,8 @@ the top of the window is to use a list like this: @code{(-3 "%p")}. use the same variables that appear in the default value (@pxref{Mode Line Variables}), rather than duplicating their contents or displaying the information in another fashion. This way, customizations made by -the user, by libraries (such as @code{display-time}) and by major modes -via changes to those variables remain effective. +the user or by Lisp programs (such as @code{display-time} and major +modes) via changes to those variables remain effective. @cindex Shell mode @code{mode-line-format} Here is an example of a @code{mode-line-format} that might be @@ -1037,7 +1019,7 @@ directory. "%n" ")%]----" @group - (line-number-mode "L%l--") + '(line-number-mode "L%l--") '(-3 . "%p") "-%-")) @end group @@ -1056,19 +1038,22 @@ other variables could have the same effects on the mode line if This variable holds the value of the mode-line construct that displays whether the current buffer is modified. -The default value of @code{mode-line-modified} is -@code{("--%1*%1*-")}. This means that the mode line displays -@samp{--**-} if the buffer is modified, @samp{-----} if the buffer is -not modified, and @samp{--%%-} if the buffer is read only. +The default value of @code{mode-line-modified} is @code{("--%1*%1+-")}. +This means that the mode line displays @samp{--**-} if the buffer is +modified, @samp{-----} if the buffer is not modified, @samp{--%%-} if +the buffer is read only, and @samp{--%*--} if the buffer is read only +and modified. Changing this variable does not force an update of the mode line. @end defvar @defvar mode-line-buffer-identification This variable identifies the buffer being displayed in the window. Its -default value is @code{("Emacs: %17b")}, which means that it displays -@samp{Emacs:} followed by seventeen characters of the buffer name. You -may want to change this in modes such as Rmail that do not behave like a +default value is @code{("%F: %17b")}, 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. @end defvar @@ -1111,18 +1096,16 @@ The default value of @code{minor-mode-alist} is: @example @group minor-mode-alist -@result{} ((abbrev-mode " Abbrev") - (overwrite-mode " Ovwrt") +@result{} ((vc-mode vc-mode) + (abbrev-mode " Abbrev") + (overwrite-mode overwrite-mode) (auto-fill-function " Fill") - (defining-kbd-macro " Def")) + (defining-kbd-macro " Def") + (isearch-mode isearch-mode)) @end group @end example -@noindent -(In earlier Emacs versions, @code{auto-fill-function} was called -@code{auto-fill-hook}.) - - @code{minor-mode-alist} is not buffer-local. The variables mentioned +@code{minor-mode-alist} is not buffer-local. The variables mentioned in the alist should be buffer-local if the minor mode can be enabled separately in each buffer. @end defvar @@ -1155,10 +1138,11 @@ The default value of @code{default-mode-line-format} is: mode-name @end group @group + mode-line-process minor-mode-alist "%n" - mode-line-process ")%]----" + (line-number-mode "L%l--") (-3 . "%p") "-%-") @end group @@ -1293,15 +1277,15 @@ the functions are called with arguments, or their values are meaningful. The name shows you that the hook is abnormal and that you should look at its documentation string to see how to use it properly. - Most major modes run hooks as the last step of initialization. This -makes it easy for a user to customize the behavior of the mode, by -overriding the local variable assignments already made by the mode. But -hooks are used in other contexts too. For example, the hook -@code{suspend-hook} runs just before Emacs suspends itself -(@pxref{Suspending Emacs}). + Major mode functions are supposed to run a hook called the @dfn{mode +hook} as the last step of initialization. This makes it easy for a user +to customize the behavior of the mode, by overriding the local variable +assignments already made by the mode. But hooks are used in other +contexts too. For example, the hook @code{suspend-hook} runs just +before Emacs suspends itself (@pxref{Suspending Emacs}). - Here's an expression you can put in your @file{.emacs} file to turn on -Auto Fill mode when in Lisp Interaction mode: + Here's an expression that uses a mode hook to turn on Auto Fill mode +when in Lisp Interaction mode: @example (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill) @@ -1330,39 +1314,9 @@ expression. @end group @end example - Finally, here is an example of how to use the Text mode hook to -provide a customized mode line for buffers in Text mode, displaying the -default directory in addition to the standard components of the -mode line. (This may cause the mode line to run out of space if you -have very long file names or display the time and load.) - -@example -@group -(add-hook 'text-mode-hook - (function (lambda () - (setq mode-line-format -@end group - '(mode-line-modified - "Emacs: %14b" - " " - default-directory - " " - global-mode-string - "%[(" - mode-name - minor-mode-alist -@group - "%n" - mode-line-process - ") %]---" - (-3 . "%p") - "-%-"))))) -@end group -@end example - At the appropriate time, Emacs uses the @code{run-hooks} function to -run particular hooks. This function calls the hook functions you have -added with @code{add-hooks}. +run particular hooks. This function calls the hook functions that have +been added with @code{add-hook}. @defun run-hooks &rest hookvar This function takes one or more hook variable names as arguments, and @@ -1376,7 +1330,7 @@ lambda expression or a symbol with a function definition), it is called. If it is a list, the elements are called, in order. The hook functions are called with no arguments. -For example, here's how @code{emacs-lisp-hooks} runs its mode hook: +For example, here's how @code{emacs-lisp-mode} runs its mode hook: @example (run-hooks 'emacs-lisp-mode-hook) diff --git a/lispref/numbers.texi b/lispref/numbers.texi index 0c331545e1d..e7db42f727b 100644 --- a/lispref/numbers.texi +++ b/lispref/numbers.texi @@ -249,9 +249,10 @@ Here's a function to do this: @example (defvar fuzz-factor 1.0e-6) (defun approx-equal (x y) - (< (/ (abs (- x y)) - (max (abs x) (abs y))) - fuzz-factor)) + (or (and (= x 0) (= y 0)) + (< (/ (abs (- x y)) + (max (abs x) (abs y))) + fuzz-factor))) @end example @cindex CL note---integers vrs @code{eq} @@ -356,7 +357,9 @@ This returns @var{number}, converted to an integer by rounding upward @defun round number This returns @var{number}, converted to an integer by rounding towards the -nearest integer. +nearest integer. Rounding a value equidistant between two integers +may choose the integer closer to zero, or it may prefer an even integer, +depending on your machine. @end defun @node Arithmetic Operations @@ -386,8 +389,8 @@ For example, @result{} 5 @end example -This function is not analogous to the C operator @code{++}---it does -not increment a variable. It just computes a sum. Thus, +This function is not analogous to the C operator @code{++}---it does not +increment a variable. It just computes a sum. Thus, if we continue, @example foo @@ -413,7 +416,7 @@ This returns the absolute value of @var{number}. @defun + &rest numbers-or-markers This function adds its arguments together. When given no arguments, -@code{+} returns 0. It does not check for overflow. +@code{+} returns 0. @example (+) @@ -430,8 +433,7 @@ The @code{-} function serves two purposes: negation and subtraction. When @code{-} has a single argument, the value is the negative of the argument. When there are multiple arguments, @code{-} subtracts each of the @var{other-numbers-or-markers} from @var{number-or-marker}, -cumulatively. If there are no arguments, the result is 0. This -function does not check for overflow. +cumulatively. If there are no arguments, the result is 0. @example (- 10 1 2 3 4) @@ -445,8 +447,7 @@ function does not check for overflow. @defun * &rest numbers-or-markers This function multiplies its arguments together, and returns the -product. When given no arguments, @code{*} returns 1. It does -not check for overflow. +product. When given no arguments, @code{*} returns 1. @example (*) @@ -562,8 +563,9 @@ For any two numbers @var{dividend} and @var{divisor}, @end example @noindent -always equals @var{dividend}, subject to rounding error if -either argument is floating point. +always equals @var{dividend}, subject to rounding error if either +argument is floating point. For @code{floor}, see @ref{Numeric +Conversions}. @end defun @node Rounding Operations @@ -640,36 +642,7 @@ As the examples illustrate, shifting the pattern of bits one place to the left produces a number that is twice the value of the previous number. -The function @code{lsh}, like all Emacs Lisp arithmetic functions, does -not check for overflow, so shifting left can discard significant bits -and change the sign of the number. For example, left shifting -134,217,727 produces @minus{}2 on a 28-bit machine: - -@example -(lsh 134217727 1) ; @r{left shift} - @result{} -2 -@end example - -In binary, in the 28-bit implementation, the argument looks like this: - -@example -@group -;; @r{Decimal 134.217,727} -0111 1111 1111 1111 1111 1111 1111 -@end group -@end example - -@noindent -which becomes the following when left shifted: - -@example -@group -;; @r{Decimal @minus{}2} -1111 1111 1111 1111 1111 1111 1110 -@end group -@end example - -Shifting the pattern of bits two places to the left produces results +Shifting a pattern of bits two places to the left produces results like this (with 8-bit binary numbers): @example @@ -681,8 +654,7 @@ like this (with 8-bit binary numbers): @end group @end example -On the other hand, shifting the pattern of bits one place to the right -looks like this: +On the other hand, shifting one place to the right looks like this: @example @group @@ -701,8 +673,37 @@ looks like this: @end example @noindent -As the example illustrates, shifting the pattern of bits one place to -the right divides the value of the binary number by two, rounding downward. +As the example illustrates, shifting one place to the right divides the +value of a positive integer by two, rounding downward. + +The function @code{lsh}, like all Emacs Lisp arithmetic functions, does +not check for overflow, so shifting left can discard significant bits +and change the sign of the number. For example, left shifting +134,217,727 produces @minus{}2 on a 28-bit machine: + +@example +(lsh 134217727 1) ; @r{left shift} + @result{} -2 +@end example + +In binary, in the 28-bit implementation, the argument looks like this: + +@example +@group +;; @r{Decimal 134.217,727} +0111 1111 1111 1111 1111 1111 1111 +@end group +@end example + +@noindent +which becomes the following when left shifted: + +@example +@group +;; @r{Decimal @minus{}2} +1111 1111 1111 1111 1111 1111 1110 +@end group +@end example @end defun @defun ash integer1 count @@ -713,8 +714,8 @@ is negative. @code{ash} gives the same results as @code{lsh} except when @var{integer1} and @var{count} are both negative. In that case, -@code{ash} puts a one in the leftmost position, while @code{lsh} puts -a zero in the leftmost position. +@code{ash} puts ones in the empty bit positions on the left, while +@code{lsh} puts zeros in those bit positions. Thus, with @code{ash}, shifting the pattern of bits one place to the right looks like this: @@ -1008,18 +1009,8 @@ Emacs's process @sc{id} number. This function returns a pseudo-random integer. Repeated calls return a series of pseudo-random integers. -If @var{limit} is @code{nil}, then the value may in principle be any -integer. However, on machines where integers have more than 32 bits, -the possible values may be limited to the interval -@tex -$[0,2^{32})$. -@end tex -@ifinfo -[0,2**32). -@end ifinfo - If @var{limit} is a positive integer, the value is chosen to be -nonnegative and less than @var{limit} (only in Emacs 19). +nonnegative and less than @var{limit}. If @var{limit} is @code{t}, it means to choose a new seed based on the current time of day and on Emacs's process @sc{id} number. diff --git a/lispref/objects.texi b/lispref/objects.texi index fc06466112c..4952f07514e 100644 --- a/lispref/objects.texi +++ b/lispref/objects.texi @@ -115,6 +115,11 @@ the end of line. The Lisp reader discards comments; they do not become part of the Lisp objects which represent the program within the Lisp system. + The @samp{#@@@var{count}} construct, which skips the next @var{count} +characters, is useful for program-generated comments containing binary +data. The Emacs Lisp byte compiler uses this in its output files +(@pxref{Byte Compilation}). It isn't meant for source files, however. + @xref{Comment Tips}, for conventions for formatting comments. @node Programming Types @@ -305,17 +310,30 @@ equivalent to @samp{?\^I} and to @samp{?\^i}: characters that exist in @sc{ASCII}, but for keyboard input purposes, you can turn any character into a control character with @samp{C-}. The character codes for these non-@sc{ASCII} control characters include the -2**22 bit as well as the code for the corresponding non-control +@iftex +$2^{26}$ +@end iftex +@ifinfo +2**26 +@end ifinfo +bit as well as the code for the corresponding non-control character. Ordinary terminals have no way of generating non-@sc{ASCII} control characters, but you can generate them straightforwardly using an X terminal. - You can think of the @key{DEL} character as @kbd{Control-?}: + For historical reasons, Emacs treats the @key{DEL} character as +the control equivalent of @kbd{?}: @example ?\^? @result{} 127 ?\C-? @result{} 127 @end example +@noindent +As a result, it is currently not possible to represent the character +@kbd{Control-?}, which is a meaningful input character under X. It is +not easy to change this as various Lisp files refer to @key{DEL} in this +way. + For representing control characters to be found in files or strings, we recommend the @samp{^} syntax; for control characters in keyboard input, we prefer the @samp{C-} syntax. This does not affect the meaning @@ -324,11 +342,24 @@ of the program, but may guide the understanding of people who read it. @cindex meta characters A @dfn{meta character} is a character typed with the @key{META} modifier key. The integer that represents such a character has the -2**23 bit set (which on most machines makes it a negative number). We +@iftex +$2^{27}$ +@end iftex +@ifinfo +2**27 +@end ifinfo +bit set (which on most machines makes it a negative number). We use high bits for this and other modifiers to make possible a wide range of basic character codes. - In a string, the 2**7 bit indicates a meta character, so the meta + In a string, the +@iftex +$2^{7}$ +@end iftex +@ifinfo +2**7 +@end ifinfo +bit indicates a meta character, so the meta characters that can fit in a string have codes in the range from 128 to 255, and are the meta versions of the ordinary @sc{ASCII} characters. (In Emacs versions 18 and older, this convention was used for characters @@ -343,11 +374,17 @@ or as @samp{?\M-\101}. Likewise, you can write @kbd{C-M-b} as The case of an ordinary letter is indicated by its character code as part of @sc{ASCII}, but @sc{ASCII} has no way to represent whether a -control character is upper case or lower case. Emacs uses the 2**21 bit -to indicate that the shift key was used for typing a control character. -This distinction is possible only when you use X terminals or other -special terminals; ordinary terminals do not indicate the distinction to -the computer in any way. +control character is upper case or lower case. Emacs uses the +@iftex +$2^{25}$ +@end iftex +@ifinfo +2**25 +@end ifinfo +bit to indicate that the shift key was used for typing a control +character. This distinction is possible only when you use X terminals +or other special terminals; ordinary terminals do not indicate the +distinction to the computer in any way. @cindex hyper characters @cindex super characters @@ -355,8 +392,15 @@ the computer in any way. The X Window System defines three other modifier bits that can be set in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}. The syntaxes for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. Thus, -@samp{?\H-\M-\A-x} represents @kbd{Alt-Hyper-Meta-x}. Numerically, the -bit values are 2**18 for alt, 2**19 for super and 2**20 for hyper. +@samp{?\H-\M-\A-x} represents @kbd{Alt-Hyper-Meta-x}. +@iftex +Numerically, the +bit values are $2^{22}$ for alt, $2^{23}$ for super and $2^{24}$ for hyper. +@end iftex +@ifinfo +Numerically, the +bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper. +@end ifinfo @cindex @samp{?} in character constant @cindex question mark in character constant @@ -423,14 +467,13 @@ do such a thing. @cindex CL note---case of letters @quotation @b{Common Lisp note:} In Common Lisp, lower case letters are always -``folded'' to upper case, unless they are explicitly escaped. This is -in contrast to Emacs Lisp, in which upper case and lower case letters -are distinct. +``folded'' to upper case, unless they are explicitly escaped. In Emacs +Lisp, upper case and lower case letters are distinct. @end quotation Here are several examples of symbol names. Note that the @samp{+} in the fifth example is escaped to prevent it from being read as a number. -This is not necessary in the last example because the rest of the name +This is not necessary in the sixth example because the rest of the name makes it invalid as a number. @example @@ -762,7 +805,14 @@ string containing just a single double-quote character. characters.) If you use the @samp{\M-} syntax to indicate a meta character in a -string constant, this sets the 2**7 bit of the character in the string. +string constant, this sets the +@iftex +$2^{7}$ +@end iftex +@ifinfo +2**7 +@end ifinfo +bit of the character in the string. This is not the same representation that the meta modifier has in a character on its own (not inside a string). @xref{Character Type}. @@ -917,8 +967,9 @@ the evaluator handles this data type specially when it appears as a function to be called. @xref{Byte Compilation}, for information about the byte compiler. -The printed representation for a byte-code function object is like that -for a vector, with an additional @samp{#} before the opening @samp{[}. +The printed representation and read syntax for a byte-code function +object is like that for a vector, with an additional @samp{#} before the +opening @samp{[}. @node Autoload Type @subsection Autoload Type @@ -998,6 +1049,12 @@ a local keymap (@pxref{Keymaps}); and, @item a local variable binding list (@pxref{Buffer-Local Variables}). + +@item +a list of overlays (@pxref{Overlays}). + +@item +text properties for the text in the buffer (@pxref{Text Properties}). @end itemize @noindent @@ -1006,7 +1063,10 @@ override global bindings or values. These are used to customize the behavior of programs in different buffers, without actually changing the programs. - Buffers have no read syntax. They print in hash notation with the + A buffer may be @dfn{indirect}, which means it shares the text +of another buffer. @xref{Indirect Buffers}. + + Buffers have no read syntax. They print in hash notation, showing the buffer name. @example @@ -1187,7 +1247,7 @@ and modify syntax tables. A @dfn{display table} specifies how to display each character code. Each buffer and each window can have its own display table. A display -table is actually a vector of length 261. @xref{Display Tables}. +table is actually a vector of length 262. @xref{Display Tables}. @node Overlay Type @subsection Overlay Type @@ -1196,12 +1256,12 @@ table is actually a vector of length 261. @xref{Display Tables}. appearance of a part of a buffer. It contains markers delimiting a range of the buffer, plus a property list (a list whose elements are alternating property names and values). Overlays are used to present -parts of the buffer temporarily in a different display style. - - @xref{Overlays}, for how to create and use overlays. They have no -read syntax, and print in hash notation, giving the buffer name and +parts of the buffer temporarily in a different display style. They have +no read syntax, and print in hash notation, giving the buffer name and range of positions. + @xref{Overlays}, for how to create and use overlays. + @node Type Predicates @section Type Predicates @cindex predicates @@ -1521,6 +1581,9 @@ use @code{string=} (@pxref{Text Comparison}). @result{} nil @end group @end example + +Two distinct buffers are never @code{equal}, even if their contents +are the same. @end defun The test for equality is implemented recursively, and circular lists may diff --git a/lispref/os.texi b/lispref/os.texi index e39c6ca752c..a21107bf4fe 100644 --- a/lispref/os.texi +++ b/lispref/os.texi @@ -60,6 +60,10 @@ using a window system. This library's name is @file{term/@var{windowsystem}-win.el}. @item +It processes the initial options. (Some of them are handled +even earlier than this.) + +@item It initializes the X window frame and faces, if appropriate. @item @@ -101,7 +105,7 @@ It displays the initial echo area message, unless you have suppressed that with @code{inhibit-startup-echo-area-message}. @item -It processes any remaining command line arguments. +It processes the action arguments from the command line. @item It runs @code{term-setup-hook}. @@ -179,6 +183,11 @@ Emacs does not subsequently load the @file{default.el} file. loads this @emph{before} the user's init file. You can inhibit the loading of this file with the option @samp{-no-site-file}. +@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"}. +@end defvar + If there is a great deal of code in your @file{.emacs} file, you should move it into another file named @file{@var{something}.el}, byte-compile it (@pxref{Byte Compilation}), and make your @file{.emacs} @@ -543,9 +552,8 @@ through various functions. These variables include the name of the system, the user's @sc{uid}, and so on. @defvar system-type -The value of this variable is a symbol indicating the type of -operating system Emacs is operating on. Here is a table of the symbols -for the operating systems that Emacs can run on up to version 19.1. +The value of this variable is a symbol indicating the type of operating +system Emacs is operating on. Here is a table of the possible values: @table @code @item aix-v3 @@ -554,14 +562,26 @@ AIX. @item berkeley-unix Berkeley BSD. +@item dgux +Data General DGUX operating system. + +@item gnu +A GNU system using the GNU HURD and Mach. + @item hpux -Hewlett-Packard operating system. +Hewlett-Packard HPUX operating system. @item irix Silicon Graphics Irix system. @item linux -The free Linux operating system. +A GNU system using the Linux kernel. + +@item ms-dos +Microsoft MS-DOS ``operating system.'' + +@item next-mach +NeXT Mach-based system. @item rtu Masscomp RTU, UCB universe. @@ -575,6 +595,9 @@ AT&T System V. @item vax-vms VAX VMS. +@item windows-nt +Microsoft windows NT. + @item xenix SCO Xenix 386. @end table @@ -650,13 +673,6 @@ function works by modifying @code{process-environment}; binding that variable with @code{let} is also reasonable practice. @end deffn -@defvar path-separator -This variable holds a string which says which character separates -directories in a search path (as found in an environment variable). Its -value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS -and Windows NT. -@end defvar - @defvar process-environment This variable is a list of strings, each describing one environment variable. The functions @code{getenv} and @code{setenv} work by means @@ -677,6 +693,13 @@ process-environment @end smallexample @end defvar +@defvar path-separator +This variable holds a string which says which character separates +directories in a search path (as found in an environment variable). Its +value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS +and Windows NT. +@end defvar + @defvar invocation-name This variable holds the program name under which Emacs was invoked. The value is a string, and does not include a directory name. @@ -785,18 +808,6 @@ you to ``fake out'' Emacs by telling the functions what to return. The variables are also useful for constructing frame titles (@pxref{Frame Titles}). -@defvar user-real-login-name -This variable holds the same value that the function -@code{user-real-login-name} returns. The variable lets you alter the value; -also, you can use variables for constructing frame titles. -@end defvar - -@defvar user-full-name -This variable holds the same value that the function -@code{user-full-name} returns. The variable lets you alter the value; -also, you can use variables for constructing frame titles. -@end defvar - @defun user-real-uid This function returns the real @sc{uid} of the user. @@ -822,16 +833,16 @@ zone. This function returns the current time and date as a humanly-readable string. The format of the string is unvarying; the number of characters used for each part is always the same, so you can reliably use -@code{substring} to extract pieces of it. However, it would be wise to -count the characters from the beginning of the string rather than from -the end, as additional information may be added at the end. +@code{substring} to extract pieces of it. It is wise to count the +characters from the beginning of the string rather than from the end, as +additional information may be added at the end. @c Emacs 19 feature The argument @var{time-value}, if given, specifies a time to format -instead of the current time. The argument should be a cons cell -containing two integers, or a list whose first two elements are -integers. Thus, you can use times obtained from @code{current-time} -(see below) and from @code{file-attributes} (@pxref{File Attributes}). +instead of the current time. The argument should be a list whose first +two elements are integers. Thus, you can use times obtained from +@code{current-time} (see below) and from @code{file-attributes} +(@pxref{File Attributes}). @example @group @@ -912,8 +923,8 @@ This stands for the full name of the month. @item %c This is a synonym for @samp{%x %X}. @item %C -This has a locale-specific meaning. In the C locale, it is equivalent -to @samp{%A, %B %e, %Y}. +This has a locale-specific meaning. In the default locale (named C), it +is equivalent to @samp{%A, %B %e, %Y}. @item %d This stands for the day of month, zero-padded. @item %D @@ -959,11 +970,11 @@ This stands for the numeric day of week (0-6). Sunday is day 0. This stands for the week of the year (01-52), assuming that weeks start on Monday. @item %x -This has a locale-specific meaning. In the C locale, it is equivalent -to @samp{%D}. +This has a locale-specific meaning. In the default locale (named C), it +is equivalent to @samp{%D}. @item %X -This has a locale-specific meaning. In the C locale, it is equivalent -to @samp{%T}. +This has a locale-specific meaning. In the default locale (named C), it +is equivalent to @samp{%T}. @item %y This stands for the year without century (00-99). @item %Y @@ -974,8 +985,8 @@ This stands for the time zone abbreviation. @end defun @defun decode-time time -This function converts a time value into calendrical form. The return -value is a list of nine elements, as follows: +This function converts a time value into calendrical information. The +return value is a list of nine elements, as follows: @example (@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone}) @@ -1002,7 +1013,8 @@ Sunday. @item dst @code{t} if daylight savings time is effect, otherwise @code{nil}. @item zone -An integer indicating the number of seconds east of Greenwich. +An integer indicating the time zone, as the number of seconds east of +Greenwich. @end table Note that Common Lisp has different meanings for @var{dow} and @@ -1011,10 +1023,8 @@ Note that Common Lisp has different meanings for @var{dow} and @defun encode-time seconds minutes hour day month year &optional zone This function is the inverse of @code{decode-time}. It converts seven -items of calendrical data into a time value. - -For the meanings of the arguments, see the table above under -@code{decode-time}. +items of calendrical data into a time value. For the meanings of the +arguments, see the table above under @code{decode-time}. Year numbers less than 100 are treated just like other year numbers. If you them to stand for years above 1900, you must alter them yourself @@ -1028,7 +1038,7 @@ any further alteration for daylight savings time. @end defun @node Timers -@section Timers +@section Timers for Delayed Execution You can set up a timer to call a function at a specified future time. @@ -1100,7 +1110,9 @@ functions. @defun set-input-mode interrupt flow meta quit-char This function sets the mode for reading keyboard input. If @var{interrupt} is non-null, then Emacs uses input interrupts. If it is -@code{nil}, then it uses @sc{cbreak} mode. +@code{nil}, then it uses @sc{cbreak} mode. When Emacs communicates +directly with X, it ignores this argument and uses interrupts if that is +the way it knows how to communicate. If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal. This has no effect except @@ -1142,7 +1154,7 @@ is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal. This value has no effect unless @var{interrupt} is non-@code{nil}. @item meta -is non-@code{t} if Emacs treats the eighth bit of input characters as +is @code{t} if Emacs treats the eighth bit of input characters as the meta bit; @code{nil} means Emacs clears the eighth bit of every input character; any other value means Emacs uses all eight bits as the basic character code. @@ -1151,14 +1163,6 @@ is the character Emacs currently uses for quitting, usually @kbd{C-g}. @end table @end defun -@defvar meta-flag -This variable used to control whether to treat the eight bit in keyboard -input characters as the @key{Meta} bit. @code{nil} meant no, and -anything else meant yes. This variable existed in Emacs versions 18 and -earlier but no longer exists in Emacs 19; use @code{set-input-mode} -instead. -@end defvar - @node Translating Input @subsection Translating Input Events @cindex translating input events @@ -1185,7 +1189,7 @@ The @key{META} key. Each time the user types a keyboard key, it is altered as if the modifier keys specified in the bit mask were held down. -When you use X windows, the program can ``press'' any of the modifier +When using X windows, the program can ``press'' any of the modifier keys in this way. Otherwise, only the @key{CTL} and @key{META} keys can be virtually pressed. @end defvar @@ -1513,8 +1517,10 @@ for flow control is not an official standard. Interestingly, on the model 33 teletype with a paper tape punch (which is very old), @kbd{C-s} and @kbd{C-q} were sent by the computer to turn the punch on and off! - GNU Emacs version 19 provides a convenient way of enabling flow -control if you want it: call the function @code{enable-flow-control}. + As X servers and other window systems replace character-only +terminals, this problem is gradually being cured. For the mean time, +Emacs provides a convenient way of enabling flow control if you want it: +call the function @code{enable-flow-control}. @defun enable-flow-control This function enables use of @kbd{C-s} and @kbd{C-q} for output flow @@ -1575,7 +1581,7 @@ calls @var{function} with no arguments. Any Lisp program output that would normally go to the echo area, either using @code{message} or using @code{prin1}, etc., with @code{t} -as the stream, goes instead to Emacs's standard output descriptor when +as the stream, goes instead to Emacs's standard error descriptor when in batch mode. Thus, Emacs behaves much like a noninteractive application program. (The echo area output that Emacs itself normally generates, such as command echoing, is suppressed entirely.) diff --git a/lispref/positions.texi b/lispref/positions.texi index 6691a63c827..1032c85453b 100644 --- a/lispref/positions.texi +++ b/lispref/positions.texi @@ -37,9 +37,9 @@ to allow editing and insertion at different places. Like other positions, point designates a place between two characters (or before the first character, or after the last character), rather -than a particular character. Many terminals display the cursor over the -character that immediately follows point; on such terminals, point is -actually before the character on which the cursor sits. +than a particular character. Usually terminals display the cursor over +the character that immediately follows point; point is actually before +the character on which the cursor sits. @cindex point with narrowing The value of point is a number between 1 and the buffer size plus 1. @@ -119,8 +119,6 @@ or relative to the edges of the selected window. @xref{Point}. * Buffer End Motion:: Moving to the beginning or end of the buffer. * Text Lines:: Moving in terms of lines of text. * Screen Lines:: Moving in terms of lines as displayed. -* Vertical Motion:: Implementation of @code{next-line} and - @code{previous-line}. * List Motion:: Moving by parsing lists and sexps. * Skipping Characters:: Skipping characters belonging to a certain set. @end menu @@ -422,36 +420,6 @@ to use and more reliable (no dependence on goal column, etc.). @c ================ @end ignore -@defvar cache-long-line-scans -This variable determines whether Emacs should use caches to handle long -lines more quickly. This variable is buffer-local, in all buffers. - - Normally, the line-motion functions work by scanning the buffer for -newlines. Columnar operations (like @code{move-to-column} and -@code{compute-motion}) also work by scanning the buffer, summing -character widths as they go. This works well for ordinary text, but if -the buffer's lines are very long (say, more than 500 characters), these -motion functions will take longer to execute. Emacs may also take -longer to update the display. - - If @code{cache-long-line-scans} is non-@code{nil}, these motion -functions cache the results of their scans, and consult the cache to -avoid rescanning regions of the buffer until the text is modified. The -caches are most beneficial when they prevent the most searching---that -is, when the buffer contains long lines and large regions of characters -with the same, fixed screen width. - - When @code{cache-long-line-scans} is non-@code{nil}, processing short -lines will become slightly slower (because of the overhead of consulting -the cache), and the caches will use memory roughly proportional to the -number of newlines and characters whose screen width varies. - - The caches require no explicit maintenance; their accuracy is -maintained internally by the Emacs primitives. Enabling or disabling -the cache should not affect the behavior of any of the motion functions; -it should only affect their performance. -@end defvar - Also see the functions @code{bolp} and @code{eolp} in @ref{Near Point}. These functions do not move point, but test whether it is already at the beginning or end of a line. @@ -532,7 +500,8 @@ the form @code{(@var{hpos} . @var{vpos})}. The argument @var{width} is the number of columns available to display text; this affects handling of continuation lines. Use the value -returned by @code{window-width} for the window of your choice. +returned by @code{window-width} for the window of your choice; +normally, use @code{(window-width @var{window})}. The argument @var{offsets} is either @code{nil} or a cons cell of the form @code{(@var{hscroll} . @var{tab-offset})}. Here @var{hscroll} is @@ -585,49 +554,6 @@ When you use @code{compute-motion} for the minibuffer, you need to use beginning of the first screen line. @xref{Minibuffer Misc}. @end defun -@node Vertical Motion -@comment node-name, next, previous, up -@subsection The User-Level Vertical Motion Commands -@cindex goal column -@cindex vertical text line motion -@findex next-line -@findex previous-line - - A goal column is useful if you want to edit text such as a table in -which you want to move point to a certain column on each line. The goal -column affects the vertical text line motion commands, @code{next-line} -and @code{previous-line}. @xref{Basic,, Basic Editing Commands, emacs, -The GNU Emacs Manual}. - -@defopt goal-column -This variable holds an explicitly specified goal column for vertical -line motion commands. If it is an integer, it specifies a column, and -these commands try to move to that column on each line. If it is -@code{nil}, then the commands set their own goal columns. Any other -value is invalid. -@end defopt - -@defvar temporary-goal-column -This variable holds the temporary goal column during a sequence of -consecutive vertical line motion commands. It is overridden by -@code{goal-column} if that is non-@code{nil}. It is set each time a -vertical motion command is invoked, unless the previous command was also -a vertical motion command. -@end defvar - -@defopt track-eol -This variable controls how the vertical line motion commands operate -when starting at the end of a line. If @code{track-eol} is -non-@code{nil}, then vertical motion starting at the end of a line will -keep to the ends of lines (instead of keeping to a particular column). -This means moving to the end of each line moved onto. The value of -@code{track-eol} has no effect if point is not at the end of a line when -the first vertical motion command is given. - -@code{track-eol} has its effect by telling line motion commands to set -@code{temporary-goal-column} to 9999 instead of to the current column. -@end defopt - @node List Motion @comment node-name, next, previous, up @subsection Moving over Balanced Expressions diff --git a/lispref/processes.texi b/lispref/processes.texi index a089ba0994d..a5d83c868cb 100644 --- a/lispref/processes.texi +++ b/lispref/processes.texi @@ -46,7 +46,7 @@ This function returns @code{t} if @var{object} is a process, * Output from Processes:: Collecting output from an asynchronous subprocess. * Sentinels:: Sentinels run when process run-status changes. * Transaction Queues:: Transaction-based communication with subprocesses. -* TCP:: Opening network connections. +* Network:: Opening network connections. @end menu @node Subprocess Creation @@ -313,7 +313,7 @@ inputinput@point{} a synchronous subprocess are text or binary. Text data requires translation between the end-of-line convention used within Emacs (a single newline character) and the convention used outside Emacs -(the two-character sequence, CRLF). +(the two-character sequence, @sc{crlf}). The variable @code{binary-process-input} applies to input sent to the subprocess, and @code{binary-process-output} applies to output received @@ -321,12 +321,12 @@ from it. A non-@code{nil} value means the data is non-text; @code{nil} means the data is text, and calls for conversion. @defvar binary-process-input -If this variable is @code{nil}, convert newlines to CRLF sequences in +If this variable is @code{nil}, convert newlines to @sc{crlf} sequences in the input to a synchronous subprocess. @end defvar @defvar binary-process-output -If this variable is @code{nil}, convert CRLF sequences to newlines in +If this variable is @code{nil}, convert @sc{crlf} sequences to newlines in the output from a synchronous subprocess. @end defvar @@ -396,9 +396,8 @@ command. @cindex pipes @cindex @sc{pty}s This variable controls the type of device used to communicate with -asynchronous subprocesses. If it is @code{nil}, then pipes are used. -If it is @code{t}, then @sc{pty}s are used (or pipes if @sc{pty}s are -not supported). +asynchronous subprocesses. If it is non-@code{nil}, then @sc{pty}s are +used, when available. Otherwise, pipes are used. @sc{pty}s are usually preferable for processes visible to the user, as in Shell mode, because they allow job control (@kbd{C-c}, @kbd{C-z}, @@ -945,7 +944,7 @@ Now Emacs does this automatically; filter functions never need to do it explicitly. @xref{Match Data}. A filter function that writes the output into the buffer of the -process should check whether the process is still alive. If it tries to +process should check whether the buffer is still alive. If it tries to insert into a dead buffer, it will get an error. If the buffer is dead, @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}. @@ -1043,6 +1042,13 @@ thus specified are added together, and @code{accept-process-output} returns after that much time whether or not there has been any subprocess output. +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}. + 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 nonzero @var{millisec}. @@ -1095,15 +1101,10 @@ would be unpredictable. If you want to permit quitting inside a sentinel, bind @code{inhibit-quit} to @code{nil}. @xref{Quitting}. A sentinel that writes the output into the buffer of the process -should check whether the process is still alive. If it tries to insert +should check whether the buffer is still alive. If it tries to insert into a dead buffer, it will get an error. If the buffer is dead, @code{(buffer-name (process-buffer @var{process}))} returns @code{nil}. - In earlier Emacs versions, every sentinel that did regexp searching or -matching had to explicitly save and restore the match data. Now Emacs -does this automatically; sentinels never need to do it explicitly. -@xref{Match Data}. - If an error happens during execution of a sentinel, it is caught automatically, so that it doesn't stop the execution of whatever programs was running when the sentinel was started. However, if @@ -1111,6 +1112,11 @@ programs was running when the sentinel was started. However, if off. This makes it possible to use the Lisp debugger to debug the sentinel. @xref{Debugger}. + In earlier Emacs versions, every sentinel that did regexp searching or +matching had to explicitly save and restore the match data. Now Emacs +does this automatically; sentinels never need to do it explicitly. +@xref{Match Data}. + @defun set-process-sentinel process sentinel This function associates @var{sentinel} with @var{process}. If @var{sentinel} is @code{nil}, then the process will have no sentinel. @@ -1186,12 +1192,13 @@ to complete, and then terminate the connection or child process. Transaction queues are implemented by means of a filter function. @xref{Filter Functions}. -@node TCP -@section TCP +@node Network +@section Network Connections +@cindex network connection @cindex TCP - Emacs Lisp programs can open TCP connections to other processes on the -same machine or other machines. A network connection is handled by Lisp + Emacs Lisp programs can open TCP network connections to other processes on +the same machine or other machines. A network connection is handled by Lisp much like a subprocess, and is represented by a process object. However, the process you are communicating with is not a child of the Emacs process, so you can't kill it or send it signals. All you can do @@ -1201,7 +1208,9 @@ what to do about closure of the connection. You can distinguish process objects representing network connections from those representing subprocesses with the @code{process-status} -function. @xref{Process Information}. +function. It always returns either @code{open} or @code{closed} for a +network connection, and it never returns either of those values for a +real subprocess. @xref{Process Information}. @defun open-network-stream name buffer-or-name host service This function opens a TCP connection for a service to a host. It diff --git a/lispref/searching.texi b/lispref/searching.texi index 7919804d35c..29852a3624f 100644 --- a/lispref/searching.texi +++ b/lispref/searching.texi @@ -974,7 +974,8 @@ This function returns, as a string, the text matched in the last search or match operation. It returns the entire text if @var{count} is zero, or just the portion corresponding to the @var{count}th parenthetical subexpression, if @var{count} is positive. If @var{count} is out of -range, the value is @code{nil}. +range, or if that subexpression didn't match anything, the value is +@code{nil}. If the last such operation was done against a string with @code{string-match}, then you should pass the same string as the @@ -1083,10 +1084,14 @@ This function replaces the text in the buffer (or in @var{string}) that was matched by the last search. It replaces that text with @var{replacement}. -If @var{string} is @code{nil}, @code{replace-match} does the replacement -by editing the buffer; it leaves point at the end of the replacement -text, and returns @code{t}. If @var{string} is a string, it does the -replacement by constructing and returning a new string. +If you did the last search in a buffer, you should specify @code{nil} +for @var{string}. Then @code{replace-match} does the replacement by +editing the buffer; it leaves point at the end of the replacement text, +and returns @code{t}. + +If you did the search in a string, pass the same string as @var{string}. +Then @code{replace-match} does the replacement by constructing and +returning a new string. If @var{fixedcase} is non-@code{nil}, then the case of the replacement text is not changed; otherwise, the replacement text is converted to a @@ -1207,10 +1212,10 @@ that shows the problem that arises if you fail to save the match data: You can save and restore the match data with @code{save-match-data}: -@defspec save-match-data body@dots{} +@defmac save-match-data body@dots{} This special form executes @var{body}, saving and restoring the match data around it. -@end defspec +@end defmac You can use @code{set-match-data} together with @code{match-data} to imitate the effect of the special form @code{save-match-data}. This is @@ -1318,9 +1323,10 @@ this matches a line that starts with a formfeed character. match always starts at the beginning of a line; they should not use @samp{^} to anchor the match. Most often, the paragraph commands do check for a match only at the beginning of a line, which means that -@samp{^} would be superfluous. When there is a left margin, they accept -matches that start after the left margin. In that case, a @samp{^} -would be incorrect. +@samp{^} would be superfluous. When there is a nonzero left margin, +they accept matches that start after the left margin. In that case, a +@samp{^} would be incorrect. However, a @samp{^} is harmless in modes +where a left margin is never used. @defvar paragraph-separate This is the regular expression for recognizing the beginning of a line diff --git a/lispref/sequences.texi b/lispref/sequences.texi index 0982b19c743..c6de3f1c94d 100644 --- a/lispref/sequences.texi +++ b/lispref/sequences.texi @@ -15,8 +15,8 @@ collection of elements. An @dfn{array} is a single primitive object that has a slot for each elements. All the elements are accessible in constant time, but the -length of an existing array cannot be changed. Both strings and vectors -are arrays. +length of an existing array cannot be changed. Strings and vectors are +the two types of arrays. A list is a sequence of elements, but it is not a single primitive object; it is made of cons cells, one cell per element. Finding the @@ -36,7 +36,7 @@ But it is possible to add elements to the list, or remove elements. | | List | | Array | | | | | | ________ _______ | | | |______| | | | | | | | - | | | String | | Vector| | | + | | | Vector | | String| | | | | |________| |_______| | | | |______________________| | |___________________________________| @@ -191,9 +191,8 @@ otherwise, they trigger an @code{args-out-of-range} error. @end group @end example -This function duplicates @code{aref} (@pxref{Array Functions}) and -@code{nth} (@pxref{List Elements}), except that it works for any kind of -sequence. +This function generalizes @code{aref} (@pxref{Array Functions}) and +@code{nth} (@pxref{List Elements}). @end defun @node Arrays @@ -232,9 +231,9 @@ The elements of an array may be referenced or changed with the functions @code{aref} and @code{aset}, respectively (@pxref{Array Functions}). @end itemize - In principle, if you wish to have an array of characters, you could use -either a string or a vector. In practice, we always choose strings for -such applications, for four reasons: + In principle, if you wish to have an array of text characters, you +could use either a string or a vector. In practice, we always choose +strings for such applications, for four reasons: @itemize @bullet @item @@ -253,6 +252,11 @@ strings. For example, you cannot insert a vector of characters into a buffer the way you can insert a string. @xref{Strings and Characters}. @end itemize + By contrast, for an array of keyboard input characters (such as a key +sequence), a vector may be necessary, because many keyboard input +characters are outside the range that will fit in a string. @xref{Key +Sequence Input}. + @node Array Functions @section Functions that Operate on Arrays diff --git a/lispref/streams.texi b/lispref/streams.texi index 6efa571ff9c..db7e9aa38ea 100644 --- a/lispref/streams.texi +++ b/lispref/streams.texi @@ -52,7 +52,7 @@ text produces a list (but not the same list) with elements @code{a} and @code{b}. However, these two operations are not precisely inverses. There are -two kinds of exceptions: +three kinds of exceptions: @itemize @bullet @item @@ -66,6 +66,10 @@ One object can have multiple textual representations. For example, @samp{1} and @samp{01} represent the same integer, and @samp{(a b)} and @samp{(a .@: (b))} represent the same list. Reading will accept any of the alternatives, but printing must choose one of them. + +@item +Comments can appear at certain points in the middle of an object's +read sequence without affecting the result of reading it. @end itemize @node Input Streams @@ -160,8 +164,9 @@ whitespace preceding the significant text. In Emacs 18, reading a symbol discarded the delimiter terminating the symbol. Thus, point would end up at the beginning of @samp{contents} rather than after @samp{the}. The Emacs 19 behavior is superior because -it correctly handles input such as @samp{bar(foo)}, where the delimiter -that ends one object is needed as the beginning of another object. +it correctly handles input such as @samp{bar(foo)}, where the +open-parenthesis that ends one object is needed as the beginning of +another object. Here is an example of reading from a stream that is a marker, initially positioned at the beginning of the buffer shown. The value diff --git a/lispref/strings.texi b/lispref/strings.texi index a0321476dc0..d923d0407cd 100644 --- a/lispref/strings.texi +++ b/lispref/strings.texi @@ -70,8 +70,16 @@ characters. @xref{Character Type}, for more information about representation of meta and other modifiers for keyboard input characters. + Strings are useful for holding regular expressions. You can also +match regular expressions against strings (@pxref{Regexp Search}). The +functions @code{match-string} (@pxref{Simple Match Data}) and +@code{replace-match} (@pxref{Replacing Match}) are useful for +decomposing and modifying strings based on regular expression matching. + Like a buffer, a string can contain text properties for the characters in it, as well as the characters themselves. @xref{Text Properties}. +All the Lisp primitives that copy text from strings to buffers or other +strings also copy the properties of the characters being copied. @xref{Text}, for information about functions that display strings or copy them into buffers. @xref{Character Type}, and @ref{String Type}, @@ -116,7 +124,7 @@ putting strings together, or by taking them apart. @end defun @defun substring string start &optional end - This function returns a new string which consists of those characters +This function returns a new string which consists of those characters from @var{string} in the range from (and including) the character at the index @var{start} up to (but excluding) the character at the index @var{end}. The first character is at index zero. @@ -175,6 +183,9 @@ of @var{string}. But we recommend @code{copy-sequence} for this purpose (@pxref{Sequence Functions}). +If the characters copied from @var{string} have text properties, the +properties are copied into the new string also. @xref{Text Properties}. + A @code{wrong-type-argument} error is signaled if either @var{start} or @var{end} is not an integer or @code{nil}. An @code{args-out-of-range} error is signaled if @var{start} indicates a character following @@ -190,9 +201,10 @@ beginning of a buffer is at index 1. @cindex copying strings @cindex concatenating strings This function returns a new string consisting of the characters in the -arguments passed to it. The arguments may be strings, lists of numbers, -or vectors of numbers; they are not themselves changed. If -@code{concat} receives no arguments, it returns an empty string. +arguments passed to it (along with their text properties, if any). The +arguments may be strings, lists of numbers, or vectors of numbers; they +are not themselves changed. If @code{concat} receives no arguments, it +returns an empty string. @example (concat "abc" "-def") diff --git a/lispref/symbols.texi b/lispref/symbols.texi index caba9a9bd7e..1921dec922c 100644 --- a/lispref/symbols.texi +++ b/lispref/symbols.texi @@ -151,7 +151,8 @@ expression and storing it in the function cell of the symbol. This lambda expression thus becomes the function definition of the symbol. (The term ``function definition'', meaning the contents of the function cell, is derived from the idea that @code{defun} gives the symbol its -definition as a function.) @xref{Functions}. +definition as a function.) @code{defsubst} and @code{defalias} are two +other ways of defining a function. @xref{Functions}. @code{defmacro} defines a symbol as a macro. It creates a macro object and stores it in the function cell of the symbol. Note that a @@ -160,8 +161,8 @@ both macro and function definitions are kept in the function cell, and that cell can hold only one Lisp object at any given time. @xref{Macros}. - In GNU Emacs Lisp, a definition is not required in order to use a -symbol as a variable or function. Thus, you can make a symbol a global + In Emacs Lisp, a definition is not required in order to use a symbol +as a variable or function. Thus, you can make a symbol a global variable with @code{setq}, whether you define it first or not. The real purpose of definitions is to guide programmers and programming tools. They inform programmers who read the code that certain symbols are @@ -503,11 +504,11 @@ stored in the property list @var{plist}. For example, @end defun @defun plist-put plist property value -This stores @var{value} as the value of the @var{property} property -stored in the property list @var{plist}. It may modify @var{plist} -destructively, or it may construct new list structure without altering -the old. The function returns the modified property list, so you can -store that back in the place where you got @var{plist}. For example, +This stores @var{value} as the value of the @var{property} property in +the property list @var{plist}. It may modify @var{plist} destructively, +or it may construct new list structure without altering the old. The +function returns the modified property list, so you can store that back +in the place where you got @var{plist}. For example, @example (setq my-plist '(bar t foo 4)) diff --git a/lispref/syntax.texi b/lispref/syntax.texi index f621e0c0ddf..585df47580a 100644 --- a/lispref/syntax.texi +++ b/lispref/syntax.texi @@ -43,7 +43,7 @@ this chapter. @end ifinfo A syntax table is a vector of 256 elements; it contains one entry for -each of the 256 @sc{ASCII} characters of an 8-bit byte. Each element is +each of the 256 possible characters in an 8-bit byte. Each element is an integer that encodes the syntax of the character in question. Syntax tables are used only for moving across text, not for the Emacs @@ -650,8 +650,8 @@ exceed that many. @node Standard Syntax Tables @section Some Standard Syntax Tables - Each of the major modes in Emacs has its own syntax table. Here are -several of them: + Most of the major modes in Emacs have their own syntax tables. Here +are several of them: @defun standard-syntax-table This function returns the standard syntax table, which is the syntax diff --git a/lispref/text.texi b/lispref/text.texi index eefd2c30259..b4547224308 100644 --- a/lispref/text.texi +++ b/lispref/text.texi @@ -26,7 +26,7 @@ interactive call, point and the mark are used for these arguments. @cindex buffer contents Throughout this chapter, ``text'' refers to the characters in the -buffer. +buffer, together with their properties (when relevant). @menu * Near Point:: Examining text in the vicinity of point. @@ -41,6 +41,7 @@ buffer. * Maintaining Undo:: How to enable and disable undo information. How to control how much information is kept. * Filling:: Functions for explicit filling. +* Margins:: How to specify margins for filling commands. * 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. @@ -239,7 +240,8 @@ the result is one plus the index of the first differing characters within the substrings. This function ignores case when comparing characters -if @code{case-fold-search} is non-@code{nil}. +if @code{case-fold-search} is non-@code{nil}. It always ignores +text properties. Suppose the current buffer contains the text @samp{foobarbar haha!rara!}; then in this example the two substrings are @samp{rbar } @@ -250,12 +252,10 @@ at the second character. (compare-buffer-substring nil 6 11 nil 16 21) @result{} 2 @end example - -This function does not exist in Emacs version 18 and earlier. @end defun @node Insertion -@section Insertion +@section Inserting Text @cindex insertion of text @cindex text insertion @@ -280,6 +280,12 @@ point} and the latter insertion @dfn{before point}. Insertion functions signal an error if the current buffer is read-only. + These functions copy text characters from strings and buffers along +with their properties. The inserted characters have exactly the same +properties as the characters they were copied from. By contrast, +characters specified as separate arguments, not part of a string or +buffer, inherit their text properties from the neighboring text. + @defun insert &rest args This function inserts the strings and/or characters @var{args} into the current buffer, at point, moving point forward. In other words, it @@ -393,6 +399,9 @@ result in this case is to insert two newlines at different places: one at point, and another earlier in the line. @code{newline} does not auto-fill if @var{number-of-newlines} is non-@code{nil}. +This command indents to the left margin if that is not zero. +@xref{Margins}. + The value returned is @code{nil}. In an interactive call, @var{count} is the numeric prefix argument. @end deffn @@ -414,7 +423,7 @@ buffer-local when set in any fashion. @end defvar @node Deletion -@section Deletion of Text +@section Deleting Text @cindex deletion vs killing Deletion means removing part of the text in a buffer, without saving @@ -544,7 +553,7 @@ instead. The value is @code{nil}. If there is a fill prefix, and the second of the lines being joined starts with the prefix, then @code{delete-indentation} deletes the -fill prefix before joining the lines. @xref{Filling}. +fill prefix before joining the lines. @xref{Margins}. In the example below, point is located on the line starting @samp{events}, and it makes no difference if there are trailing spaces @@ -713,8 +722,8 @@ and if so appends the killed text to the most recent entry. @deffn Command kill-region start end This function kills the text in the region defined by @var{start} and -@var{end}. The text is deleted but saved in the kill ring. The value -is always @code{nil}. +@var{end}. The text is deleted but saved in the kill ring, along with +its text properties. The value is always @code{nil}. In an interactive call, @var{start} and @var{end} are point and the mark. @@ -728,9 +737,10 @@ text into the kill ring from a read-only buffer. @deffn Command copy-region-as-kill start end This command saves the region defined by @var{start} and @var{end} on -the kill ring, but does not delete the text from the buffer. It returns -@code{nil}. It also indicates the extent of the text copied by moving -the cursor momentarily, or by displaying a message in the echo area. +the kill ring (including text properties), but does not delete the text +from the buffer. It returns @code{nil}. It also indicates the extent +of the text copied by moving the cursor momentarily, or by displaying a +message in the echo area. The command does not set @code{this-command} to @code{kill-region}, so a subsequent kill command does not append to the same kill ring entry. @@ -745,7 +755,7 @@ support Emacs 18. For Emacs 19, it is better to use @code{kill-new} or @subsection Functions for Yanking @dfn{Yanking} means reinserting an entry of previously killed text -from the kill ring. +from the kill ring. The text properties are copied too. @deffn Command yank &optional arg @cindex inserting killed text @@ -975,8 +985,9 @@ Here's how you might undo the change: @end example @item @var{position} -This element indicates where point was at an earlier time. -Undoing this element sets point to @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 @@ -1018,7 +1029,7 @@ but it is convenient to have it in C. changes the buffer. Undo commands avoid confusion by saving the undo list value at the beginning of a sequence of undo operations. Then the undo operations use and update the saved value. The new elements added -by undoing are not part of the saved value, so they don't interfere with +by undoing are not part of this saved value, so they don't interfere with continuing to undo. @end defun @@ -1089,10 +1100,9 @@ change group is never discarded separate no matter how big it is. @dfn{Filling} means adjusting the lengths of lines (by moving the line breaks) so that they are nearly (but no greater than) a specified maximum width. Additionally, lines can be @dfn{justified}, which means -that spaces are inserted between words to make the line exactly the -specified width. The width is controlled by the variable -@code{fill-column}. For ease of reading, lines should be no longer than -70 or so columns. +inserting spaces to make the left and/or right margins line up +precisely. The width is controlled by the variable @code{fill-column}. +For ease of reading, lines should be no longer than 70 or so columns. You can use Auto Fill mode (@pxref{Auto Filling}) to fill text automatically as you insert it, but changes to existing text may leave @@ -1100,28 +1110,38 @@ it improperly filled. Then you must fill the text explicitly. Most of the commands in this section return values that are not meaningful. All the functions that do filling take note of the current -left margin, current right margin, and current justification style. If -the current justification style is @code{none}, the filling functions -don't actually do anything. +left margin, current right margin, and current justification style +(@pxref{Margins}). If the current justification style is +@code{none}, the filling functions don't actually do anything. + + Several of the filling functions have an argument @var{justify}. +If it is non-@code{nil}, that requests some kind of justification. It +can be @code{left}, @code{right}, @code{full}, or @code{center}, to +request a specific style of justification. If it is @code{t}, that +means to use the current justification style for this part of the text +(see @code{current-justification}, below). + + When you call the filling functions interactively, using a prefix +argument implies the value @code{full} for @var{justify}. -@deffn Command fill-paragraph justify-flag +@deffn Command fill-paragraph justify @cindex filling a paragraph This command fills the paragraph at or after point. If -@var{justify-flag} is non-@code{nil}, each line is justified as well. +@var{justify} is non-@code{nil}, each line is justified as well. It uses the ordinary paragraph motion commands to find paragraph boundaries. @xref{Paragraphs,,, emacs, The Emacs Manual}. @end deffn -@deffn Command fill-region start end &optional justify-flag +@deffn Command fill-region start end &optional justify This command fills each of the paragraphs in the region from @var{start} -to @var{end}. It justifies as well if @var{justify-flag} is +to @var{end}. It justifies as well if @var{justify} is non-@code{nil}. The variable @code{paragraph-separate} controls how to distinguish paragraphs. @xref{Standard Regexps}. @end deffn -@deffn Command fill-individual-paragraphs start end &optional justify-flag mail-flag +@deffn Command fill-individual-paragraphs start end &optional justify mail-flag This command fills each paragraph in the region according to its individual fill prefix. Thus, if the lines of a paragraph were indented with spaces, the filled paragraph will remain indented in the same @@ -1129,8 +1149,8 @@ fashion. The first two arguments, @var{start} and @var{end}, are the beginning and end of the region to be filled. The third and fourth arguments, -@var{justify-flag} and @var{mail-flag}, are optional. If -@var{justify-flag} is non-@code{nil}, the paragraphs are justified as +@var{justify} and @var{mail-flag}, are optional. If +@var{justify} is non-@code{nil}, the paragraphs are justified as well as filled. If @var{mail-flag} is non-@code{nil}, it means the function is operating on a mail message and therefore should not fill the header lines. @@ -1147,13 +1167,11 @@ This variable alters the action of @code{fill-individual-paragraphs} as described above. @end defopt -@deffn Command fill-region-as-paragraph start end &optional justify-flag +@deffn Command fill-region-as-paragraph start end &optional justify This command considers a region of text as a 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 filling when -@var{justify-flag} is non-@code{nil}. The precise value of -@var{justify-flag} specifies a style of justification, as in -@code{justify-current-line}, below. +@var{justify} is non-@code{nil}. In an interactive call, any prefix argument requests justification. @@ -1187,7 +1205,7 @@ whitespace. This variable's value specifies the style of justification to use for text that doesn't specify a style with a text property. The possible values are @code{left}, @code{right}, @code{full}, @code{center}, or -@code{none}. +@code{none}. The default value is @code{left}. @end defopt @defun current-justification @@ -1195,6 +1213,32 @@ This function returns the proper justification style to use for filling the text around point. @end defun +@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 +this function to do the work. If the function returns a non-@code{nil} +value, @code{fill-paragraph} assumes the job is done, and immediately +returns that value. + +The usual use of this feature is to fill comments in programming +language modes. If the function needs to fill a paragraph in the usual +way, it can do so as follows: + +@example +(let ((fill-paragraph-function nil)) + (fill-paragraph arg)) +@end example +@end defvar + +@defvar use-hard-newlines +If this variable is non-@code{nil}, the filling functions do not delete +newlines that have the @code{hard} text property. These ``hard +newlines'' act as paragraph separators. +@end defvar + +@node Margins +@section Margins for Filling + @defopt fill-prefix This variable specifies a string of text that appears at the beginning of normal text lines and should be disregarded when filling them. Any @@ -1203,6 +1247,8 @@ a paragraph; so is any line that starts with the fill prefix followed by additional whitespace. Lines that start with the fill prefix but no additional whitespace are ordinary text lines that can be filled together. The resulting filled lines also start with the fill prefix. + +The fill prefix follows the left margin whitespace, if any. @end defopt @defopt fill-column @@ -1225,23 +1271,6 @@ buffers that do not override it. This is the same as The default value for @code{default-fill-column} is 70. @end defvar -@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 -this function to do the work. If the function returns a non-@code{nil} -value, @code{fill-paragraph} assumes the job is done, and immediately -returns that value. - -The usual use of this feature is to fill comments in programming -language modes. If the function needs to fill a paragraph in the usual -way, it can do so as follows: - -@example -(let ((fill-paragraph-function nil)) - (fill-paragraph arg)) -@end example -@end defvar - @deffn Command set-left-margin from to margin This sets the @code{left-margin} property on the text from @var{from} to @var{to} to the value @var{margin}. If Auto Fill mode is enabled, this @@ -1249,17 +1278,16 @@ command also refills the region to fit the new margin. @end deffn @deffn Command set-right-margin from to margin -This sets the @code{fill-colmn} property on the text from @var{from} to -@var{to} so as to yield a right margin of width @var{margin}. If Auto -Fill mode is enabled, this command also refills the region to fit the -new margin. +This sets the @code{right-margin} property on the text from @var{from} +to @var{to} to the value @var{margin}. If Auto Fill mode is enabled, +this command also refills the region to fit the new margin. @end deffn @defun current-left-margin This function returns the proper left margin value to use for filling the text around point. The value is the sum of the @code{left-margin} property of the character at the start of the current line (or zero if -none), plus the value of the variable @code{left-margin}. +none), and the value of the variable @code{left-margin}. @end defun @defun current-fill-column @@ -1272,7 +1300,7 @@ character after point. @deffn Command move-to-left-margin &optional n force This function moves point to the left margin of the current line. The column moved to is determined by calling the function -@code{current-left-margin}. If the argument @var{n} is specified, +@code{current-left-margin}. If the argument @var{n} is non-@code{nil}, @code{move-to-left-margin} moves forward @var{n}@minus{}1 lines first. If @var{force} is non-@code{nil}, that says to fix the line's @@ -1286,6 +1314,20 @@ to delete is determined by calling @code{current-left-margin}. In no case does this function delete non-whitespace. @end defun +@defun indent-to-left-margin +This is the default @code{indent-line-function}, used in Fundamental +mode, Text mode, etc. Its effect is to adjust the indentation at the +beginning of the current line to the value specified by the variable +@code{left-margin}. This may involve either inserting or deleting +whitespace. +@end defun + +@defvar left-margin +This variable specifies the base left margin column. In Fundamental +mode, @key{LFD} indents to this column. This variable automatically +becomes buffer-local when set in any fashion. +@end defvar + @node Auto Filling @comment node-name, next, previous, up @section Auto Filling @@ -1297,6 +1339,9 @@ as inserted. This section describes the hook used by Auto Fill mode. For a description of functions that you can call explicitly to fill and justify existing text, see @ref{Filling}. + Auto Fill mode also enables the functions that change the margins and +justification style to refill portions of the text. @xref{Margins}. + @defvar auto-fill-function The value of this variable should be a function (of no arguments) to be called after self-inserting a space or a newline. It may be @code{nil}, @@ -1539,8 +1584,6 @@ containing position @var{beg}, and the entire line containing position Note that @code{sort-columns} uses the @code{sort} utility program, and so cannot work properly on text containing tab characters. Use @kbd{M-x @code{untabify}} to convert tabs to spaces before sorting. - -The @code{sort-columns} function did not work on VMS prior to Emacs 19. @end deffn @node Columns @@ -1689,20 +1732,6 @@ the current line; except that if that function is is a trivial command that inserts a tab character.) @end deffn -@defun indent-to-left-margin -This is the default @code{indent-line-function}, used in Fundamental -mode, Text mode, etc. Its effect is to adjust the indentation at the -beginning of the current line to the value specified by the variable -@code{left-margin}. This may involve either inserting or deleting -whitespace. -@end defun - -@defvar left-margin -This variable specifies the column for @code{indent-to-left-margin} to -indent to. In Fundamental mode, @key{LFD} indents to this column. This -variable automatically becomes buffer-local when set in any fashion. -@end defvar - @deffn Command newline-and-indent @comment !!SourceFile simple.el This function inserts a newline, then indents the new line (the one @@ -2107,8 +2136,8 @@ This function returns the entire property list of the character at @defvar default-text-properties This variable holds a property list giving default values for text properties. Whenever a character does not specify a value for a -property, the value stored in this list is used instead. Here is an -example: +property, neither directly nor through a category symbol, the value +stored in this list is used instead. Here is an example: @example (setq default-text-properties '(foo 69)) @@ -2134,6 +2163,12 @@ can affect how the buffer looks on the screen, any change in the text properties is considered a buffer modification. Buffer text property changes are undoable (@pxref{Undo}). +@defun put-text-property start end prop value &optional object +This function sets the @var{prop} property to @var{value} for the text +between @var{start} and @var{end} in the string or buffer @var{object}. +If @var{object} is @code{nil}, it defaults to the current buffer. +@end defun + @defun add-text-properties start end props &optional object This function modifies the text properties for the text between @var{start} and @var{end} in the string or buffer @var{object}. If @@ -2157,12 +2192,6 @@ properties of a range of text: @end example @end defun -@defun put-text-property start end prop value &optional object -This function sets the @var{prop} property to @var{value} for the text -between @var{start} and @var{end} in the string or buffer @var{object}. -If @var{object} is @code{nil}, it defaults to the current buffer. -@end defun - @defun remove-text-properties start end props &optional object This function deletes specified text properties from the text between @var{start} and @var{end} in the string or buffer @var{object}. If @@ -2214,13 +2243,14 @@ consecutive characters have the same value for a property. Rather than writing your programs to examine characters one by one, it is much faster to process chunks of text that have the same property value. -Here are functions you can use to do this. In all cases, @var{object} -defaults to the current buffer. +Here are functions you can use to do this. They use @code{eq} for +comparing property values. In all cases, @var{object} defaults to the +current buffer. For high performance, it's very important to use the @var{limit} argument to these functions, especially the ones that search for a -single property---otherwise, they may spend a long time considering -changes in other properties while scanning to the end of the buffer. +single property---otherwise, they may spend a long time scanning to the +end of the buffer, if the property you are interested in does not change. Remember that a position is always between two characters; the position returned by these functions is between two characters with different @@ -2314,6 +2344,11 @@ for @var{object} is the current buffer. @node Special Properties @subsection Properties with Special Meanings + Here is a table of text property names that have special built-in +meanings. The following section lists a few more special property names +that are used to control filling. All other names have no standard +meaning, and you can use them as you like. + @table @code @cindex category of text character @kindex category @r{(text property)} @@ -2370,8 +2405,8 @@ on the screen. @xref{Invisible Text}, for details. @kindex intangible @r{(text property)} If a group of consecutive characters have equal and non-@code{nil} @code{intangible} properties, then you cannot place point between them. -If you move point forward into the group, point actually moves to the -end of the group. If you try to move point backward into the group, +If you try to move point forward into the group, point actually moves to +the end of the group. If you try to move point backward into the group, point actually moves to the start of the group. When the variable @code{inhibit-point-motion-hooks} is non-@code{nil}, @@ -2444,12 +2479,13 @@ property has no effect. @end defvar @node Format Properties -@section Formatted Text Properties +@subsection Formatted Text Properties These text properties affect the behavior of the fill commands. They -are used for representing formatted text. @xref{Filling}. +are used for representing formatted text. @xref{Filling}, and +@ref{Margins}. -@table code +@table @code @item hard If a newline character has this property, it is a ``hard'' newline. The fill commands do not alter hard newlines and do not move words @@ -2457,11 +2493,11 @@ across them. However, this property takes effect only if the variable @code{use-hard-newlines} is non-@code{nil}. @item right-margin -This property specifies the right margin for filling this part of the +This property specifies an extra right margin for filling this part of the text. @item left-margin -This property specifies the left margin for filling this part of the +This property specifies an extra left margin for filling this part of the text. @item justification @@ -2541,7 +2577,7 @@ adjoining text. You can save text properties in files, and restore text properties when inserting the files, using these two hooks: -@defvar write-region-annotation-functions +@defvar write-region-annotate-functions This variable's value is a list of functions for @code{write-region} to run to encode text properties in some fashion as annotations to the text being written in the file. @xref{Writing to Files}. @@ -2597,6 +2633,10 @@ names or property values---because a program that general is probably difficult to write, and slow. Instead, choose a set of possible data types that are reasonably flexible, and not too hard to encode. +@xref{Format Conversion}, for a related feature. + +@c ??? In next edition, merge this info Format Conversion. + @node Not Intervals @subsection Why Text Properties are not Intervals @cindex intervals @@ -2659,11 +2699,10 @@ defined by @var{start} and @var{end}. @cindex Outline mode @cindex undo avoidance -If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} -does not record the change for undo and does not mark the buffer as -modified. This feature is useful for changes that are not considered -significant, such as when Outline mode changes visible lines to -invisible lines and vice versa. +If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does +not record the change for undo and does not mark the buffer as modified. +This feature is used for controlling selective display (@pxref{Selective +Display}). @code{subst-char-in-region} does not move point and returns @code{nil}. @@ -2700,8 +2739,6 @@ The return value of @code{translate-region} is the number of characters that were actually changed by the translation. This does not count characters that were mapped into themselves in the translation table. - -This function is available in Emacs versions 19 and later. @end defun @node Registers @@ -2875,13 +2912,13 @@ buffer that's about to change is always the current buffer. @end defvar @defvar before-change-function -This variable holds one function to call before any buffer modification -(or @code{nil} for no function). It is called just like the functions -in @code{before-change-functions}. +This obsolete variable holds one function to call before any buffer +modification (or @code{nil} for no function). It is called just like +the functions in @code{before-change-functions}. @end defvar @defvar after-change-function -This variable holds one function to call after any buffer modification +This obsolete variable holds one function to call after any buffer modification (or @code{nil} for no function). It is called just like the functions in @code{after-change-functions}. @end defvar @@ -2916,6 +2953,3 @@ to call. Here is an example: This variable is a normal hook that is run whenever a buffer is changed that was previously in the unmodified state. @end defvar - - The variables described in this section are meaningful only starting -with Emacs version 19. diff --git a/lispref/tips.texi b/lispref/tips.texi index 9c252748230..76cd3427eef 100644 --- a/lispref/tips.texi +++ b/lispref/tips.texi @@ -60,14 +60,28 @@ library program, at least if there is more than one entry point to the program. @item +If a file requires certain other library programs to be loaded +beforehand, then the comments at the beginning of the file should say +so. Also, use @code{require} to make sure they are loaded. + +@item If one file @var{foo} uses a macro defined in another file @var{bar}, -@var{foo} should contain @code{(require '@var{bar})} before the first -use of the macro. (And @var{bar} should contain @code{(provide -'@var{bar})}, to make the @code{require} work.) This will cause -@var{bar} to be loaded when you byte-compile @var{foo}. Otherwise, you -risk compiling @var{foo} without the necessary macro loaded, and that -would produce compiled code that won't work right. @xref{Compiling -Macros}. +@var{foo} should contain this expression before the first use of the +macro: + +@example +(eval-when-compile (require '@var{bar})) +@end example + +@noindent +(And @var{bar} should contain @code{(provide '@var{bar})}, to make the +@code{require} work.) This will cause @var{bar} to be loaded when you +byte-compile @var{foo}. Otherwise, you risk compiling @var{foo} without +the necessary macro loaded, and that would produce compiled code that +won't work right. @xref{Compiling Macros}. + +Using @code{eval-when-compile} avoids loading @var{bar} when +the compiled version of @var{foo} is @emph{used}. @item If you define a major mode, make sure to run a hook variable using @@ -156,11 +170,6 @@ say which functions are replaced, and how the behavior of the replacements differs from that of the originals. @item -If a file requires certain standard library programs to be loaded -beforehand, then the comments at the beginning of the file should say -so. - -@item Please keep the names of your Emacs Lisp source files to 13 characters or less. This way, if the files are compiled, the compiled files' names will be 14 characters or less, which is short enough to fit on all kinds @@ -212,6 +221,10 @@ Do not use @code{message}, @code{throw}, @code{sleep-for}, or @code{beep} to report errors. @item +An error message should start with a capital letter but should not end +with a period. + +@item Try to avoid using recursive edits. Instead, do what the Rmail @kbd{e} command does: use a new local keymap that contains one command defined to switch back to the old local keymap. Or do what the @@ -265,10 +278,10 @@ Function calls are slow in Emacs Lisp even when a compiled function is calling another compiled function. @item -Using the primitive list-searching functions @code{memq}, @code{assq}, or -@code{assoc} is even faster than explicit iteration. It may be worth -rearranging a data structure so that one of these primitive search -functions can be used. +Using the primitive list-searching functions @code{memq}, @code{member}, +@code{assq}, or @code{assoc} is even faster than explicit iteration. It +may be worth rearranging a data structure so that one of these primitive +search functions can be used. @item Certain built-in functions are handled specially in byte-compiled code, @@ -431,10 +444,6 @@ It is not practical to use @samp{\\[@dots{}]} very many times, because display of the documentation string will become slow. So use this to describe the most important commands in your major mode, and then use @samp{\\@{@dots{}@}} to display the rest of the mode's keymap. - -@item -Don't use the term ``Elisp'', since that is or was a trademark. -Use the term ``Emacs Lisp''. @end itemize @node Comment Tips diff --git a/lispref/variables.texi b/lispref/variables.texi index fb08a390c6d..34cd07b6769 100644 --- a/lispref/variables.texi +++ b/lispref/variables.texi @@ -231,6 +231,12 @@ Macro calls (@pxref{Macros}). @code{condition-case} (@pxref{Errors}). @end itemize + Variables can also have buffer-local bindings (@pxref{Buffer-Local +Variables}); a few variables have terminal-local bindings +(@pxref{Multiple Displays}). These kinds of bindings work somewhat like +ordinary local bindings, but they are localized depending on ``where'' +you are in Emacs, rather than localized in time. + @defvar max-specpdl-size @cindex variable limit error @cindex evaluation error @@ -409,6 +415,12 @@ is not even evaluated, and @var{symbol}'s value remains unchanged. If evaluates it and sets @var{symbol} to the result. (If @var{value} is omitted, the value of @var{symbol} is not changed in any case.) +When you evaluate a top-level @code{defvar} form with @kbd{C-M-x} in +Emacs Lisp mode (@code{eval-defun}), a special feature of +@code{eval-defun} evaluates it as a @code{defconst}. The purpose of +this is to make sure the variable's value is reinitialized, when you ask +for it specifically. + If @var{symbol} has a buffer-local binding in the current buffer, @code{defvar} sets the default value, not the local value. @xref{Buffer-Local Variables}. @@ -532,9 +544,9 @@ then the variable is a user option. @end defun If a user option variable has a @code{variable-interactive} property, -@code{set-variable} uses that value to control reading the new value for -the variable. The property's value is used as if it were the argument -to @code{interactive}. +the @code{set-variable} command uses that value to control reading the +new value for the variable. The property's value is used as if it were +the argument to @code{interactive}. @strong{Warning:} If the @code{defconst} and @code{defvar} special forms are used while the variable has a local binding, they set the @@ -714,7 +726,12 @@ an element to a list if it is not already present in the list. @defun add-to-list symbol element This function sets the variable @var{symbol} by consing @var{element} onto the old value, if @var{element} is not already a member of that -value. The value of @var{symbol} had better be a list already. +value. It returns the resulting list, whether updated or not. The +value of @var{symbol} had better be a list already before the call. + +The argument @var{symbol} is not implicitly quoted; @code{add-to-list} +is an ordinary function, like @code{set} and unlike @code{setq}. Quote +the argument yourself if that is what you want. Here's a scenario showing how to use @code{add-to-list}: @@ -944,6 +961,12 @@ Then you can bind the variable in other programs, knowing reliably what the effect will be. @end itemize + In either case, you should define the variable with @code{defvar}. +This helps other people understand your program by telling them to look +for inter-function usage. It also avoids a warning from the byte +compiler. Choose the variable's name to avoid name conflicts---don't +use short names like @code{x}. + @node Buffer-Local Variables @section Buffer-Local Variables @cindex variables, buffer-local @@ -1027,7 +1050,7 @@ example of what to avoid: (setq foo 'a) (let ((foo 'temp)) (set-buffer "b") - @dots{}) + @var{body}@dots{}) @group foo @result{} 'a ; @r{The old buffer-local value from buffer @samp{a}} ; @r{is now the default value.} @@ -1107,6 +1130,10 @@ variable does not work. This is because @code{let} does not distinguish between different kinds of bindings; it knows only which variable the binding was made for. +If the variable is terminal-local, this function signals an error. Such +variables cannot have buffer-local bindings as well. @xref{Multiple +Displays}. + @strong{Note:} do not use @code{make-local-variable} for a hook variable. Instead, use @code{make-local-hook}. @xref{Hooks}. @end deffn @@ -1119,6 +1146,12 @@ local to the current buffer at the time. The value returned is @var{variable}. @end deffn +@defun local-variable-p variable &optional buffer +This returns @code{t} if @var{variable} is buffer-local in buffer +@var{buffer} (which defaults to the current buffer); otherwise, +@code{nil}. +@end defun + @defun buffer-local-variables &optional buffer This function returns a list describing the buffer-local variables in buffer @var{buffer}. It returns an association list (@pxref{Association @@ -1153,12 +1186,6 @@ Note that storing new values into the @sc{cdr}s of cons cells in this list does @emph{not} change the local values of the variables. @end defun -@defun local-variable-p variable -This returns @code{t} if @var{variable} is buffer-local in the current -buffer. It is much faster to get the answer this way than to examine -the value of @code{buffer-local-variables}. -@end defun - @deffn Command kill-local-variable variable This function deletes the buffer-local binding (if any) for @var{variable} (a symbol) in the current buffer. As a result, the diff --git a/lispref/windows.texi b/lispref/windows.texi index b1dcd2d6e0e..35202827e18 100644 --- a/lispref/windows.texi +++ b/lispref/windows.texi @@ -36,25 +36,29 @@ displayed in windows. @cindex window @cindex selected window - A @dfn{window} is the physical area of the screen in which a buffer is -displayed. The term is also used to refer to a Lisp object that + A @dfn{window} in Emacs is the physical area of the screen in which a +buffer is displayed. The term is also used to refer to a Lisp object that represents that screen area in Emacs Lisp. It should be clear from the context which is meant. - There is always at least one window in any frame. In each frame, at -any time, one and only one window is designated as @dfn{selected within -the frame}. The frame's cursor appears in that window. There is also -one selected frame; and the window selected within that frame is -@dfn{the selected window}. The selected window's buffer is usually the -current buffer (except when @code{set-buffer} has been used). -@xref{Current Buffer}. - - For practical purposes, a window exists only while it is displayed on the -terminal. Once removed from the display, the window is effectively -deleted and should not be used, @emph{even though there may still be -references to it} from other Lisp objects. Restoring a saved window -configuration is the only way for a window no longer on the screen to -come back to life. (@xref{Deleting Windows}.) + Emacs groups windows into frames. A frame represents an area of +screen available for Emacs to use. Each frame always contains at least +one window, but you can subdivide it vertically or horizontally into +multiple nonoverlapping Emacs windows. + + In each frame, at any time, one and only one window is designated as +@dfn{selected within the frame}. The frame's cursor appears in that +window. At ant time, one frame is the selected frame; and the window +selected within that frame is @dfn{the selected window}. The selected +window's buffer is usually the current buffer (except when +@code{set-buffer} has been used). @xref{Current Buffer}. + + For practical purposes, a window exists only while it is displayed in +a frame. Once removed from the frame, the window is effectively deleted +and should not be used, @emph{even though there may still be references +to it} from other Lisp objects. Restoring a saved window configuration +is the only way for a window no longer on the screen to come back to +life. (@xref{Deleting Windows}.) Each window has the following attributes: @@ -93,17 +97,16 @@ how recently the window was selected @cindex multiple windows Users create multiple windows so they can look at several buffers at once. Lisp libraries use multiple windows for a variety of reasons, but -most often to give different views of the same information. In Rmail, -for example, you can move through a summary buffer in one window while -the other window shows messages one at a time as they are reached. +most often to display related information. In Rmail, for example, you +can move through a summary buffer in one window while the other window +shows messages one at a time as they are reached. The meaning of ``window'' in Emacs is similar to what it means in the context of general-purpose window systems such as X, but not identical. -The X Window System subdivides the screen into X windows; Emacs uses one -or more X windows, called @dfn{frames} in Emacs terminology, and -subdivides each of them into (nonoverlapping) Emacs windows. When you -use Emacs on an ordinary display terminal, Emacs subdivides the terminal -screen into Emacs windows. +The X Window System places X windows on the screen; Emacs uses one or +more X windows as frames, and subdivides them into +Emacs windows. When you use Emacs on a character-only terminal, Emacs +treats the whole terminal screen as one frame. @cindex terminal screen @cindex screen of terminal @@ -300,6 +303,9 @@ Count all windows in all existing frames. @item @code{visible} Count all windows in all visible frames. +@item 0 +Count all windows in all visible or iconified frames. + @item anything else Count precisely the windows in the selected frame, and no others. @end table @@ -370,6 +376,8 @@ If it is @code{nil}, operate on the selected frame. If it is @code{t}, operate on all frames. @item If it is @code{visible}, operate on all visible frames. +@item 0 +If it is 0, operate on all visible or iconified frames. @item If it is a frame, operate on that frame. @end itemize @@ -405,6 +413,14 @@ The return value is @var{window}. @end example @end defun +@defmac save-selected-window forms@dots{} +This macro records the selected window, executes @var{forms} +in sequence, then restores the earlier selected window. +It does not save or restore anything about the sizes, arrangement +or contents of windows; therefore, if the @var{forms} change them, +the changes are permanent. +@end defmac + @cindex finding windows The following functions choose one of the windows on the screen, offering various criteria for the choice. @@ -427,6 +443,8 @@ 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 @end defun @@ -503,6 +521,9 @@ Consider all windows in all existing frames. Consider all windows in all visible frames. (To get useful results, you must ensure @var{window} is in a visible frame.) +@item @code{t} +Consider all windows in all visible or iconified frames. + @item anything else Consider precisely the windows in @var{window}'s frame, and no others. @end table @@ -611,20 +632,12 @@ 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 @end defun -@deffn Command replace-buffer-in-windows buffer -This function replaces @var{buffer} with some other buffer in all -windows displaying it. The other buffer used is chosen with -@code{other-buffer}. In the usual applications of this function, you -don't care which other buffer is used; you just want to make sure that -@var{buffer} is no longer displayed. - -This function returns @code{nil}. -@end deffn - @node Displaying Buffers @section Displaying Buffers in Windows @cindex switching to a buffer @@ -716,12 +729,25 @@ already displayed in the selected window and @var{other-window} is @code{nil}, then the selected window is considered sufficient display for @var{buffer-or-name}, so that nothing needs to be done. +All the variables that affect @code{display-buffer} affect +@code{pop-to-buffer} as well. @xref{Choosing Window}. + If @var{buffer-or-name} is a string that does not name an existing buffer, a buffer by that name is created. The major mode for the new buffer is set according to the variable @code{default-major-mode}. @xref{Auto Major Mode}. @end defun +@deffn Command replace-buffer-in-windows buffer +This function replaces @var{buffer} with some other buffer in all +windows displaying it. The other buffer used is chosen with +@code{other-buffer}. In the usual applications of this function, you +don't care which other buffer is used; you just want to make sure that +@var{buffer} is no longer displayed. + +This function returns @code{nil}. +@end deffn + @node Choosing Window @section Choosing a Window for Display @@ -804,6 +830,13 @@ If the buffer's name is in this list, @code{display-buffer} handles the buffer specially. By default, special display means to give the buffer a dedicated frame. + +If an element is a list, instead of a string, then the @sc{car} of the +list is the buffer name, and the rest of the list says how to create the +frame. There are two possibilities for the rest of the list. It can be +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 @defvar special-display-regexps @@ -813,6 +846,10 @@ expressions in this list, @code{display-buffer} handles the buffer specially. By default, special display means to give the buffer a dedicated frame. + +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 @defvar special-display-function @@ -841,6 +878,20 @@ This variable holds frame parameters for @code{special-display-popup-frame} to use when it creates a frame. @end defopt +@defvar same-window-buffer-names +A list of buffer names for buffers that should be displayed in the +selected window. If the buffer's name is in this list, +@code{display-buffer} handles the buffer by switching to it in the +selected window. +@end defvar + +@defvar same-window-regexps +A list of regular expressions that specify buffers that should be +displayed in the selected window. If the buffer's name matches any of +the regular expressions in this list, @code{display-buffer} handles the +buffer by switching to it in the selected window. +@end defvar + @c Emacs 19 feature @defvar display-buffer-function This variable is the most flexible way to customize the behavior of @@ -1125,10 +1176,6 @@ This function scrolls the text in another window upward @var{count} lines. Negative values of @var{count}, or @code{nil}, are handled as in @code{scroll-up}. -The window that is scrolled is normally the one following the selected -window in the cyclic ordering of windows---the window that -@code{next-window} would return. @xref{Cyclic Window Ordering}. - You can specify a buffer to scroll with the variable @code{other-window-scroll-buffer}. When the selected window is the minibuffer, the next window is normally the one at the top left corner. @@ -1539,6 +1586,11 @@ comparing the old size data with the new. Creating or deleting windows counts as a size change, and therefore causes these functions to be called. Changing the frame size also counts, because it changes the sizes of the existing windows. + +It is not a good idea to use @code{save-window-excursion} in these +functions, because that always counts as a size change, and it would +cause these functions to be called over and over. In most cases, +@code{save-selected-window} is what you need here. @end defvar @node Coordinates and Windows @@ -1627,6 +1679,11 @@ buffers to the state specified by @var{configuration}. The argument @var{configuration} must be a value that was previously returned by @code{current-window-configuration}. +This function always counts as a window size change and triggers +execution of the @code{window-size-change-functions}. (It doesn't know +how to tell whether the new configuration actually differs from the old +one.) + Here is a way of using this function to get the same effect as @code{save-window-excursion}: @@ -1649,6 +1706,13 @@ that is visible. It also includes the choice of selected window. However, it does not include the value of point in the current buffer; use @code{save-excursion} if you wish to preserve that. +Don't use this construct when @code{save-selected-window} is all you need. + +Exit from @code{save-window-excursion} always triggers execution of the +@code{window-size-change-functions}. (It doesn't know how to tell +whether the restored configuration actually differs from the one in +effect at the end of the @var{forms}.) + The return value is the value of the final form in @var{forms}. For example: |