Mercurial > emacs
changeset 25751:467b88fab665
*** empty log message ***
line wrap: on
line diff
--- a/lispref/abbrevs.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/abbrevs.texi Fri Sep 17 06:59:04 1999 +0000 @@ -4,7 +4,7 @@ @c See the file elisp.texi for copying conditions. @setfilename ../info/abbrevs @node Abbrevs, Processes, Syntax Tables, Top -@chapter Abbrevs And Abbrev Expansion +@chapter Abbrevs and Abbrev Expansion @cindex abbrev @cindex abbrev table
--- a/lispref/advice.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/advice.texi Fri Sep 17 06:59:04 1999 +0000 @@ -174,6 +174,9 @@ list, then the first one (the one with the smallest position) found in the list of all classes of advice is used. +@xref{Argument Access in Advice}, for more information about argument +lists and advice. + The remaining elements, @var{flags}, are symbols that specify further information about how to use this piece of advice. Here are the valid symbols and their meanings: @@ -210,7 +213,7 @@ Activate advice for @var{function} when this @code{defadvice} is compiled or macroexpanded. This generates a compiled advised definition according to the current advice state, which will be used during -activation if appropriate. +activation if appropriate. @xref{Preactivation}. This is useful only if this @code{defadvice} is byte-compiled. @end table @@ -301,7 +304,9 @@ to put the new piece of advice. The value of @var{position} can either be @code{first}, @code{last}, or a number (counting from 0 at the beginning of the list). Numbers outside the range are mapped to the -closest extreme position. +beginning or the end of the range, whichever is closer. The +@var{position} value is ignored when redefining an existing piece of +advice. If @var{function} already has a piece of @var{advice} with the same name, then the position argument is ignored and the old advice is @@ -339,7 +344,7 @@ advice. @deffn Command ad-activate function &optional compile -This command activates the advice for @var{function}. +This command activates all the advice defined for @var{function}. @end deffn To activate advice for a function whose advice is already active is not
--- a/lispref/anti.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/anti.texi Fri Sep 17 06:59:04 1999 +0000 @@ -1,248 +1,226 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1998 Free Software Foundation, Inc. +@c Copyright (C) 1999 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Antinews, Index, Standard Hooks, Top -@appendix Emacs 19 Antinews +@appendix Emacs 20 Antinews For those users who live backwards in time, here is information about -downgrading to Emacs version 19.34. We hope you will enjoy the greater -simplicity that results from the absence of many Emacs 20 features. In -the following section, we carry this information back as far as Emacs -19.29, for which the previous printed edition of this manual was made. +downgrading to Emacs version 20.4. We hope you will enjoy the greater +simplicity that results from the absence of many Emacs 21 features. In +the following section, we carry this information back to Emacs +20.3, for which the previous printed edition of this manual was made. -@section Old Lisp Features in Emacs 19 - -Here are the most important of the features that you will learn -to do without in Emacs 19: +@section Old Lisp Features in Emacs 20 @itemize @bullet @item -In a great simplification, Emacs 19 supports ASCII characters only. -There are no multibyte characters, character sets, language -environments, coding systems, or input methods; all the functions that -specifically relate to them are gone as well. +The @code{push} and @code{pop} macros are not defined. + +@item +You can't display images in buffers. (Emacs is meant for editing text.) +With no images, there are no display margins, and no tool bars. + +@item +The @code{display} text property has no special meaning; you can use it +freely in Lisp programs, with no effects except what you implement for +yourself. With no images, who needs the @code{display} text property? + +@item +Faces have fewer attributes. The attributes @code{:family}, +@code{:height}, @code{:width}, @code{:weight}, and @code{:slant}, +have been replaced with a font name, a ``bold'' flag, and an +``italic'' flag. + +The attributes @code{:overline}, @code{:strike-through} +and @code{:box} have been eliminated too. + +With fewer font attributes, there are no functions +@code{set-face-attribute} and @code{face-attribute}. Instead, you +access these attributes using functions such as @code{face-font}, and +set them with functions such as @code{set-face-font}. (These functions +were available in Emacs 21, but are not as useful there.) + +@item +There are no facilities for playing sound. This means Emacs will +respect your peace and quiet, aside from occasional beeps. + +@item +Regular expressions do not support the POSIX character classes +such as @samp{[:alpha:]}. All characters are created equal. -Valid character codes for text must be in the range 0 through 255. -Within this range, there are no invalid character codes. +@item +Hash tables have been eliminated; use alists instead. + +@item +The Lisp printer does not detect and report circular structure. That is +ok, because the Lisp reader cannot recreate circular structure anyway. +However, there is a library @samp{cust-print.el} which can report +circular structure. + +@item +Emacs provides its own implementation of scroll bars, instead +of using those of the X toolkit. They always use the frame foreground +and background colors, so you cannot specify different colors for +the scroll bars. + +@item +For simplicity, all ASCII characters now have the same height and width. +(Certain characters, such as Chinese characters, always have have twice +the standard width.) All characters are created equal. + +@item +Tooltips operate using ordinary Emacs frames. + +@item +Areas of the mode line are not mouse-sensitive; however, some mouse +commands are available for the mode line as a whole. + +@item +Windows cannot have header lines. Conversely, there is no way to turn +off the mode line of a window unless it is a minibuffer. + +@item +Plain dashes are the only separators you can use in a menu. @item -The Custom facility has been replaced with a much simpler and more -general method of defining user option variables. Instead of -@code{defcustom}, which requires you to specify each user option's data -type and classify options into groups, all you have to do is write a -@code{defvar}. You should still start the documentation string with -@samp{*}, though. +Vertical fractional scrolling does not exist. + +@item +The functions @code{format} and @code{message} ignore and discard text +properties. + +@item +Colors are supported only on window systems, not on text-only terminals. +So the support functions for colors on text-only terminals are +not needed. + +@item +The functions @code{color-values}, @code{color-defined-p} and +@code{defined-colors} have been renamed to @code{x-color-values}, +@code{x-color-defined-p} and @code{x-defined-colors}. + +@item +Windows cannot be made fixed-width or fixed-height; +Emacs will adjust the size of all windows when it needs to. + +@item +The minibuffer prompt does not actually appear in content of the +minibuffer; it is displayed specially in the minibuffer window. + +@item +The ``exclusive open'' feature of @code{write-region} +has been eliminated; any non-@code{nil} value for the seventh +argument now means to ask the user for confirmation. + +@item +The function @code{buffer-size} always reports on the +current buffer. + +@item +The function @code{assoc-delete-all} has itself been deleted. +So there! + +@item +The variable @code{small-temporary-file-directory} has no special +meaning. There's only one variable for specifying which directory to +use for temporary files, @code{temporary-file-directory}, but not all +Emacs features use it anyway. Some use the @code{TMP} environment +variable, and some use the @code{TMPDIR} environment variable. + +@item +The variable @code{inhibit-modification-hooks} +has no special meaning. + +@item +The hook @code{fontification-functions} has been eliminated, +but there are other hooks, such as @code{window-scroll-functions}, +that you can use to do a similar job. + +@item +The variable @code{redisplay-dont-pause} +has no special meaning. + +@item +The hook @code{calendar-move-hook} has been deleted. + +@item +The function @code{move-to-column} treats any non-@code{nil} +second argument just like @code{t}. @end itemize +@section Old Lisp Features in Emacs 20.3 + +Here are the most important of the features that you will learn +to do without in Emacs 20.3: + Here are changes in the Lisp language itself: @itemize @bullet @item -Symbols whose names start with @samp{:} are no longer special -in any way. They start out void, like most other symbols. - -@item -The macros @code{when} and @code{unless} have been deleted. - -@item -The functions @code{caar}, @code{cadr}, @code{cdar} and @code{cddr} -no longer exist. - -@item -The function @code{functionp} is now gone. If you don't know -by now whether something is a function, Emacs can't tell you. -@end itemize - -Here are changes in handling strings and text. - -@itemize @bullet -@item -The function @code{substring} works only on strings, not on vectors. +The functions @code{line-beginning-position} and @code{line-end-position} +have been eliminated. @item -There are no more character categories. - -@item -When you compare strings with @code{equal}, it now compares -their string properties as well as their text. All must match, -or the strings are not equal. - -@item -@code{format-time-string} no longer supports specified field width -or specified padding. +The functions @code{directory-files-and-attributes}, +@code{file-attributes-lessp}, and @code{file-expand-wildcards}, have +been eliminated. @item -The functions @code{split-string} and @code{string} no longer exist. -Neither does @code{store-substring} or @code{sref}. - -@item -All printing characters have the same width. Therefore, we have deleted -@code{char-width}, @code{string-width} and -@code{truncate-string-to-width}. - -@item -We have eliminated the functions @code{next-char-property-change} and -@code{previous-char-property-change} also. +The functions @code{decode-coding-region} and @code{encode-coding-region} +leave text properties untouched, in case that is useful. (It rarely makes +any sense, though.) @item -Syntax parsing now determines the syntax of each character from the -syntax table alone---not from text properties. This makes the syntax -codes @samp{|} and @samp{!}, which were meant for use with text -properties, useless; so we have deleted them. +The functions @code{position-bytes} and @code{byte-to-position} have +been eliminated. @item -In the function @code{parse-partial-sexp}, passing @code{syntax-table} -as the sixth argument @var{commentstop} no longer has any special meaning. -And the return value has only eight elements. -@end itemize - -Here are changes in other areas of Emacs Lisp: - -@itemize @bullet -@item -The macros @code{save-current-buffer}, @code{with-current-buffer}, -@code{with-temp-buffer}, @code{with-temp-file}, @code{save-selected-window}, -and @code{with-output-to-string} are gone. - -@item -The easy-mmode facility for defining minor modes is gone too. +Temporary buffers made with @code{with-output-to-temp-buffer} are now +modifiable by default, and use Fundamental mode rather than Help mode. @item -Process filters and sentinels must explicitly save the match data, with -@code{save-match-data}, or they will clobber the match data and -something horrible will happen. - -@item -As part of our effort to loosen up, @code{batch-byte-compile-file} no -longer returns a nonzero status code if there is a compilation error. - -@item -The ``mail user agent'' feature is gone. +The functions @code{sref} interprets its @var{index} argument as a +number of bytes, not a number of characters. And the function +@code{char-bytes} actually tries to report on the number of bytes that a +character occupies. @item -We have removed the functions @code{add-to-invisibility-spec} and -@code{remove-from-invisibility-spec}, so you should manipulate -the value of @code{buffer-invisibility-spec} by hand. - -@item -The functions @code{face-documentation}, @code{face-bold-p}, -@code{face-italic-p}, @code{set-face-bold-p}, @code{set-face-italic-p} -are gone. Instead, use @code{make-face-bold} and friends. - -@item -All the functions that operate on a file now discard an extra redundant -directory name from the beginning of the file name---just like -@code{substitute-in-file-name}. - -@item -We have got rid of the function @code{access-file}. +The function @code{process-running-child-p} has been eliminated. @item -Most of the minibuffer input functions no longer take a default value as -an argument. Also, they do not discard text properties from the result. -This means that if you insert text with text properties into the minibuffer, -the minibuffer value really will contain text properties. +The function @code{interrupt-process} and similar functions no longer do +anything special when the second argument is @code{lambda}. @item -Only the simple menu item format is supported (@pxref{Simple Menu Items}). - -@item -You can still bind @code{x-resource-class} around a call to -@code{x-get-resource}, but it won't do anything special. - -@item -Wave goodbye to the hooks @code{before-make-frame-hook}, -@code{after-make-frame-functions}, and -@code{window-configuration-change-hook}, +The function @code{define-prefix-command} accepts only two arguments. @item -The functions and variables that deal with MS Windows NT/95 -have been renamed to start with @samp{win32-} instead of @samp{w32-}. -This is because we admire Microsoft more each day as we go back -into the past. -@end itemize - -@section Onward into the Past! - -Here we go even further back, as far as Emacs 19.29, for which the -previous printed edition of the Emacs Lisp manual was made. - -@itemize @bullet -@item -There are no char-tables or bool-vectors. Syntax tables, display -tables, and case tables are all vectors now, and the value of -@code{keyboard-translate-table} should be a vector or a string. +The meaning of the second argument to @code{read-char}, +@code{read-event}, and @code{read-char-exclusive} has been reversed: +they use the current input method if the argument is if @code{nil}. @item -There is only one kind of marker. When you insert text at the place -where a marker points, the marker always ends up before that text, -unless you use @code{insert-before-markers}, which puts all the markers -after the inserted text. +The function @code{with-temp-message} has been eliminated. @item -There is no function @code{overlays-in}. - -@item -The variable @code{print-length} applies only to lists, not to -vectors or strings. - -@item -The function @code{convert-standard-filename} no longer exists, so each -Lisp package must independently figure out which file names to use for -its initialization files on each kind of operating system. +The function @code{clear-this-command-keys} has been eliminated. @item -The macro @code{with-timeout} has been eliminated, along with the -function @code{y-or-n-p-with-timeout}. Idle timers don't exist at all; -instead, maybe you can use @code{post-command-idle-hook} to do some of -the same job. - -@item -The functions @code{keymap-parent} and @code{set-keymap-parent} are -gone. We expect keymaps to recognize their own parents. +The functions @code{gap-position} and @code{gap-size} have been eliminated. @item -When you delete text and then undo a deletion, markers that were -originally inside the deleted text end up either at the beginning -or the end of it---not back in their original places. - -@item -The interactive specification @samp{N} is gone now. - -@item -There is no more @code{safe-length}. Don't try to be so safe! Did you -expect to live forever? - -@item -We got rid of @code{insert-file-contents-literally}, because -programmers are too literal-minded anyway. +In @code{modify-face}, an argument of @code{(nil)} has no special +meaning. @item -As part of our continuing effort to help Lisp programmers to relax, we -threw out the function @code{error-message-string}. Don't worry so much -about errors! We all make mistakes. - -@item -The keymap @code{special-event-map} is gone, because Emacs has no more -special events. If you want to hold a party in Emacs, please let us -know. - -@item -You can't do date arithmetic with @code{encode-time} any more. +The base64 conversion functions have been eliminated. @item -The functions @code{command-execute} and @code{call-interactively} no -longer accept the optional argument @var{keys}. - -@item -@code{get-buffer-window-list} is gone as well. +Wildcard support has been eliminated from @code{find-file} +and allied functions. @item -With the function @code{replace-match}, you can only replace the whole -match, not a subexpression of it. - -@item -We eliminated the hooks @code{buffer-access-fontify-functions}, -@code{window-scroll-functions}, and @code{redisplay-end-trigger-functions}. +@code{file-attributes} returns the file size and the file inode number +only as a simple integer. @end itemize
--- a/lispref/backups.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/backups.texi Fri Sep 17 06:59:04 1999 +0000 @@ -179,6 +179,19 @@ non-@code{nil}. @end defvar +@defvar backup-by-copying-when-privileged-mismatch +This variable, if non-@code{nil}, specifies the same behavior as +@code{backup-by-copying-when-mismatch}, but only for certain user-id +values: namely, those less than or equal to a certain number. You set +this variable to that number. + +Thus, if you set @code{backup-by-copying-when-privileged-mismatch} +to 0, backup by copying is done for the superuser only, +when necessary to prevent a change in the owner of the file. + +The default is 200. +@end defvar + @node Numbered Backups @subsection Making and Deleting Numbered Backup Files @@ -393,8 +406,8 @@ @defun auto-save-file-name-p filename This function returns a non-@code{nil} value if @var{filename} is a -string that could be the name of an auto-save file. It works based on -knowledge of the naming convention for auto-save files: a name that +string that could be the name of an auto-save file. It assumes +the usual naming convention for auto-save files: a name that begins and ends with hash marks (@samp{#}) is a possible auto-save file name. The argument @var{filename} should not contain a directory part. @@ -433,8 +446,8 @@ This function returns the file name to use for auto-saving the current buffer. This is just the file name with hash marks (@samp{#}) prepended and appended to it. This function does not look at the variable -@code{auto-save-visited-file-name} (described below); you should check -that before calling this function. +@code{auto-save-visited-file-name} (described below); callers of this +function should check that variable first. @example @group @@ -475,10 +488,11 @@ auto-save files have distinct names that are created by @code{make-auto-save-file-name}. -When you change the value of this variable, the value does not take -effect until the next time auto-save mode is reenabled in any given -buffer. If auto-save mode is already enabled, auto-saves continue to go -in the same file name until @code{auto-save-mode} is called again. +When you change the value of this variable, the new value does not take +effect in an existing buffer until the next time auto-save mode is +reenabled in it. If auto-save mode is already enabled, auto-saves +continue to go in the same file name until @code{auto-save-mode} is +called again. @end defvar @defun recent-auto-save-p @@ -493,18 +507,18 @@ @end defun @defopt auto-save-interval -The value of this variable is the number of characters that Emacs -reads from the keyboard between auto-saves. Each time this many more -characters are read, auto-saving is done for all buffers in which it is +The value of this variable specifies how often to do auto-saving, in +terms of number of input events. Each time this many additional input +events are read, Emacs does auto-saving for all buffers in which that is enabled. @end defopt @defopt auto-save-timeout The value of this variable is the number of seconds of idle time that should cause auto-saving. Each time the user pauses for this long, -Emacs auto-saves any buffers that need it. (Actually, the specified -timeout is multiplied by a factor depending on the size of the current -buffer.) +Emacs does auto-saving for all buffers in which that is enabled. +(Actually, the specified timeout is multiplied by a factor depending on +the size of the current buffer.) @end defopt @defvar auto-save-hook @@ -552,14 +566,15 @@ @defvar buffer-saved-size The value of this buffer-local variable is the length of the current -buffer as of the last time it was read in, saved, or auto-saved. This is +buffer, when it was last read in, saved, or auto-saved. This is used to detect a substantial decrease in size, and turn off auto-saving in response. -If it is @minus{}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-saving. -Turning auto-save mode off or on also alters this variable. +If it is @minus{}1, that means auto-saving is temporarily shut off in +this buffer due to a substantial decrease in size. Explicitly saving +the buffer stores a positive value in this variable, thus reenabling +auto-saving. Turning auto-save mode off or on also updates this +variable, so that the substantial decrease in size is forgotten. @end defvar @defvar auto-save-list-file-name @@ -570,14 +585,14 @@ 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 +When 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. +this file to find them. -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 -name. +The default name for this file specifies your home directory and starts +with @samp{.saves-}. It also contains the Emacs process @sc{id} and the +host name. @end defvar @node Reverting @@ -594,10 +609,10 @@ or saved. By default, if the latest auto-save file is more recent than the visited -file, @code{revert-buffer} asks the user whether to use that instead. -But if the argument @var{ignore-auto} is non-@code{nil}, then only the -the visited file itself is used. Interactively, @var{ignore-auto} is -@code{t} unless there is a numeric prefix argument; thus, the +file, and the argument @var{ignore-auto} is non-@code{nil}, +@code{revert-buffer} asks the user whether to use that auto-save +instead. When you invoke this command interactively, @var{ignore-auto} +is @code{t} unless there is a numeric prefix argument; thus, the interactive default is to check the auto-save file. Normally, @code{revert-buffer} asks for confirmation before it changes @@ -608,9 +623,9 @@ replacement feature of @code{insert-file-contents}. If the buffer contents and the file contents are identical before the revert operation, reverting preserves all the markers. If they are not -identical, reverting does change the buffer; then it preserves the -markers in the unchanged text (if any) at the beginning and end of the -buffer. Preserving any additional markers would be problematical. +identical, reverting does change the buffer; in that case, it preserves +the markers in the unchanged text (if any) at the beginning and end of +the buffer. Preserving any additional markers would be problematical. @end deffn You can customize how @code{revert-buffer} does its work by setting @@ -618,10 +633,10 @@ @defvar revert-without-query This variable holds a list of files that should be reverted without -query. The value is a list of regular expressions. If a file name -matches one of these regular expressions, then @code{revert-buffer} -reverts the file without asking the user for confirmation, if the file -has changed on disk and the buffer is not modified. +query. The value is a list of regular expressions. If the visited file +name matches one of these regular expressions, and the file has changed +on disk but the buffer is not modified, then @code{revert-buffer} +reverts the file without asking the user for confirmation. @end defvar @defvar revert-buffer-function @@ -637,20 +652,20 @@ @end defvar @defvar revert-buffer-insert-file-contents-function -The value of this variable, if non-@code{nil}, is the function to use to +The value of this variable, if non-@code{nil}, specifies the function to use to 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 -This normal hook is run by @code{revert-buffer} before actually +This normal hook is run by @code{revert-buffer} before inserting the modified contents---but only if @code{revert-buffer-function} is @code{nil}. @end defvar @defvar after-revert-hook -This normal hook is run by @code{revert-buffer} after actually inserting +This normal hook is run by @code{revert-buffer} after inserting the modified contents---but only if @code{revert-buffer-function} is @code{nil}. @end defvar
--- a/lispref/buffers.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/buffers.texi Fri Sep 17 06:59:04 1999 +0000 @@ -10,7 +10,7 @@ A @dfn{buffer} is a Lisp object containing text to be edited. Buffers are used to hold the contents of files that are being visited; there may also be buffers that are not visiting files. While several buffers may -exist at one time, exactly one buffer is designated the @dfn{current +exist at one time, only one buffer is designated the @dfn{current buffer} at any time. Most editing commands act on the contents of the current buffer. Each buffer, including the current buffer, may or may not be displayed in any windows. @@ -18,7 +18,7 @@ @menu * Buffer Basics:: What is a buffer? * Current Buffer:: Designating a buffer as current - so primitives will access its contents. + so that primitives will access its contents. * Buffer Names:: Accessing and changing buffer names. * Buffer File Name:: The buffer file name indicates which file is visited. * Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. @@ -39,8 +39,8 @@ @ifinfo A @dfn{buffer} is a Lisp object containing text to be edited. Buffers are used to hold the contents of files that are being visited; there may -also be buffers that are not visiting files. While several buffers may -exist at one time, exactly one buffer is designated the @dfn{current +also be buffers that are not visiting files. Although several buffers +normally exist, only one buffer is designated the @dfn{current buffer} at any time. Most editing commands act on the contents of the current buffer. Each buffer, including the current buffer, may or may not be displayed in any windows. @@ -103,12 +103,12 @@ Emacs reads a command is the buffer that the command will apply to. (@xref{Command Loop}.) Therefore, @code{set-buffer} is not the way to switch visibly to a different buffer so that the user can edit it. For -this, you must use the functions described in @ref{Displaying Buffers}. +that, you must use the functions described in @ref{Displaying Buffers}. - However, Lisp functions that change to a different current buffer + @strong{Note:} Lisp functions that change to a different current buffer should not depend on the command loop to set it back afterwards. Editing commands written in Emacs Lisp can be called from other programs -as well as from the command loop. It is convenient for the caller if +as well as from the command loop; it is convenient for the caller if the subroutine does not change which buffer is current (unless, of course, that is the subroutine's purpose). Therefore, you should normally use @code{set-buffer} within a @code{save-current-buffer} or @@ -153,9 +153,9 @@ @code{save-excursion} to make sure that the buffer current at the beginning is current again whenever the variable is unbound. - It is not reliable to change the current buffer back with -@code{set-buffer}, because that won't do the job if a quit happens while -the wrong buffer is current. Here is what @emph{not} to do: + Do not rely on using @code{set-buffer} to change the current buffer +back, because that won't do the job if a quit happens while the wrong +buffer is current. Here is what @emph{not} to do: @example @group @@ -192,10 +192,9 @@ @end defun @defun set-buffer buffer-or-name -This function makes @var{buffer-or-name} the current buffer. It does -not display the buffer in the currently selected window or in any other -window, so the user cannot necessarily see the buffer. But Lisp -programs can in any case work on it. +This function makes @var{buffer-or-name} the current buffer. This does +not display the buffer in any window, so the user cannot necessarily see +the buffer. But Lisp programs will now operate on it. This function returns the buffer identified by @var{buffer-or-name}. An error is signaled if @var{buffer-or-name} does not identify an @@ -302,18 +301,15 @@ already in use. However, if @var{unique} is non-@code{nil}, it modifies @var{newname} to make a name that is not in use. Interactively, you can make @var{unique} non-@code{nil} with a numeric prefix argument. - -One application of this command is to rename the @samp{*shell*} buffer -to some other name, thus making it possible to create a second shell -buffer under the name @samp{*shell*}. +(This is how the command @code{rename-uniquely} is implemented.) @end deffn @defun get-buffer buffer-or-name This function returns the buffer specified by @var{buffer-or-name}. If @var{buffer-or-name} is a string and there is no buffer with that name, the value is @code{nil}. If @var{buffer-or-name} is a buffer, it -is returned as given. (That is not very useful, so the argument is usually -a name.) For example: +is returned as given; that is not very useful, so the argument is usually +a name. For example: @example @group @@ -374,7 +370,7 @@ @defvar buffer-file-name This buffer-local variable contains the name of the file being visited in the current buffer, or @code{nil} if it is not visiting a file. It -is a permanent local, unaffected by @code{kill-local-variables}. +is a permanent local variable, unaffected by @code{kill-local-variables}. @example @group @@ -621,7 +617,7 @@ @item Modes such as Dired and Rmail make buffers read-only when altering the -contents with the usual editing commands is probably a mistake. +contents with the usual editing commands would probably be a mistake. The special commands of these modes bind @code{buffer-read-only} to @code{nil} (with @code{let}) or bind @code{inhibit-read-only} to @@ -649,7 +645,7 @@ @deffn Command toggle-read-only This command changes whether the current buffer is read-only. It is -intended for interactive use; don't use it in programs. At any given +intended for interactive use; do not use it in programs. At any given point in a program, you should know whether you want the read-only flag on or off; so you can set @code{buffer-read-only} explicitly to the proper value, @code{t} or @code{nil}. @@ -857,8 +853,8 @@ The buffer object for the buffer that has been killed remains in existence as long as anything refers to it, but it is specially marked so that you cannot make it current or display it. Killed buffers retain -their identity, however; two distinct buffers, when killed, remain -distinct according to @code{eq}. +their identity, however; if you kill two distinct buffers, they remain +distinct according to @code{eq} although both are dead. If you kill a buffer that is current or displayed in a window, Emacs automatically selects or displays some other buffer instead. This means @@ -916,9 +912,9 @@ After confirming unsaved changes, @code{kill-buffer} calls the functions in the list @code{kill-buffer-query-functions}, in order of appearance, with no arguments. The buffer being killed is the current buffer when -they are called. The idea is that these functions ask for confirmation -from the user for various nonstandard reasons. If any of them returns -@code{nil}, @code{kill-buffer} spares the buffer's life. +they are called. The idea of this feature is that these functions will +ask for confirmation from the user. If any of them returns @code{nil}, +@code{kill-buffer} spares the buffer's life. @end defvar @defvar kill-buffer-hook @@ -951,7 +947,7 @@ in the other. This includes the text properties as well as the characters themselves. - But in all other respects, the indirect buffer and its base buffer are + In all other respects, the indirect buffer and its base buffer are completely separate. They have different names, different values of point, different narrowing, different markers and overlays (though inserting or deleting text in either buffer relocates the markers and @@ -959,8 +955,8 @@ variables. An indirect buffer cannot visit a file, but its base buffer can. If -you try to save the indirect buffer, that actually works by saving the -base buffer. +you try to save the indirect buffer, that actually saves the base +buffer. Killing an indirect buffer has no effect on its base buffer. Killing the base buffer effectively kills the indirect buffer in that it cannot
--- a/lispref/calendar.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/calendar.texi Fri Sep 17 06:59:04 1999 +0000 @@ -117,6 +117,10 @@ A similar normal hook, @code{today-invisible-calendar-hook} is run if the current date is @emph{not} visible in the window. +@vindex calendar-move-hook + Starting in Emacs 21, each of the calendar cursor motion commands +runs the hook @code{calendar-move-hook} after it moves the cursor. + @node Holiday Customizing @section Customizing the Holidays @@ -776,7 +780,7 @@ @noindent and the fancy diary will show @smallexample -Ruth & Ed's anniversary +Ed's anniversary @end smallexample @noindent both on December 15 and on December 22.
--- a/lispref/commands.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/commands.texi Fri Sep 17 06:59:04 1999 +0000 @@ -322,7 +322,7 @@ specification. If the key sequence that invoked the command has @var{n} events that are lists, the @var{n}th @samp{e} provides the @var{n}th such event. Events that are not lists, such as function keys -and @sc{ASCII} characters, do not count where @samp{e} is concerned. +and @sc{ascii} characters, do not count where @samp{e} is concerned. @item f A file name of an existing file (@pxref{File Names}). The default @@ -760,7 +760,7 @@ @end example @noindent -The value is 5 because that is the @sc{ASCII} code for @kbd{C-e}. +The value is 5 because that is the @sc{ascii} code for @kbd{C-e}. The alias @code{last-command-char} exists for compatibility with Emacs version 18. @@ -834,7 +834,7 @@ @item meta The @tex -$2^{27}$ +@math{2^{27}} @end tex @ifinfo 2**27 @@ -845,57 +845,57 @@ @item control The @tex -$2^{26}$ +@math{2^{26}} @end tex @ifinfo 2**26 @end ifinfo -bit in the character code indicates a non-@sc{ASCII} +bit in the character code indicates a non-@sc{ascii} control character. -@sc{ASCII} control characters such as @kbd{C-a} have special basic +@sc{ascii} control characters such as @kbd{C-a} have special basic codes of their own, so Emacs needs no special bit to indicate them. Thus, the code for @kbd{C-a} is just 1. -But if you type a control combination not in @sc{ASCII}, such as +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 @tex -$2^{26}$ +@math{2^{26}} @end tex @ifinfo 2**26 @end ifinfo -(assuming the terminal supports non-@sc{ASCII} +(assuming the terminal supports non-@sc{ascii} control characters). @item shift The @tex -$2^{25}$ +@math{2^{25}} @end tex @ifinfo 2**25 @end ifinfo -bit in the character code indicates an @sc{ASCII} control +bit in the character code indicates an @sc{ascii} control character typed with the shift key held down. For letters, the basic code itself 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 +@sc{ascii} character set whenever possible, Emacs avoids using the @tex -$2^{25}$ +@math{2^{25}} @end tex @ifinfo 2**25 @end ifinfo bit for those characters. -However, @sc{ASCII} provides no way to distinguish @kbd{C-A} from +However, @sc{ascii} provides no way to distinguish @kbd{C-A} from @kbd{C-a}, so Emacs uses the @tex -$2^{25}$ +@math{2^{25}} @end tex @ifinfo 2**25 @@ -906,7 +906,7 @@ @item hyper The @tex -$2^{24}$ +@math{2^{24}} @end tex @ifinfo 2**24 @@ -917,7 +917,7 @@ @item super The @tex -$2^{23}$ +@math{2^{23}} @end tex @ifinfo 2**23 @@ -928,7 +928,7 @@ @item alt The @tex -$2^{22}$ +@math{2^{22}} @end tex @ifinfo 2**22 @@ -966,10 +966,10 @@ @table @asis @item @code{backspace}, @code{tab}, @code{newline}, @code{return}, @code{delete} -These keys correspond to common @sc{ASCII} control characters that have +These keys correspond to common @sc{ascii} control characters that have special keys on most keyboards. -In @sc{ASCII}, @kbd{C-i} and @key{TAB} are the same character. If the +In @sc{ascii}, @kbd{C-i} and @key{TAB} are the same character. If the terminal can distinguish between them, Emacs conveys the distinction to Lisp programs by representing the former as the integer 9, and the latter as the symbol @code{tab}. @@ -981,7 +981,7 @@ symbols in this group. The function @code{read-char} likewise converts these events into characters. -In @sc{ASCII}, @key{BS} is really @kbd{C-h}. But @code{backspace} +In @sc{ascii}, @key{BS} is really @kbd{C-h}. But @code{backspace} converts into the character code 127 (@key{DEL}), not into code 8 (@key{BS}). This is what most users prefer. @@ -1657,7 +1657,7 @@ characters. Now the flag that represents the Meta modifier in a character is @tex -$2^{27}$ +@math{2^{27}} @end tex @ifinfo 2**27 @@ -1677,14 +1677,14 @@ @item The meta variants of those characters, with codes in the range of @tex -$2^{27}$ +@math{2^{27}} @end tex @ifinfo 2**27 @end ifinfo to @tex -$2^{27} + 127$, +@math{2^{27} + 127}, @end tex @ifinfo 2**27+127, @@ -1692,14 +1692,14 @@ can also go in the string, but you must change their numeric values. You must set the @tex -$2^{7}$ +@math{2^{7}} @end tex @ifinfo 2**7 @end ifinfo bit instead of the @tex -$2^{27}$ +@math{2^{27}} @end tex @ifinfo 2**27 @@ -1708,7 +1708,7 @@ can include these codes. @item -Non-@sc{ASCII} characters above 256 can be included in a multibyte string. +Non-@sc{ascii} characters above 256 can be included in a multibyte string. @item Other keyboard character events cannot fit in a string. This includes @@ -1869,7 +1869,7 @@ If @var{inherit-input-method} is non-@code{nil}, then the current input method (if any) is employed to make it possible to enter a -non-@sc{ASCII} character. Otherwise, input method handling is disabled +non-@sc{ascii} character. Otherwise, input method handling is disabled for reading this event. If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event} @@ -1899,7 +1899,7 @@ function key event), @code{read-char} signals an error. The arguments work as in @code{read-event}. -In the first example, the user types the character @kbd{1} (@sc{ASCII} +In the first example, the user types the character @kbd{1} (@sc{ascii} code 49). The second example shows a keyboard macro definition that calls @code{read-char} from the minibuffer using @code{eval-expression}. @code{read-char} reads the keyboard macro's very next character, which @@ -2078,7 +2078,7 @@ 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}, +@sc{ascii} code 49. It becomes the value of @code{last-input-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}. @@ -2171,12 +2171,8 @@ @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 -all if input is available before it starts. Thus, there is no way to -force screen updating if there is pending input; however, if there is no -input pending, you can force an update with no delay by using -@code{(sit-for 0)}. +The expression @code{(sit-for 0)} is a convenient way to request a +redisplay, without any delay. @xref{Forcing Redisplay}. If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not redisplay, but it still returns as soon as input is available (or when
--- a/lispref/control.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/control.texi Fri Sep 17 06:59:04 1999 +0000 @@ -20,8 +20,8 @@ level in a file of Lisp code---the forms are executed in the order written. We call this @dfn{textual order}. For example, if a function body consists of two forms @var{a} and @var{b}, evaluation of the -function evaluates first @var{a} and then @var{b}, and the function's -value is the value of @var{b}. +function evaluates first @var{a} and then @var{b}. The result of +evaluating @var{b} becomes the value of the function. Explicit control structures make possible an order of execution other than sequential. @@ -60,9 +60,9 @@ @noindent and it says to execute the forms @var{a}, @var{b}, @var{c}, and so on, in -that order. These forms are called the body of the @code{progn} form. +that order. These forms are called the @dfn{body} of the @code{progn} form. The value of the last form in the body becomes the value of the entire -@code{progn}. +@code{progn}. @code{(progn)} returns @code{nil}. @cindex implicit @code{progn} In the early days of Lisp, @code{progn} was the only way to execute @@ -72,8 +72,8 @@ the body of a function was made into an ``implicit @code{progn}'': several forms are allowed just as in the body of an actual @code{progn}. Many other control structures likewise contain an implicit @code{progn}. -As a result, @code{progn} is not used as often as it used to be. It is -needed now most often inside an @code{unwind-protect}, @code{and}, +As a result, @code{progn} is not used as much as it was many years ago. +It is needed now most often inside an @code{unwind-protect}, @code{and}, @code{or}, or in the @var{then}-part of an @code{if}. @defspec progn forms@dots{} @@ -265,6 +265,7 @@ @example @group +(setq a 5) (cond ((eq a 'hack) 'foo) (t "default")) @result{} "default" @@ -272,8 +273,8 @@ @end example @noindent -This expression is a @code{cond} which returns @code{foo} if the value -of @code{a} is @code{hack}, and returns the string @code{"default"} otherwise. +This @code{cond} expression returns @code{foo} if the value of @code{a} +is @code{hack}, and returns the string @code{"default"} otherwise. @end defspec Any conditional construct can be expressed with @code{cond} or with @@ -310,11 +311,14 @@ If any of the @var{conditions} evaluates to @code{nil}, then the result of the @code{and} must be @code{nil} regardless of the remaining -@var{conditions}; so @code{and} returns right away, ignoring the -remaining @var{conditions}. +@var{conditions}; so @code{and} returns @code{nil} right away, ignoring +the remaining @var{conditions}. If all the @var{conditions} turn out non-@code{nil}, then the value of -the last of them becomes the value of the @code{and} form. +the last of them becomes the value of the @code{and} form. Just +@code{(and)}, with no @var{conditions}, returns @code{t}, appropriate +because all the @var{conditions} turned out non-@code{nil}. (Think +about it; which one did not?) Here is an example. The first condition returns the integer 1, which is not @code{nil}. Similarly, the second condition returns the integer 2, @@ -368,10 +372,13 @@ returns is the non-@code{nil} value of the condition just evaluated. If all the @var{conditions} turn out @code{nil}, then the @code{or} -expression returns @code{nil}. +expression returns @code{nil}. Just @code{(or)}, with no +@var{conditions}, returns @code{nil}, appropriate because all the +@var{conditions} turned out @code{nil}. (Think about it; which one +did not?) -For example, this expression tests whether @code{x} is either 0 or -@code{nil}: +For example, this expression tests whether @code{x} is either +@code{nil} or the integer zero: @example (or (eq x nil) (eq x 0)) @@ -446,9 +453,10 @@ @end group @end example -If you would like to execute something on each iteration before the -end-test, put it together with the end-test in a @code{progn} as the -first argument of @code{while}, as shown here: +To write a ``repeat...until'' loop, which will execute something on each +iteration and then do the end-test, put the body followed by the +end-test in a @code{progn} as the first argument of @code{while}, as +shown here: @example @group @@ -560,9 +568,10 @@ error or nonlocal exit) the value of the last body form is returned from the @code{catch}. -If a @code{throw} is done within @var{body} specifying the same value -@var{tag}, the @code{catch} exits immediately; the value it returns is -whatever was specified as the second argument of @code{throw}. +If a @code{throw} is executed during the execution of @var{body}, +specifying the same value @var{tag}, the @code{catch} form exits +immediately; the value it returns is whatever was specified as the +second argument of @code{throw}. @end defspec @defun throw tag value @@ -641,13 +650,6 @@ @example @group -(defun catch2 (tag) - (catch tag - (throw 'hack 'yes))) -@result{} catch2 -@end group - -@group (catch 'hack (print (catch2 'quux)) 'no) @@ -709,6 +711,11 @@ considered an error, but it is handled almost like an error. @xref{Quitting}. + The error message should state what is wrong (``File does not +exist''), not how things ought to be (``File must exist''). The +convention in Emacs Lisp is that error messages should start with a +capital letter, but should not end with any sort of punctuation. + @defun error format-string &rest args This function signals an error with an error message constructed by applying @code{format} (@pxref{String Conversion}) to @@ -852,7 +859,7 @@ The search for an applicable handler checks all the established handlers starting with the most recently established one. Thus, if two nested @code{condition-case} forms offer to handle the same error, the inner of -the two will actually handle it. +the two gets to handle it. If an error is handled by some @code{condition-case} form, this ordinarily prevents the debugger from being run, even if @@ -881,10 +888,11 @@ read from the user. Error signaling and handling have some resemblance to @code{throw} and -@code{catch}, but they are entirely separate facilities. An error -cannot be caught by a @code{catch}, and a @code{throw} cannot be handled -by an error handler (though using @code{throw} when there is no suitable -@code{catch} signals an error that can be handled). +@code{catch} (@pxref{Catch and Throw}), but they are entirely separate +facilities. An error cannot be caught by a @code{catch}, and a +@code{throw} cannot be handled by an error handler (though using +@code{throw} when there is no suitable @code{catch} signals an error +that can be handled). @defspec condition-case var protected-form handlers@dots{} This special form establishes the error handlers @var{handlers} around @@ -1127,9 +1135,9 @@ @var{cleanup-forms}. If the @var{body} forms do not finish, @code{unwind-protect} does not return any value in the normal sense. -Only the @var{body} is actually protected by the @code{unwind-protect}. -If any of the @var{cleanup-forms} themselves exits nonlocally (e.g., via -a @code{throw} or an error), @code{unwind-protect} is @emph{not} +Only the @var{body} is protected by the @code{unwind-protect}. If any +of the @var{cleanup-forms} themselves exits nonlocally (via a +@code{throw} or an error), @code{unwind-protect} is @emph{not} guaranteed to evaluate the rest of them. If the failure of one of the @var{cleanup-forms} has the potential to cause trouble, then protect it with another @code{unwind-protect} around that form. @@ -1167,13 +1175,13 @@ in this way. @findex ftp-login - Here is an actual example taken from the file @file{ftp.el}. It -creates a process (@pxref{Processes}) to try to establish a connection -to a remote machine. As the function @code{ftp-login} is highly -susceptible to numerous problems that the writer of the function cannot -anticipate, it is protected with a form that guarantees deletion of the -process in the event of failure. Otherwise, Emacs might fill up with -useless subprocesses. + Here is an actual example derived from an FTP package. It creates a +process (@pxref{Processes}) to try to establish a connection to a remote +machine. As the function @code{ftp-login} is highly susceptible to +numerous problems that the writer of the function cannot anticipate, it +is protected with a form that guarantees deletion of the process in the +event of failure. Otherwise, Emacs might fill up with useless +subprocesses. @smallexample @group @@ -1188,7 +1196,7 @@ @end group @end smallexample - This example actually has a small bug: if the user types @kbd{C-g} to + This example has a small bug: if the user types @kbd{C-g} to quit, and the quit happens immediately after the function @code{ftp-setup-buffer} returns but before the variable @code{process} is set, the process will not be killed. There is no easy way to fix this bug,
--- a/lispref/customize.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/customize.texi Fri Sep 17 06:59:04 1999 +0000 @@ -19,7 +19,7 @@ @end menu @node Common Keywords -@section Common Keywords for All Kinds of Items +@section Common Item Keywords All kinds of customization declarations (for variables and groups, and for faces) accept keyword arguments for specifying various information. @@ -31,8 +31,8 @@ display one name. @table @code -@item :tag @var{name} -Use @var{name}, a string, instead of the item's name, to label the item +@item :tag @var{label} +Use @var{label}, a string, instead of the item's name, to label the item in customization menus and buffers. @item :group @var{group} @@ -42,7 +42,7 @@ If you use this keyword more than once, you can put a single item into more than one group. Displaying any of those groups will show this -item. Be careful not to overdo this! +item. Please don't overdo this, since the result would be annoying. @item :link @var{link-data} Include an external link after the documentation string for this item. @@ -113,7 +113,8 @@ @tindex defgroup Declare @var{group} as a customization group containing @var{members}. Do not quote the symbol @var{group}. The argument @var{doc} specifies -the documentation string for the group. +the documentation string for the group. It should not start with a +@samp{*} as in @code{defcustom}; that convention is for variables only. The argument @var{members} is a list specifying an initial set of customization items to be members of the group. However, most often @@ -165,12 +166,20 @@ @tindex defcustom Declare @var{option} as a customizable user option variable. Do not quote @var{option}. The argument @var{doc} specifies the documentation -string for the variable. +string for the variable; it should normally start with a @samp{*}. This +marks the variable, for other purposes, as one that users may want to +customize. If @var{option} is void, @code{defcustom} initializes it to @var{default}. @var{default} should be an expression to compute the value; be careful in writing it, because it can be evaluated on more than one occasion. + +When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp +mode (@code{eval-defun}), a special feature of @code{eval-defun} +arranges to set the variable unconditionally, without testing whether +its value is void. (The same feature applies to @code{defvar}.) +@xref{Defining Variables}. @end defmac @code{defcustom} accepts the following additional keywords: @@ -277,7 +286,8 @@ definition. You can do it thus: @example -(custom-add-option 'emacs-lisp-mode-hook 'my-lisp-mode-initialization) +(custom-add-option 'emacs-lisp-mode-hook + 'my-lisp-mode-initialization) @end example @defun custom-add-option symbol option @@ -392,10 +402,9 @@ You can specify the key and value types like this: -@example -(alist :key-type @var{key-type} - :value-type @var{value-type}) -@end example +@smallexample +(alist :key-type @var{key-type} :value-type @var{value-type}) +@end smallexample @noindent where @var{key-type} and @var{value-type} are customization type @@ -414,9 +423,9 @@ specifications. Ordinarily, the options are simply atoms, which are the specified keys. For example: -@example +@smallexample :options '("foo" "bar" "baz") -@end example +@end smallexample @noindent specifies that there are three ``known'' keys, namely @code{"foo"}, @@ -428,9 +437,9 @@ specification. The first element will specify the key, like before, while the second element will specify the value type. -@example +@smallexample :options '("foo" ("bar" integer) "baz") -@end example +@end smallexample Finally, you may want to change how the key is presented. By default, the key is simply shown as a @code{const}, since the user cannot change @@ -440,36 +449,36 @@ This is done by using a customization type specification instead of a symbol for the key. -@example +@smallexample :options '("foo" ((function-item some-function) integer) "baz") -@end example +@end smallexample Many alists use lists with two elements, instead of cons cells. For example, -@example +@smallexample (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3)) "Each element is a list of the form (KEY VALUE).") -@end example +@end smallexample @noindent instead of -@example +@smallexample (defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3)) "Each element is a cons-cell (KEY . VALUE).") -@end example +@end smallexample Because of the way lists are implemented on top of cons cells, you can treat @code{list-alist} in the example above as a cons cell alist, where the value type is a list with a single element containing the real value. -@example +@smallexample (defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3)) "Each element is a list of the form (KEY VALUE)." :type '(alist :value-type (group integer))) -@end example +@end smallexample The @code{group} widget is used here instead of @code{list} only because the formatting is better suited for the purpose. @@ -477,7 +486,7 @@ Similarily, you can have alists with more values associated with each key, using variations of this trick: -@example +@smallexample (defcustom person-data '(("brian" 50 t) ("dorith" 55 nil) ("ken" 52 t)) @@ -489,16 +498,16 @@ ("ken" "cat")) "Alist where the KEY is a person, and the VALUE is a list of pets." :type '(alist :value-type (repeat string))) -@end example +@end smallexample @item plist The @code{plist} custom type is similar to the @code{alist} (see above), except that the information is stored as a property list, i.e. a list of this form: -@example +@smallexample (@var{key} @var{value} @var{key} @var{value} @var{key} @var{value} @dots{}) -@end example +@end smallexample The default @code{:key-type} for @code{plist} is @code{symbol}, rather than @code{sexp}.
--- a/lispref/debugging.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/debugging.texi Fri Sep 17 06:59:04 1999 +0000 @@ -510,9 +510,9 @@ @defvar debugger The value of this variable is the function to call to invoke the -debugger. Its value must be a function of any number of arguments (or, -more typically, the name of a function). Presumably this function will -enter some kind of debugger. The default value of the variable is +debugger. Its value must be a function of any number of arguments, or, +more typically, the name of a function. This function should invoke +some kind of debugger. The default value of the variable is @code{debug}. The first argument that Lisp hands to the function indicates why it @@ -531,11 +531,13 @@ In the following example, a Lisp expression calls @code{backtrace} explicitly. This prints the backtrace to the stream -@code{standard-output}: in this case, to the buffer -@samp{backtrace-output}. Each line of the backtrace represents one -function call. The line shows the values of the function's arguments if -they are all known. If they are still being computed, the line says so. -The arguments of special forms are elided. +@code{standard-output}, which, in this case, is the buffer +@samp{backtrace-output}. + +Each line of the backtrace represents one function call. The line shows +the values of the function's arguments if they are all known; if they +are still being computed, the line says so. The arguments of special +forms are elided. @smallexample @group @@ -620,9 +622,9 @@ information for future debugger invocations during the same command invocation. -The advantage, for the debugger, of using this variable rather than an -ordinary global variable is that the data will never carry over to a -subsequent command invocation. +The advantage of using this variable rather than an ordinary global +variable is that the data will never carry over to a subsequent command +invocation. @end defvar @defun backtrace-frame frame-number @@ -630,11 +632,11 @@ debuggers. It returns information about what computation is happening in the stack frame @var{frame-number} levels down. -If that frame has not evaluated the arguments yet (or is a special -form), the value is @code{(nil @var{function} @var{arg-forms}@dots{})}. +If that frame has not evaluated the arguments yet, or is a special +form, the value is @code{(nil @var{function} @var{arg-forms}@dots{})}. If that frame has evaluated its arguments and called its function -already, the value is @code{(t @var{function} +already, the return value is @code{(t @var{function} @var{arg-values}@dots{})}. In the return value, @var{function} is whatever was supplied as the @@ -679,12 +681,9 @@ @subsection Excess Open Parentheses The first step is to find the defun that is unbalanced. If there is -an excess open parenthesis, the way to do this is to insert a -close parenthesis at the end of the file and type @kbd{C-M-b} -(@code{backward-sexp}). This will move you to the beginning of the -defun that is unbalanced. (Then type @kbd{C-@key{SPC} C-_ C-u -C-@key{SPC}} to set the mark there, undo the insertion of the -close parenthesis, and finally return to the mark.) +an excess open parenthesis, the way to do this is to go to the end of +the file and type @kbd{C-u C-M-u}. This will move you to the beginning +of the defun that is unbalanced. The next step is to determine precisely what is wrong. There is no way to be sure of this except by studying the program, but often the @@ -715,11 +714,9 @@ @node Excess Close @subsection Excess Close Parentheses - To deal with an excess close parenthesis, first insert an open -parenthesis at the beginning of the file, back up over it, and type -@kbd{C-M-f} to find the end of the unbalanced defun. (Then type -@kbd{C-@key{SPC} C-_ C-u C-@key{SPC}} to set the mark there, undo the -insertion of the open parenthesis, and finally return to the mark.) + To deal with an excess close parenthesis, first go to the beginning of +the file, then type @kbd{C-u -1 C-M-u} to find the end of the unbalanced +defun. Then find the actual matching close parenthesis by typing @kbd{C-M-f} at the beginning of that defun. This will leave you somewhere short of
--- a/lispref/display.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/display.texi Fri Sep 17 06:59:04 1999 +0000 @@ -11,6 +11,7 @@ @menu * Refresh Screen:: Clearing the screen and redrawing everything on it. +* Forcing Redisplay:: Forcing redisplay. * Truncation:: Folding or wrapping long text lines. * The Echo Area:: Where messages are displayed. * Invisible Text:: Hiding part of the buffer text. @@ -20,6 +21,8 @@ * Overlays:: Use overlays to highlight parts of the buffer. * Width:: How wide is a character or string. * Faces:: A face defines a graphics appearance: font, color, etc. +* Display Property:: Enabling special display features. +* Images:: Displaying images in Emacs buffers. * Blinking:: How Emacs shows the matching open parenthesis. * Inverse Video:: Specifying how the screen looks. * Usual Display:: The usual conventions for displaying nonprinting chars. @@ -64,6 +67,32 @@ to redraw, @code{nil} means redrawing is needed. The default is @code{nil}. @end defvar +@node Forcing Redisplay +@section Forcing Redisplay +@cindex forcing redisplay + + Emacs redisplay normally stops if input arrives, and does not happen +at all if input is available before it starts. Most of the time, this +is exactly what you want. However, you can prevent preemption by +binding @code{redisplay-dont-pause} to a non-@code{nil} value. + +@tindex redisplay-dont-pause +@defvar redisplay-dont-pause +If this variable is non-@code{nil}, pending input does not +prevent or halt redisplay; redisplay occurs, and finishes, +regardless of whether input is available. This feature is available +as of Emacs 21. +@end defvar + + You can request a display update, but only if no input is pending, +with @code{(sit-for 0)}. To force a display update even when input is +pending, do this: + +@example +(let ((redisplay-dont-pause t)) + (sit-for 0)) +@end example + @node Truncation @section Truncation @cindex line wrapping @@ -158,10 +187,14 @@ In batch mode, @code{message} prints the message text on the standard error stream, followed by a newline. +If @var{string}, or strings among the @var{arguments}, have @code{face} +text properties, these affect the way the message is displayed. + @c Emacs 19 feature -If @var{string} is @code{nil}, @code{message} clears the echo area. If -the minibuffer is active, this brings the minibuffer contents back onto -the screen immediately. +If @var{string} is @code{nil}, @code{message} clears the echo area; if +the echo area has been expanded automatically, this brings it back to +its normal size. If the minibuffer is active, this brings the +minibuffer contents back onto the screen immediately. @example @group @@ -682,7 +715,7 @@ @node Overlay Properties @subsection Overlay Properties -Overlay properties are like text properties in that the properties that + Overlay properties are like text properties in that the properties that alter how a character is displayed can come from either source. But in most respects they are different. Text properties are considered a part of the text; overlays are specifically considered not to be part of the @@ -693,6 +726,29 @@ changes, overlay changes are not recorded in the buffer's undo list. @xref{Text Properties}, for comparison. + These functions are used for reading and writing the properties of an +overlay: + +@defun overlay-get overlay prop +This function returns the value of property @var{prop} recorded in +@var{overlay}, if any. If @var{overlay} does not record any value for +that property, but it does have a @code{category} property which is a +symbol, that symbol's @var{prop} property is used. Otherwise, the value +is @code{nil}. +@end defun + +@defun overlay-put overlay prop value +This function sets the value of property @var{prop} recorded in +@var{overlay} to @var{value}. It returns @var{value}. +@end defun + + See also the function @code{get-char-property} which checks both +overlay properties and text properties for a given character. +@xref{Examining Properties}. + + Many overlay properties have special meanings; here is a table +of them: + @table @code @item priority @kindex priority @r{(overlay property)} @@ -721,20 +777,51 @@ @item face @kindex face @r{(overlay property)} This property controls the way text is displayed---for example, which -font and which colors. Its value is a face name or a list of face -names. @xref{Faces}, for more information. - -If the property value is a list, elements may also have the form -@code{(foreground-color . @var{color-name})} or @code{(background-color -. @var{color-name})}. These elements specify just the foreground color -or just the background color; therefore, there is no need to create a -face for each color that you want to use. +font and which colors. @xref{Faces}, for more information. + +In the simplest case, the value is a face name. It can also be a list; +then each element can be any of these possibilities; + +@itemize @bullet +@item +A face name (a symbol or string). + +@item +Starting in Emacs 21, a property list of face attributes. This has the +form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a +face attribute name and @var{value} is a meaningful value for that +attribute. With this feature, you do not need to create a face each +time you want to specify a particular attribute for certain text. +@xref{Face Attributes}. + +@item +A cons cell of the form @code{(foreground-color . @var{color-name})} or +@code{(background-color . @var{color-name})}. These elements specify +just the foreground color or just the background color. + +@code{(foreground-color . @var{color-name})} is equivalent to +@code{(:foreground @var{color-name})}, and likewise for the background. +@end itemize @item mouse-face @kindex mouse-face @r{(overlay property)} This property is used instead of @code{face} when the mouse is within the range of the overlay. +@item display +@kindex display @r{(overlay property)} +This property activates various features that change the +way text is displayed. For example, it can make text appear taller +or shorter, higher or lower, wider or narror, or replaced with an image. +@xref{Display Property}. + +@item help-echo +@kindex help-echo @r{(text property)} +If an overlay has a string as its @code{help-echo} property, then when +you move the mouse onto the text in the overlay, Emacs displays that +string in the echo area, or in the tooltip window. It is available +starting in Emacs 21. + @item modification-hooks @kindex modification-hooks @r{(overlay property)} This property's value is a list of functions to be called if any @@ -818,26 +905,6 @@ the character after point is within the overlay. @xref{Active Keymaps}. @end table - These are the functions for reading and writing the properties of an -overlay. - -@defun overlay-get overlay prop -This function returns the value of property @var{prop} recorded in -@var{overlay}, if any. If @var{overlay} does not record any value for -that property, but it does have a @code{category} property which is a -symbol, that symbol's @var{prop} property is used. Otherwise, the value -is @code{nil}. -@end defun - -@defun overlay-put overlay prop value -This function sets the value of property @var{prop} recorded in -@var{overlay} to @var{value}. It returns @var{value}. -@end defun - - See also the function @code{get-char-property} which checks both -overlay properties and text properties for a given character. -@xref{Examining Properties}. - @node Managing Overlays @subsection Managing Overlays @@ -974,13 +1041,14 @@ @section Faces @cindex face -A @dfn{face} is a named collection of graphical attributes: font, -foreground color, background color, and optional underlining. Faces -control the display of text on the screen. + A @dfn{face} is a named collection of graphical attributes: font +family, foreground color, background color, optional underlining, and +many others. Faces are used in Emacs to control the style of display of +particular parts of the text or the frame. @cindex face id Each face has its own @dfn{face number}, which distinguishes faces at -low levels within Emacs. However, for most purposes, you can refer to +low levels within Emacs. However, for most purposes, you refer to faces in Lisp programs by their names. @defun facep object @@ -996,23 +1064,56 @@ @menu * Standard Faces:: The faces Emacs normally comes with. * Defining Faces:: How to define a face with @code{defface}. -* Merging Faces:: How Emacs decides which face to use for a character. +* Face Attributes:: What is in a face? +* Attribute Functions:: Functions to examine and set face attributes. +* Merging Faces:: How Emacs combines the faces specified for a character. +* Font Selection:: Finding the best available font for a face. * Face Functions:: How to define and examine faces. +* Auto Faces:: Hook for automatic face assignment. +* Font Lookup:: Looking up the names of available fonts + and information about them. +* Fontsets:: A fontset is a collection of fonts + that handle a range of character sets. @end menu @node Standard Faces @subsection Standard Faces - This table lists all the standard faces and their uses. + This table lists all the standard faces and their uses. Most of them +are used for displaying certain parts of the frames or certain kinds of +text; you can control how those places look by customizing these faces. @table @code @item default @kindex default @r{(face name)} This face is used for ordinary text. +@item mode-line +@kindex mode-line @r{(face name)} +This face is used for mode lines, and for menu bars +when toolkit menus are not used. + @item modeline @kindex modeline @r{(face name)} -This face is used for mode lines and menu bars. +This is an alias for the @code{mode-line} face, for compatibility with +old Emacs versions. + +@item header-line +@kindex header-line @r{(face name)} +This face is used for the header lines of windows that have them. + +@item fringe +@kindex fringe @r{(face name)} +This face controls the colors of window fringes, the thin areas on +either side that are used to display continuation and truncation glyphs. + +@item scroll-bar +@kindex scroll-bar @r{(face name)} +This face controls the colors for display of scroll bars. + +@item tool-bar +@kindex tool-bar @r{(face name)} +This face is used for display of the tool bar, if any. @item region @kindex region @r{(face name)} @@ -1026,10 +1127,16 @@ @kindex highlight @r{(face name)} This face is meant to be used for highlighting for various purposes. -@item underline -@kindex underline @r{(face name)} -This face underlines text. - +@item trailing-whitespace +@kindex trailing-whitespace @r{(face name)} +This face is used to display excess whitespace at the end of a line. +@end table + + In contrast, these faces are provided to change the appearance of text +in specific ways. You can use them on specific text, when you want +the effects they produce. + +@table @code @item bold @kindex bold @r{(face name)} This face uses a bold font, if possible. It uses the bold variant of @@ -1044,6 +1151,20 @@ @kindex bold-italic @r{(face name)} This face uses the bold italic variant of the frame's font, if it has one. + +@item underline +@kindex underline @r{(face name)} +This face underlines text. + +@item fixed-patch +@kindex fixed-patch @r{(face name)} +This face forces use of a particular fixed-width font. + +@item variable-patch +@kindex variable-patch @r{(face name)} +This face forces use of a particular variable-width font. It's +reasonable to customize this to use a diffrent variable-width font, if +you like, but you should not make it a fixed-width font. @end table @node Defining Faces @@ -1139,32 +1260,352 @@ as if they had a light background. @end defopt +@node Face Attributes +@subsection Face Attributes +@cindex face attributes + + The effect of using a face is determined by a fixed set of @dfn{face +attributes}. This table lists all the face attributes, and what they +mean. Note that in general, more than one face be specified for a given +piece of text; when that happens, the attributes of all the faces are +merged to specify how to display the text. @xref{Merging Faces}. + + In Emacs 21, any attribute in a face can have the value +@code{unspecified}. This means the face doesn't specify that attribute. +In face merging, when the first face fails to specify a particular +attribute, that means the next face gets a chance. However, the +@code{default} face must specify all attributes. + + Some of these font attributes are meaningful only on certain +kinds of displays---if your display cannot handle a certain attribute, +the attribute is ignored. + +@table @code +@item :family +Font family name, or fontset name (@pxref{Fontsets}). If you specify a +font family name, the wild-cards @samp{*} and @samp{?} are allowed. + +@item :width +Relative proportionate width, also known as the character set width or +set width. This should be one of the symbols @code{ultra-condensed}, +@code{extra-condensed}, @code{condensed}, @code{semi-condensed}, +@code{normal}, @code{semi-expanded}, @code{expanded}, +@code{extra-expanded}, or @code{ultra-expanded}. + +@item :height +Font height, an integer in units of 1/10pt. + +@item :weight +Font weight---a symbol from this series (from most dense to most faint): +@code{ultra-bold}, @code{extra-bold}, @code{bold}, @code{semi-bold}, +@code{normal}, @code{semi-light}, @code{light}, @code{extra-light}, +@code{ultra-light}, or else @code{nil} meaning this attribute is not +specified. + +@item :slant +Font slant---one of the symbols @code{italic}, @code{oblique}, @code{normal}, +@code{reverse-italic}, or @code{reverse-oblique}. + +@item :foreground +Foreground color, a string. + +@item :background +Background color, a string. + +@item :inverse-video +Whether or not characters should be displayed in inverse video. The +value should be @code{t} (yes) or @code{nil} (no). + +@item :stipple +The background stipple, a bitmap name. + +The value can be a string; then is the name of a file of pixmap data. +The file is found in the directories listed in the variable +@code{x-bitmap-file-path}. + +Alternatively, the value can be a list of the form @code{(@var{width} +@var{height} @var{data})}. Here, width and height are the size in +pixels, and @var{data} is a string containing the raw bits of the +bitmap. + +If the value is @code{nil}, that means use no stipple pattern. + +Normally you do not need to set the stipple attribute, because it is +used automatically to handle certain shades of gray. + +@item :underline +Whether or not characters should be underlined, and in what color. If +the value is @code{t}, underlining uses the foreground color of the +face. If the value is a string, underlining uses that color. The +value @code{nil} means do not underline. + +@item :overline +Whether or not characters should be overlined, and in what color. +The value is used like that of @code{:underline}. + +@item :strike-through +Whether or not characters should be strike-through, and in what +color. The value is used like that of @code{:underline}. + +@item :box +Whether or not a box should be drawn around characters, its color, the +width of the box lines, and 3D appearance. See below for the possible +values and what they mean. +@end table + + Here are the possible values of the @code{:box} attribute, and what +they mean: + +@table @asis +@item @code{nil} +Don't draw a box. + +@item @code{t} +Draw a box with lines of width 1, in the foreground color. + +@item @var{color} +Draw a box with lines of width 1, in color @var{color}. + +@item @code{(:line-width @var{width} :color @var{color} :style @var{style})} +This way you can explicitly specify all aspects of the box. The value +@var{width} specifies the width of the lines to draw; it defaults to 1. + +The value @var{color} specifies the color to draw with. The default is +the foreground color of the face for simple boxes, and the background +color of the face for 3D boxes. + +The value @var{style} specifies whether to draw a 3D box. If it is +@code{released-button}, the box looks like a 3D button that is not being +pressed. If it is @code{pressed-button}, the box looks like a 3D button +that is being pressed. If it is @code{nil} or omitted, a plain 2D box +is used. +@end table + + The attributes @code{:overline}, @code{:strike-through} and +@code{:box} are new in Emacs 21. The attributes @code{:family}, +@code{:height}, @code{:width}, @code{:weight}, @code{:slant} are also +new, previous versions had another way to specify some of the same +information. + +@table @code +@item :font +This attribute specified the font name. + +@item :bold +A non-@code{nil} value specifies a bold font. + +@item :italic +A non-@code{nil} value specifies an italic font. +@end table + + For compatibility, you can still set these ``attributes'' in Emacs 21, +even though they are not real face attributes. Here is what that does: + +@table @code +@item :font +@code{:font} is not really a font attribute, but you can use it in +@code{set-face-attribute} to specify several attributes at once. You +specify an X font name as the value, and based on this font name, and +it sets the attributes @code{:family}, @code{:width}, @code{:height}, +@code{:weight}, and @code{:slant} according to the font name. + +If the value is a pattern with wildcards, the first font that matches +the pattern is used to set these attributes. + +@item :bold +A non-@code{nil} makes the face bold; @code{nil} makes it normal. +This actually works by setting the @code{:weight} attribute. + +@item :italic +A non-@code{nil} makes the face italic; @code{nil} makes it normal. +This actually works by setting the @code{:slant} attribute. +@end table + +@defvar x-bitmap-file-path +This variable specifies a list of directories for searching +for bitmap files, for the @code{:stipple} attribute. +@end defvar + +@node Attribute Functions +@subsection Face Attribute Functions + + You can modify the attributes of an existing face with the following +functions. If you specify @var{frame}, they affect just that frame; +otherwise, they affect all frames as well as the defaults that apply to +new frames. + +@tindex set-face-attribute +@defun set-face-attribute face frame &rest arguments +This function sets one or more attributes of face @var{face} +for frame @var{frame}. If @var{frame} is @code{nil}, it sets +the attribute for all frames, and the defaults for new frames. + +The extra arguments @var{arguments} specify the attributes to set, and +the values for them. They should consist of alternating attribute names +(such as @code{:family} or @code{:underline} and corresponding values. +Thus, + +@example +(set-face-attribute 'foo nil + :width :extended + :weight :bold + :underline "red") +@end example + +@noindent +sets the attributes @code{:width}, @code{:weight} and @code{:underline} +to the corresponding values. +@end defun + +@tindex face-attribute +@defun face-attribute face attribute &optional frame +This returns the value of the @var{attribute} attribute of face +@var{face} on @var{frame}. If @var{frame} is @code{nil}, +that means the selected frame. + +If @var{frame} is @code{t}, the value is the default for +@var{face} for new frames. + +For example, + +@example +(face-attribute 'bold :weight) + @result{} bold +@end example +@end defun + + For older Emacs versions, you can these functions to set +and examine the face attributes which existed in those versions. + +@defun set-face-foreground face color &optional frame +@defunx set-face-background face color &optional frame +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 +This function sets the font of face @var{face}. + +In Emacs 21, this actually sets the attributes @code{:family}, +@code{:width}, @code{:height}, @code{:weight}, and @code{:slant} +according to the font name @var{font}. + +In Emacs 20, this sets the font attribute. Once you set the font +explicitly, the bold and italic attributes cease to have any effect, +because the precise font that you specified is used. +@end defun + +@defun set-face-bold-p face bold-p &optional frame +@tindex set-face-bold-p +This function specifies whether @var{face} should be bold. If +@var{bold-p} is non-@code{nil}, that means yes; @code{nil} means no. + +In Emacs 21, this sets the @code{:weight} attribute. +In Emacs 20, it sets the @code{:bold} attribute. +@end defun + +@defun set-face-italic-p face italic-p &optional frame +@tindex set-face-italic-p +This function specifies whether @var{face} should be italic. If +@var{italic-p} is non-@code{nil}, that means yes; @code{nil} means no. + +In Emacs 21, this sets the @code{:slant} attribute. +In Emacs 20, it sets the @code{:italic} attribute. +@end defun + +@defun set-face-underline-p face underline-p &optional frame +This function sets the underline attribute of face @var{face}. +Non-@code{nil} means do underline; @code{nil} means don't. +@end defun + +@defun invert-face face &optional frame +This function inverts the @code{:inverse-video} attribute of face +@var{face}. If the attribute is @code{nil}, this function sets it to +@code{t}, and vice versa. +@end defun + + These functions examine the attributes of a face. If you don't +specify @var{frame}, they refer to the default data for new frames. + +@defun face-foreground face &optional frame +@defunx face-background face &optional frame +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 + +@defun face-bold-p face &optional frame +@tindex face-bold-p +This function returns @code{t} if @var{face} is bold---that is, if it is +bolder than normal. It returns @code{nil} otherwise. +@end defun + +@defun face-italic-p face &optional frame +@tindex face-italic-p +This function returns @code{t} if @var{face} is italic or oblique, +@code{nil} otherwise. +@end defun + +@defun face-underline-p face &optional frame +This function returns the @code{:underline} attribute of face @var{face}. +@end defun + +@defun face-inverse-video-p face &optional frame +This function returns the @code{:inverse-video} attribute of face @var{face}. +@end defun + @node Merging Faces @subsection Merging Faces for Display - Here are all the ways to specify which face to use for display of text: + Here are the ways to specify which faces to use for display of text: @itemize @bullet @item -With defaults. Each frame has a @dfn{default face}, which is used for -all text that doesn't somehow specify another face. (We may change this -in a forthcoming Emacs version to serve as a default for all text.) +With defaults. The @code{default} face is used as the ultimate +default for all text. (In Emacs 19 and 20, the @code{default} +face is used only when no other face is specified.) + +For a mode line or header line, the face @code{modeline} or +@code{header-line} is used just before @code{default}. @item -With text properties. A character may have a @code{face} property; if so, -it is displayed with that face. @xref{Special Properties}. +With text properties. A character can have a @code{face} property; if +so, the faces and face attributes specified there apply. @xref{Special +Properties}. If the character has a @code{mouse-face} property, that is used instead of the @code{face} property when the mouse is ``near enough'' to the character. @item -With overlays. An overlay may have @code{face} and @code{mouse-face} +With overlays. An overlay can 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). +highlighted with the face @code{region} (@pxref{Standard Faces}). @item With special glyphs. Each glyph can specify a particular face @@ -1181,17 +1622,132 @@ When multiple overlays cover one character, an overlay with higher priority overrides those with lower priority. @xref{Overlays}. - If an attribute such as the font or a color is not specified in any of -the above ways, the frame's own font or color is used. + In Emacs 20, if an attribute such as the font or a color is not +specified in any of the above ways, the frame's own font or color is +used. In newer Emacs versions, this cannot happen, because the +@code{default} face specifies all attributes---in fact, the frame's own +font and colors are synonymous with those of the default face. + +@node Font Selection +@subsection Font Selection + + @dfn{Selecting a font} means mapping the specified face attributes for +a character to a font that is available on a particular display. The +face attributes, as determined by face merging, specify most of the +font choice, but not all. Part of the choice depends on what character +it is. + + For multibyte characters, typically each font covers only one +character set. So each character set (@pxref{Character Sets}) specifies +a registry and encoding to use, with the character set's +@code{x-charset-registry} property. Its value is a string containing +the registry and the encoding, with a dash between them: + +@example +(plist-get (charset-plist 'latin-iso8859-1) + 'x-charset-registry) + @result{} "ISO8859-1" +@end example + + Unibyte text does not have character sets, so displaying a unibyte +character takes the registry and encoding from the variable +@code{face-default-registry}. + +@defvar face-default-registry +This variable specifies which registry and encoding to use in choosing +fonts for unibyte characters. The value is initialized at Emacs startup +time from the font the user specified for Emacs. +@end defvar + + If the face specifies a fontset name, that fontset determines a +pattern for fonts of the given charset. If the face specifies a font +family, a font pattern is constructed. + + Emacs tries to find an available font for the given face attributes +and character's registry and encoding. If there is a font that matches +exactly, it is used, of course. The hard case is when no available font +exactly fits the specification. Then Emacs looks for one that is +``close''---one attribute at a time. You can specify the order +to consider the attributes. + +@defvar face-font-selection-order +@tindex face-font-selection-order +This variable specifies the order of importance of the face attributes +@code{:width}, @code{:height}, @code{:weight}, and @code{:slant}. The +value should be a list containing those four symbols, in order of +decreasing importance. + +Font selection first finds the best available matches for the first +attribute listed; then, among the fonts which are best in that way, it +searches for the best matches in the second attribute, and so on. + +The attributes @code{:weight} and @code{:width} have symbolic values in +a range centered around @code{normal}. Matches that are more extreme +(farther from @code{normal}) are somewhat preferred to matches that are +less extreme (closer to @code{normal}); this is designed to ensure that +non-normal faces contrast with normal ones, whenever possible. + +The default is @code{(:width :height :weight :slant)}, which means first +find the fonts closest to the specified @code{:width}, then---among the +fonts with that width---find a best match for the specified font height, +and so on. + +One example of a case where this variable makes a difference is when the +default font has no italic equivalent. With the default ordering, the +@code{italic} face will use a non-italic font that is similar to the +default one. But if you put @code{:slant} before @code{:height}, the +@code{italic} face will use an italic font, even if its height is not +quite right. +@end defvar + +@defvar face-alternative-font-family-alist +@tindex face-alternative-font-family-alist +This variable lets you specify alternative font families to try, if a +given family is specified and doesn't exist. Each element should have +this form: + +@example +(@var{family} @var{alternate-families}@dots{}) +@end example + +If @var{family} is specified but not available, Emacs will try the other +families given in @var{alternate-families}, one by one, until it finds a +family that does exist. +@end defvar + + Emacs can make use of scalable fonts, but by default it does not use +them, since the use of too many or too big scalable fonts can crash +XFree86 servers. + +@defvar scalable-fonts-allowed +@tindex scalable-fonts-allowed +This variable controls which scalable fonts to use. A value of +@code{nil}, the default, means do not use scalable fonts. @code{t} +means to use any scalable font that seems appropriate for the text. + +Otherwise, the value must be a list of regular expressions. Then a +scalable font is enabled for use if its name matches any regular +expression in the list. For example, + +@example +(setq scalable-fonts-allowed '("muleindian-2$")) +@end example + +@noindent +allows the use of scalable fonts with registry @code{muleindian-2}. +@end example + +@defun clear-face-cache &optional unload-p +@tindex clear-face-cache +This function clears the face cache for all frames. +If @var{unload-p} is non-@code{nil}, that means to unload +all unused fonts as well. +@end defun @node Face Functions @subsection Functions for Working with Faces - The attributes a face can specify include the font, the foreground -color, the background color, and underlining. The face can also leave -these unspecified by giving the value @code{nil} for them. - - Here are the primitives for creating and changing faces. + Here are additional functions for creating and working with faces. @defun make-face name This function defines a new face named @var{name}, initially with all @@ -1218,95 +1774,6 @@ in @var{new-frame}. @end defun - You can modify the attributes of an existing face with the following -functions. If you specify @var{frame}, they affect just that frame; -otherwise, they affect all frames as well as the defaults that apply to -new frames. - -@defun set-face-foreground face color &optional frame -@defunx set-face-background face color &optional frame -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 -This function sets the font of face @var{face}. The argument @var{font} -should be a string, either a valid font name for your system or the name -of an Emacs fontset (@pxref{Fontsets}). Note that if you set the font -explicitly, the bold and italic attributes cease to have any effect, -because the precise font that you specified is always used. -@end defun - -@defun set-face-bold-p face bold-p &optional frame -@tindex set-face-bold-p -This function sets the bold attribute of face @var{face}. -Non-@code{nil} means bold; @code{nil} means non-bold. -@end defun - -@defun set-face-italic-p face italic-p &optional frame -@tindex set-face-italic-p -This function sets the italic attribute of face @var{face}. -Non-@code{nil} means italic; @code{nil} means non-italic. -@end defun - -@defun set-face-underline-p face underline-p &optional frame -This function sets the underline attribute of face @var{face}. -Non-@code{nil} means do underline; @code{nil} means don't. -@end defun - -@defun invert-face face &optional frame -Swap the foreground and background colors of face @var{face}. If the -face doesn't specify both foreground and background, then its foreground -and background are set to the default background and foreground, -respectively. -@end defun - - These functions examine the attributes of a face. If you don't -specify @var{frame}, they refer to the default data for new frames. - -@defun face-foreground face &optional frame -@defunx face-background face &optional frame -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 - -@defun face-bold-p face &optional frame -@tindex face-bold-p -This function returns the bold attribute of face @var{face}. -@end defun - -@defun face-italic-p face &optional frame -@tindex face-italic-p -This function returns the italic attribute of face @var{face}. -@end defun - -@defun face-underline-p face &optional frame -This function returns the underline attribute of face @var{face}. -@end defun - @defun face-id face This function returns the face number of face @var{face}. @end defun @@ -1329,22 +1796,801 @@ @code{nil} (meaning to inherit from the default). @end defun -@defvar region-face -This variable's value specifies the face number to use to display characters -in the region when it is active (in Transient Mark mode only). The face -thus specified takes precedence over all faces that come from text -properties and overlays, for characters in the region. @xref{The Mark}, -for more information about Transient Mark mode. - -Normally, the value is the face number of the face named @code{region}. -@end defvar - @tindex frame-update-face-colors @defun frame-update-face-colors frame This function updates the way faces display on @var{frame}, for a change in @var{frame}'s foreground or background color. @end defun +@node Auto Faces +@subsection Automatic Face Assignment +@cindex automatic face assignment +@cindex faces, automatic choice + +@cindex Font-Lock mode + Starting with Emacs 21, a hook is available for automatically +assigning faces to text in the buffer. This hook is used for part of +the implementation of Font-Lock mode. + +@tindex fontification-functions +@defvar fontification-functions +This variable holds a list of functions that are called by Emacs +redisplay as needed to assign faces automatically to text in the buffer. + +The functions are called in the order listed, with one argument, a +buffer position @var{pos}. Each function should attempt to assign faces +to the text in the current buffer starting at @var{pos}. + +Each function should record the faces they assign by setting the +@code{face} property. It should also add a non-@code{nil} +@code{fontified} property for all the text it has assigned faces to. +That property tells redisplay that faces have been assigned to that text +already. + +It is probably a good idea for each function to do nothing if the +character after @var{pos} already has a non-@code{nil} @code{fontified} +property, but this is not required. If one function overrides the +assignments made by a previous one, the properties as they are +after the last function finishes are the ones that really matter. + +For efficiency, we recommend writing these functions so that they +usually assign faces to around 400 to 600 characters at each call. +@end defvar + +@node Font Lookup +@subsection Looking Up Fonts + +@defun x-list-fonts pattern &optional face frame maximum +This function returns a list of available font names that match +@var{pattern}. If the optional arguments @var{face} and @var{frame} are +specified, then the list is limited to fonts that are the same size as +@var{face} currently is on @var{frame}. + +The argument @var{pattern} should be a string, perhaps with wildcard +characters: the @samp{*} character matches any substring, and the +@samp{?} character matches any single character. Pattern matching +of font names ignores case. + +If you specify @var{face} and @var{frame}, @var{face} should be a face name +(a symbol) and @var{frame} should be a frame. + +The optional argument @var{maximum} sets a limit on how many fonts to +return. If this is non-@code{nil}, then the return value is truncated +after the first @var{maximum} matching fonts. Specifying a small value +for @var{maximum} can make this function much faster, in cases where +many fonts match the pattern. +@end defun + + These additional functions are available starting in Emacs 21. + +@defun x-family-fonts &optional family frame +@tindex x-family-fonts +This function returns a list describing the available fonts for family +@var{family} on @var{frame}. If @var{family} is omitted or @code{nil}, +this list applies to all families, and therefore, it contains all +available fonts. Otherwise, @var{family} must be a string; it may +contain the wildcards @samp{?} and @samp{*}. + +The list describes the display that @var{frame} is on; if @var{frame} is +omitted or @code{nil}, it applies to the selected frame's display. + +The list contains a vector of the following form for each font: + +@example +[@var{family} @var{width} @var{point-size} @var{weight} @var{slant} + @var{fixed-p} @var{full} @var{registry-and-encoding}] +@end example + +The first five elements correspond to face attributes; if you +specify these attributes for a face, it will use this font. + +The last three elements give additional information about the font. +@var{fixed-p} is non-nil if the font is fixed-pitch. @var{full} is the +full name of the font, and @var{registry-and-encoding} is a string +giving the registry and encoding of the font. + +The result list is sorted according to the current face font sort order. +@end defun + +@defun x-font-family-list &optional frame +@tindex x-font-family-list +This function returns a list of the font families available for +@var{frame}'s display. If @var{frame} is omitted or @code{nil}, it +describes the selected frame's display. + +The value is a list of elements of this form: + +@example +(@var{family} . @var{fixed-p}) +@end example + +@noindent +Here @var{family} is a font family, and @var{fixed-p} is +non-@code{nil} if fonts of that family are fixed-pitch. +@end defun + +@defvar font-list-limit +@tindex font-list-limit +This variable specifies maximum number of fonts to consider in font +matching. The function @code{x-family-fonts} will not return more than +that many fonts, and font selection will consider only that many fonts +when searching a matching font for face attributes. The default is +currently 100. +@end defvar + +@node Fontsets +@subsection Fontsets + + A @dfn{fontset} is a list of fonts, each assigned to a range of +character codes. An individual font cannot display the whole range of +characters that Emacs supports, but a fontset can. Fontsets have names, +just as fonts do, and you can use a fontset name in place of a font name +when you specify the ``font'' for a frame or a face. Here is +information about defining a fontset under Lisp program control. + +@defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror +This function defines a new fontset according to the specification +string @var{fontset-spec}. The string should have this format: + +@smallexample +@var{fontpattern}, @r{[}@var{charsetname}:@var{fontname}@r{]@dots{}} +@end smallexample + +@noindent +Whitespace characters before and after the commas are ignored. + +The first part of the string, @var{fontpattern}, should have the form of +a standard X font name, except that the last two fields should be +@samp{fontset-@var{alias}}. + +The new fontset has two names, one long and one short. The long name is +@var{fontpattern} in its entirety. The short name is +@samp{fontset-@var{alias}}. You can refer to the fontset by either +name. If a fontset with the same name already exists, an error is +signaled, unless @var{noerror} is non-@code{nil}, in which case this +function does nothing. + +If optional argument @var{style-variant-p} is non-@code{nil}, that says +to create bold, italic and bold-italic variants of the fontset as well. +These variant fontsets do not have a short name, only a long one, which +is made by altering @var{fontpattern} to indicate the bold or italic +status. + +The specification string also says which fonts to use in the fontset. +See below for the details. +@end defun + + The construct @samp{@var{charset}:@var{font}} specifies which font to +use (in this fontset) for one particular character set. Here, +@var{charset} is the name of a character set, and @var{font} is the font +to use for that character set. You can use this construct any number of +times in the specification string. + + For the remaining character sets, those that you don't specify +explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces +@samp{fontset-@var{alias}} with a value that names one character set. +For the @sc{ascii} character set, @samp{fontset-@var{alias}} is replaced +with @samp{ISO8859-1}. + + In addition, when several consecutive fields are wildcards, Emacs +collapses them into a single wildcard. This is to prevent use of +auto-scaled fonts. Fonts made by scaling larger fonts are not usable +for editing, and scaling a smaller font is not useful because it is +better to use the smaller font in its own size, which Emacs does. + + Thus if @var{fontpattern} is this, + +@example +-*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24 +@end example + +@noindent +the font specification for ASCII characters would be this: + +@example +-*-fixed-medium-r-normal-*-24-*-ISO8859-1 +@end example + +@noindent +and the font specification for Chinese GB2312 characters would be this: + +@example +-*-fixed-medium-r-normal-*-24-*-gb2312*-* +@end example + + You may not have any Chinese font matching the above font +specification. Most X distributions include only Chinese fonts that +have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In +such a case, @samp{Fontset-@var{n}} can be specified as below: + +@smallexample +Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\ + chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-* +@end smallexample + +@noindent +Then, the font specifications for all but Chinese GB2312 characters have +@samp{fixed} in the @var{family} field, and the font specification for +Chinese GB2312 characters has a wild card @samp{*} in the @var{family} +field. + +@node Display Property +@section The @code{display} Property +@cindex display specification +@kindex display @r{(text property)} + + The @code{display} text property is used to insert images into text, +and also control other aspects of how text displays. These features are +available starting in Emacs 21. The value of the @code{display} +property should be a display specification, or a list or vector +containing several display specifications. The rest of this section +describes several kinds of display specifications and what they mean. + +@menu +* Specified Space:: +* Other Display Specs:: +* Display Margins:: +* Conditional Display:: +@end menu + +@node Specified Space +@subsection Specified Spaces +@cindex spaces, specified height or width +@cindex specified spaces +@cindex variable-width spaces + + To display a space of specified width and/or height, use a display +specification of the form @code{(space @var{props})}, where @var{props} +is a property list (see below). You can put this property on one or +more consecutive characters; a space of the specified height and width +is displayed in place of @emph{all} of those characters. + +@table @code +@item :width @var{width} +Specifies that the space width should be @var{width} times the normal +character width. @var{width} can be an integer or floating point +number. + +@item :relative-width @var{factor} +Specifies that the width of the stretch should be computed from the +first character in the group of consecutive characters that have the +same @code{display} property. The space width is the width of that +character, multiplied by @var{factor}. + +@item :align-to @var{hpos} +Specifies that the space should be wide enough to reach @var{hpos}. The +value @var{hpos} is measured in units of the normal character width. +@end table + + Exactly one of the above properties should be used. You can also +specify the height of the space, with other properties: + +@table @code +@item :height @var{height} +Specifies the height of the space, as @var{height}, +measured in terms of the normal line height. + +@item :relative-height @var{factor} +Specifies the height of the space, multiplying the ordinary height +of the text having this display specification by @var{factor}. + +@item :ascent @var{ascent} +Specifies that @var{ascent} percent of the height of the space should be +considered as the ascent of the space. The value of @var{ascent} must +be a non-negative number no greater than 100. +@end table + + You should not use both @code{:height} and @code{:relative-height} +together. + +@node Other Display Specs +@subsection Other Display Specifications + +@table @code +@item (image . @var{image-props}) +This is in fact an image descriptor (@pxref{Images}). When used as a +display specification, it means to display the image instead of the text +that has the display specification. + +@item (space-width @var{factor}) +This display specification affects all the spaces in the text that has +the specification. It displays all of these spaces @var{factor} times +as wide as normal. The element @var{factor} should be an integer or +float. + +@item (height @var{height}) +This display specification makes the text taller or shorter. +Here are the possibilities for @var{height}: + +@table @asis +@item @code{(+ @var{n})} +This means to use a font that is @var{n} steps larger. A ``step'' is +defined by the set of available fonts; each size for which a font is +available counts as a step. @var{n} should be an integer. + +@item @code{(- @var{n})} +This means to use a font that is @var{n} steps smaller. + +@item a number, @var{factor} +A number, @var{factor}, means to use a font that is @var{factor} times +as tall as the default font. + +@item a symbol, @var{function} +A symbol is a function to compute the height. It is called with the +current height as argument, and should return the new height to use. + +@item anything else, @var{form} +If the @var{height} value doesn't fit the previous possibilities, it is +a form. Emacs evaluates it to get the new height, with the symbol +@code{height} bound to the current specified font height. +@end table + +@item (raise @var{factor}) +This kind of display specification raises or lowers the text +it applies to, relative to the baseline of the line. + +@var{factor} must be a number, which is interpreted as a multiple of the +height of the affected text. If it is positive, that means to display +the characters raised. If it is negative, that means to display them +lower down. + +If the text also has a @code{height} display specification, that does +not affect the amount of raising or lowering, which is based on the +faces used for the text. +@end table + +@node Display Margins +@subsection Displaying in the Margins +@cindex display margins +@cindex margins, display + + A buffer can have blank areas called @dfn{display margins} on the left +and on the right. Ordinary text never appears in these areas, but you +can put things into the display margins using the @code{display} +property. + + To put text in the left or right display margin of the window, use a +display specification of the form @code{(margin right-margin)} or +@code{(margin left-margin)} on it. To put an image in a display margin, +use that display specification along with the display specification for +the image. + + Before the display margins can display anything, you must give +them a nonzero width. The usual way to do that is to set these +variables: + +@defvar left-margin-width +@tindex left-margin-width +This variable specifies the width of the left margin. +It is buffer-local in all buffers. +@end defvar + +@defvar right-margin-width +@tindex right-margin-width +This variable specifies the width of the right margin. +It is buffer-local in all buffers. +@end defvar + + Setting these variables does not immediately affect the window. These +variables are checked when a new buffer is displayed in the window. +Thus, you can make changes take effect by calling +@code{set-window-buffer}. + + You can also set the margin widths immediately. + +@defun set-window-margins window left right +@tindex set-window-margins +This function specifies the margin widths for window @var{window}. +The argument @var{left} controls the left margin and +@var{right} controls the right margin. +@end defun + +@defun window-margins &optional window +@tindex window-margins +This function returns the left and right margins of @var{window} +as a cons cell of the form @code{(@var{left} . @var{right})}. +If @var{window} is @code{nil}, the selected window is used. +@end defun + +@node Conditional Display +@subsection Conditional Display Specifications +@cindex conditional display specifications + + You can make any display specification conditional. To do that, +package it in another list of the form @code{(when @var{condition} +@var{spec})}. Then the specification @var{spec} applies only when +@var{condition} evaluates to a non-@code{nil} value. During the +evaluation, point is temporarily set at the end position of the text +having this conditional display specification. + +@node Images +@section Images +@cindex images in buffers + + To display an image in an Emacs buffer, you must first create an image +descriptor, then use it as a display specifier in the @code{display} +property of text that is displayed (@pxref{Display Property}). Like the +@code{display} property, this feature is available starting in Emacs 21. + + Emacs can display a number of different image formats; some of them +are supported only if particular support libraries are installed on your +machine. The supported image formats include XBM, XPM (needing the +libraries @code{libXpm} version 3.4k and @code{libz}), GIF (needing +@code{libungif} 4.1.0), Postscript, PBM, JPEG (needing the +@code{libjpeg} library version v6a), TIFF (needing @code{libtiff} v3.4), +and PNG (needing @code{libpng} 1.0.2). + + You specify one of these formats with an image type symbol. The image +type symbols are @code{xbm}, @code{xpm}, @code{gif}, @code{postscript}, +@code{pbm}, @code{jpeg}, @code{tiff}, and @code{png}. + +@defvar image-types +This variable contains a list of those image type symbols that are +supported in the current configuration. +@end defvar + +@menu +* Image Descriptors:: +* XBM Images:: +* XPM Images:: +* GIF Images:: +* Postscript Images:: +* Other Image Types:: +* Defining Images:: +* Showing Images:: +* Image Cache:: +@end menu + +@node Image Descriptors +@subsection Image Descriptors +@cindex image descriptor + + An image description is a list of the form @code{(image +. @var{props})}, where @var{props} is a property list containing +alternating keyword symbols (symbols whose names start with a colon) and +their values. Every image descriptor must contain the property +@code{:type @var{type}} to specify the format of the image. The value +of @var{type} should be an image type symbol; for example, @code{xpm} +for an image in XPM format. + + Here is a list of other properties that are meaningful for all image +types: + +@table @code +@item :ascent @var{ascent} +The @code{:ascent} property specifies the percentage of the image's +height to use for its ascent---that is, the part above the baseline. The +value, @var{ascent}, must be a number in the range 0 to 100. If this +property is omitted, it defaults to 50. + +@item :margin @var{margin} +The @code{:margin} property specifies how many pixels to add as an extra +margin around the image. The value, @var{margin}, must be a +non-negative number; if it is not specified, the default is zero. + +@item :relief @var{relief} +The @code{:relief} property, if non-@code{nil}, adds a shadow rectangle +around the image. The value, @var{relief}, specifies the width of the +shadow lines, in pixels. If @var{relief} is negative, shadows are drawn +so that the image appears as a pressed button; otherwise, it appears as +an unpressed button. + +@item :algorithm @var{algorithm} +The @code{:algorithm} property, if non-@code{nil}, specifies a +conversion algorithm that should be applied to the image before it is +displayed; the value, @var{algorithm}, specifies which algorithm. + +Currently, the only meaningful value for @var{algorithm} (aside from +@code{nil}) is @code{laplace}; this applies the Laplace edge detection +algorithm, which blurs out small differences in color while highlighting +larger differences. People sometimes consider this useful for +displaying the image for a ``disabled'' button. + +@item :heuristic-mask @var{transparent-color} +The @code{:heuristic-mask} property, if non-@code{nil}, specifies that a +certain color in the image should be transparent. Each pixel where this +color appears will actually allow the frame's background to show +through. + +If @var{transparent-color} is @code{t}, then determine the transparent +color by looking at the four corners of the image. This uses the color +that occurs most frequently near the corners as the transparent color. + +Otherwise, @var{heuristic-mask} should specify the transparent color +directly, as a list of three integers in the form @code{(@var{red} +@var{green} @var{blue})}. + +@item :file @var{file} +The @code{:file} property specifies to load the image from file +@var{file}. If @var{file} is not an absolute file name, it is expanded +in @code{data-directory}. + +@item :data @var{data} +The @code{:data} property specifies the actual contents of the image. +Each image must use either @code{:data} or @code{:file}, but not both. +However, only certain image types support @code{:data}; for other types, +you must use @code{:file}. + +The formats that support @code{:data} include XBM and XPM. +Before using @code{:data}, see the section describing the specific +format you wish to use for further information. +@end table + +@node XBM Images +@subsection XBM Images +@cindex XBM + + To use XBM format, specify @code{xbm} as the image type. This image +format doesn't require an external library, so images of this type are +always supported. + + Additional image properties supported for the @code{xbm} image type are: + +@table @code +@item :foreground @var{foreground} +The value, @var{foreground}, should be a string specifying the image +foreground color. This color is used for each pixel in the XBM that is +1. The default is the frame's foreground color. + +@item :background @var{background} +The value, @var{background}, should be a string specifying the image +background color. This color is used for each pixel in the XBM that is +0. The default is the frame's background color. +@end table + + You can specify an XBM image using data within Emacs instead +of an external file. To do this, don't use @code{:file}; instead, +use the following three properties (all of them): + +@table @code +@item :width @var{width} +The value, @var{width}, specifies the width the image in pixels. + +@item :height @var{height} +The value, @var{height}, specifies the height of the image in pixels. + +@item :data @var{data} +The value, @var{data}, is normally a string or a bool-vector. Either +way, it must contain enough bits for the area of the image: at least +@var{width} * @code{height}. + +Alternatively, @var{data} can be a vector of strings or bool-vectors, +each specifying one line of the image. +@end table + +@node XPM Images +@subsection XPM Images +@cindex XPM + + To use XPM format, specify @code{xpm} as the image type. These +additional image properties are meaningful with the @code{xpm} image +type: + +@table @code +@item :color-symbols @var{symbols} +The value, @var{symbols}, should be an alist whose elements have the +form @code{(@var{name} . @var{color})}. In each element, @var{name} is +the name of a color as it appears in the image file, and @var{color} +specifies the actual color to use for displaying that name. + +@item :data @var{data} +XPM images can be displayed from data instead of files. In that case, +use the @code{:data} property instead of the @code{:file} property. + +The value @var{data} must be a string containing an XPM image. The +contents of the string have same format as an external XPM file. +@end table + +@node GIF Images +@subsection GIF Images +@cindex GIF + + For GIF images, specify image type @code{gif}. Because of the patents +in the US covering the LZW algorithm, the continued use of GIF format is +a problem for the whole Internet; to end this problem, it is a good idea +for everyone, even outside the US, to stop using GIFS right away +(@uref{http://www.burnallgifs.org/}). But if you still want to use +them, Emacs can display them. + +@table @code +@item :index @var{index} +You can use @code{:index} to specify one image from a GIF file that +contains more than one image. This property specifies use of image +number @var{index} from the file. An error is signaled if the GIF file +doesn't contain an image with index @var{index}. +@end table + +@ignore +This could be used to implement limited support for animated GIFs. +For example, the following function displays a multi-image GIF file +at point-min in the current buffer, switching between sub-images +every 0.1 seconds. + +(defun show-anim (file max) + "Display multi-image GIF file FILE which contains MAX subimages." + (display-anim (current-buffer) file 0 max t)) + +(defun display-anim (buffer file idx max first-time) + (when (= idx max) + (setq idx 0)) + (let ((img (create-image file nil :image idx))) + (save-excursion + (set-buffer buffer) + (goto-char (point-min)) + (unless first-time (delete-char 1)) + (insert-image img)) + (run-with-timer 0.1 nil 'display-anim buffer file (1+ idx) max nil))) +@end ignore + +@node Postscript Images +@subsection Postscript Images +@cindex Postscript images + + To use Postscript for an image, specify image type @code{postscript}. +This works only if you have Ghostscript installed. You must always use +these three properties: + +@table @code +@item :pt-width @var{width} +The value, @var{width}, specifies the width of the image measured in +points (1/72 inch). @var{width} must be an integer. + +@item :pt-height @var{height} +The value, @var{height}, specifies the height of the image in points +(1/72 inch). @var{height} must be an integer. + +@item :bounding-box @var{box} +The value, @var{box}, must be a list or vector of four integers, which +specifying the bounding box of the Postscript image, analogous to the +@samp{BoundingBox} comment found in Postscript files. + +@example +%%BoundingBox: 22 171 567 738 +@end example +@end table + +@node Other Image Types +@subsection Other Image Types +@cindex PBM + + For PBM images, specify image type @code{pbm}. Color, gray-scale and +monochromatic images are supported. + + For JPEG images, specify image type @code{jpeg}. There are no +additional image properties defined. + + For TIFF images, specify image type @code{tiff}. + + For PNG images, specify image type @code{png}. + +@node Defining Images +@subsection Defining Images + + The functions @code{create-image} and @code{defimage} provide +convenient ways to create image descriptors. + +@defun create-image file &optional type &rest props +@tindex create-image +This function creates and returns an image descriptor which uses the +data in @var{file}. + +The optional argument @var{type} is a symbol specifying the image type. +If @var{type} is omitted or @code{nil}, @code{create-image} tries to +determine the image type from the file's first few bytes, or else +from the file's name. + +The remaining arguments, @var{props}, specify additional image +properties---for example, + +@example +(create-image "foo.xpm" 'xpm :heuristic-mask t) +@end example + +The function returns @code{nil} if images of this type are not +supported. Otherwise it returns an image descriptor. +@end defun + +@defmac defimage variable doc &rest specs +@tindex defimage +This macro defines @var{variable} as an image name. The second argument, +@var{doc}, is an optional documentation string. The remaining +arguments, @var{specs}, specify alternative ways to display the image. + +Each argument in @var{specs} has the form of a property list, and each +one should specify at least the @code{:type} property and the +@code{:file} property. Here is an example: + +@smallexample +(defimage test-image ((:type xpm :file \"~/test1.xpm\") + (:type xbm :file \"~/test1.xbm\")))" +@end smallexample + +@code{defimage} tests each argument, one by one, to see if it is +usable---that is, if the type is supported and the file exists. The +first usable argument is used to make an image descriptor which is +stored in the variable @var{variable}. + +If none of the alternatives will work, then @var{variable} is defined +as @code{nil}. +@end defmac + +@node Showing Images +@subsection Showing Images + + You can use an image descriptor by setting up the @code{display} +property yourself, but it is easier to use the functions in this +section. + +@defun insert-image image &optional area +This function inserts @var{image} in the current buffer at point. The +value @var{image} should be an image descriptor; it could be a value +returned by @code{create-image}, or the value of a symbol defined with +@code{defimage}. + +The argument @var{area} specifies whether to put the image in a margin. +If it is @code{left-margin}, the image appears in the left margin; +@code{right-margin} specifies the right margin. If @var{area} is +@code{nil} or omitted, the image is displayed at point within the +buffer's text. + +Internally, this function inserts an @samp{x} in the buffer, and gives +it a @code{display} property which specifies this image. @xref{Display +Property}. +@end defun + +@defun put-image image pos &optional area +This function puts image @var{image} in front of @var{pos} in the +current buffer. The argument @var{pos} should be an integer or a +marker. It specifies the buffer position where the image should appear. + +The argument @var{image} must be an image descriptor, perhaps returned +by @code{create-image} or stored by @code{defimage}. + +The argument @var{area} specifies whether to put the image in a margin. +If it is @code{left-margin}, the image appears in the left margin; +@code{right-margin} specifies the right margin. If @var{area} is +@code{nil} or omitted, the image is displayed at point within the +buffer's text. + +Internally, this function creates an overlay, and gives it a +@code{before-string} property containing text that has a @code{display} +property whose value is the image. (Whew!) +@end defun + +@defun remove-images start end &optional buffer +This function removes images in @var{buffer} between positions +@var{start} and @var{end}. If @var{buffer} is omitted or @code{nil}, +images are removed from the current buffer. + +This remove only images that were put into @var{buffer} the way +@code{put-image} does it, not images that were inserted with +@code{insert-image} or in other ways. +@end defun + +@node Image Cache +@subsection Image Cache + + Emacs stores images in an image cache when it displays them, so it can +display them again more efficiently. It removes an image from the cache +when it hasn't been displayed for a specified period of time. + +@defvar image-cache-eviction-delay +@tindex image-cache-eviction-delay +This variable specifies the number of seconds an image can remain in the +cache without being displayed. When an image is not displayed for this +length of time, Emacs removes it from the image cache. + +If the value is @code{nil}, Emacs does not remove images from the cache +except when you explicitly clear it. This mode can be useful for +debugging. +@end defvar + +@defun clear-image-cache &optional frame +@tindex clear-image-cache +This function clears the image cache. If @var{frame} is non-@code{nil}, +only the cache for that frame is cleared. Otherwise all frames' caches +are cleared. +@end defun @node Blinking @section Blinking Parentheses @cindex parenthesis matching @@ -1451,13 +2697,19 @@ All other codes in the range 0 through 31, and code 127, display in one of two ways according to the value of @code{ctl-arrow}. If it is non-@code{nil}, these codes map to sequences of two glyphs, where the -first glyph is the @sc{ASCII} code for @samp{^}. (A display table can +first glyph is the @sc{ascii} code for @samp{^}. (A display table can specify a glyph to use instead of @samp{^}.) Otherwise, these codes map just like the codes in the range 128 to 255. +On MS-DOS terminals, Emacs arranges by default for the character code +127 to be mapped to the glyph code 127, which normally displays as an +empty polygon. This glyph is used to display non-@sc{ascii} characters +that the MS-DOS terminal doesn't support. @xref{MS-DOS and MULE,,, +emacs, The GNU Emacs Manual}. + @item Character codes 128 through 255 map to sequences of four glyphs, where -the first glyph is the @sc{ASCII} code for @samp{\}, and the others are +the first glyph is the @sc{ascii} code for @samp{\}, and the others are digit characters representing the character code in octal. (A display table can specify a glyph to use instead of @samp{\}.) @@ -1511,11 +2763,11 @@ @cindex display table You can use the @dfn{display table} feature to control how all possible character codes display on the screen. This is useful for displaying -European languages that have letters not in the @sc{ASCII} character +European languages that have letters not in the @sc{ascii} character set. The display table maps each character code into a sequence of -@dfn{glyphs}, each glyph being an image that takes up one character +@dfn{glyphs}, each glyph being a graphic that takes up one character position on the screen. You can also define how to display each glyph on your terminal, using the @dfn{glyph table}. @@ -1557,9 +2809,14 @@ @table @asis @item 0 The glyph for the end of a truncated screen line (the default for this -is @samp{$}). @xref{Glyphs}. +is @samp{$}). @xref{Glyphs}. Newer Emacs versions, on some platforms, +display arrows to indicate truncation---the display table has no effect +in these situations. @item 1 The glyph for the end of a continued line (the default is @samp{\}). +Newer Emacs versions, on some platforms, display curved arrows to +indicate truncation---the display table has no effect in these +situations. @item 2 The glyph for indicating a character displayed as an octal character code (the default is @samp{\}). @@ -1570,7 +2827,9 @@ default is @samp{...}). @xref{Selective Display}. @item 5 The glyph used to draw the border between side-by-side windows (the -default is @samp{|}). @xref{Splitting Windows}. +default is @samp{|}). @xref{Splitting Windows}. This takes effect only +when there are no scroll bars; if scroll bars are supported and in use, +a scroll bar separates the two windows. @end table For example, here is how to construct a display table that mimics the @@ -1604,6 +2863,18 @@ @code{selective-display}, and @code{vertical-border}. @end defun +@defun describe-display-table display-table +@tindex describe-display-table +This function displays a description of the display table +@var{display-table} in a help buffer. +@end defun + +@deffn Command describe-current-display-table +@tindex describe-current-display-table +This command displays a description of the current display table in a +help buffer. +@end deffn + @node Active Display Table @subsection Active Display Table @cindex active display table @@ -1645,6 +2916,9 @@ display conventions for all character codes in that window. @xref{Usual Display}. +A number of functions for changing the standard display table +are defined in the library @file{disp-table}. + @node Glyphs @subsection Glyphs @@ -1694,6 +2968,12 @@ If a glyph code is greater than or equal to the length of the glyph table, that code is automatically simple. +@defun create-glyph string +@tindex create-glyph +This function returns a newly-allocated glyph code which is set up to +display by sending @var{string} to the terminal. +@end defun + @node Beeping @section Beeping @cindex beeping @@ -1747,9 +3027,11 @@ @cindex X Window System Emacs is displaying using X. @item pc -Emacs is displaying using MSDOS. +Emacs is displaying using MS-DOS. @item w32 -Emacs is displaying using Windows NT or Windows 95. +Emacs is displaying using Windows NT or Windows 9x. +@item mac +Emacs is displaying using a Macintosh. @item nil Emacs is using a character-based terminal. @end table
--- a/lispref/edebug.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/edebug.texi Fri Sep 17 06:59:04 1999 +0000 @@ -66,9 +66,9 @@ * Jumping:: Commands to jump to a specified place. * Misc: Edebug Misc. Miscellaneous commands. * Breakpoints:: Setting breakpoints to make the program stop. -* Trapping Errors:: trapping errors with Edebug. +* Trapping Errors:: Trapping errors with Edebug. * Views: Edebug Views. Views inside and outside of Edebug. -* Eval: Edebug Eval. Evaluating expressions within Edebug. +* Eval: Edebug Eval. Evaluating expressions within Edebug. * Eval List:: Expressions whose values are displayed each time you enter Edebug. * Printing in Edebug:: Customization of printing. @@ -89,23 +89,23 @@ @ref{Instrumenting}, for alternative ways to instrument code. Once a function is instrumented, any call to the function activates -Edebug. Activating Edebug may stop execution and let you step through -the function, or it may update the display and continue execution while -checking for debugging commands, depending on which Edebug execution -mode you have selected. The default execution mode is step, which does -stop execution. @xref{Edebug Execution Modes}. +Edebug. Depending on which Edebug execution mode you have selected, +activating Edebug may stop execution and let you step through the +function, or it may update the display and continue execution while +checking for debugging commands. The default execution mode is step, +which stops execution. @xref{Edebug Execution Modes}. Within Edebug, you normally view an Emacs buffer showing the source of the Lisp code you are debugging. This is referred to as the @dfn{source -code buffer}. This buffer is temporarily read-only. +code buffer}, and is is temporarily read-only. An arrow at the left margin indicates the line where the function is executing. Point initially shows where within the line the function is executing, but this ceases to be true if you move point yourself. If you instrument the definition of @code{fac} (shown below) and then -execute @code{(fac 3)}, here is what you normally see. Point is at the -open-parenthesis before @code{if}. +execute @code{(fac 3)}, here is what you would normally see. Point is +at the open-parenthesis before @code{if}. @example (defun fac (n) @@ -118,7 +118,7 @@ The places within a function where Edebug can stop execution are called @dfn{stop points}. These occur both before and after each subexpression that is a list, and also after each variable reference. -Here we show with periods the stop points found in the function +Here we use periods to show the stop points in the function @code{fac}: @example @@ -163,7 +163,7 @@ argument on a definition, it instruments the definition before evaluating it. (The source code itself is not modified.) If the variable @code{edebug-all-defs} is non-@code{nil}, that inverts the -meaning of the prefix argument: then @kbd{C-M-x} instruments the +meaning of the prefix argument: in this case, @kbd{C-M-x} instruments the definition @emph{unless} it has a prefix argument. The default value of @code{edebug-all-defs} is @code{nil}. The command @kbd{M-x edebug-all-defs} toggles the value of the variable @@ -188,10 +188,11 @@ (@code{edebug-instrument-callee}) instruments the definition of the function or macro called by the list form after point, if is not already instrumented. This is possible only if Edebug knows where to find the -source for that function; after loading Edebug, @code{eval-region} -records the position of every definition it evaluates, even if not -instrumenting it. See also the @kbd{i} command (@pxref{Jumping}), which -steps into the call after instrumenting the function. +source for that function; for this reading, after loading Edebug, +@code{eval-region} records the position of every definition it +evaluates, even if not instrumenting it. See also the @kbd{i} command +(@pxref{Jumping}), which steps into the call after instrumenting the +function. @cindex special forms (Edebug) @cindex interactive commands (Edebug) @@ -201,15 +202,16 @@ @pindex cl-specs.el Edebug knows how to instrument all the standard special forms, @code{interactive} forms with an expression argument, anonymous lambda -expressions, and other defining forms. Edebug cannot know what a -user-defined macro will do with the arguments of a macro call, so you -must tell it; see @ref{Instrumenting Macro Calls}, for details. +expressions, and other defining forms. However, Edebug cannot determine +on its own what a user-defined macro will do with the arguments of a +macro call, so you must provide that information; see @ref{Instrumenting +Macro Calls}, for details. When Edebug is about to instrument code for the first time in a session, it runs the hook @code{edebug-setup-hook}, then sets it to -@code{nil}. You can use this to arrange to load Edebug specifications +@code{nil}. You can use this to load Edebug specifications (@pxref{Instrumenting Macro Calls}) associated with a package you are -using, but actually load them only if you use Edebug. +using, but only when you use Edebug. @findex eval-expression @r{(Edebug)} To remove instrumentation from a definition, simply re-evaluate its @@ -238,12 +240,12 @@ Normally, you specify the Edebug execution mode by typing a command to continue the program in a certain mode. Here is a table of these -commands. All except for @kbd{S} resume execution of the program, at +commands; all except for @kbd{S} resume execution of the program, at least for a certain distance. @table @kbd @item S -Stop: don't execute any more of the program for now, just wait for more +Stop: don't execute any more of the program, but wait for more Edebug commands (@code{edebug-stop}). @item @key{SPC} @@ -296,7 +298,7 @@ completely work: exiting from Edebug, to resume the program, loses track of the keyboard macro. This is not easy to fix. Also, defining or executing a keyboard macro outside of Edebug does not affect commands -inside Edebug. This is usually an advantage. But see the +inside Edebug. This is usually an advantage. See also the @code{edebug-continue-kbd-macro} option (@pxref{Edebug Options}). When you enter a new Edebug level, the initial execution mode comes from @@ -316,8 +318,8 @@ execution. @xref{Breakpoints}, for the details on breakpoints. These commands may fail to work as expected in case of nonlocal exit, -because a nonlocal exit can bypass the temporary breakpoint where you -expected the program to stop. +as that can bypass the temporary breakpoint where you expected the +program to stop. @table @kbd @item h @@ -348,13 +350,13 @@ more elements, then the place to stop is after the containing expression. -Be careful that the position @kbd{C-M-f} finds is a place that the -program will really get to; this may not be true in a -@code{cond}, for example. +You must check that the position @kbd{C-M-f} finds is a place that the +program will really get to. In @code{cond}, for example, this may not +be true. -The @kbd{f} command does @code{forward-sexp} starting at point, rather -than at the stop point, for flexibility. If you want to execute one -expression @emph{from the current stop point}, type @kbd{w} first, to +For flexibility, the @kbd{f} command does @code{forward-sexp} starting +at point, rather than at the stop point. If you want to execute one +expression @emph{from the current stop point}, first type @kbd{w}, to move point there, and then type @kbd{f}. The @kbd{o} command continues ``out of'' an expression. It places a @@ -397,7 +399,7 @@ debugging. @item Q -Like @kbd{q} but don't stop even for protected code +Like @kbd{q}, but don't stop even for protected code (@code{top-level-nonstop}). @item r @@ -415,22 +417,21 @@ execution. @end table -From the Edebug recursive edit, you may invoke commands that activate -Edebug again recursively. Any time Edebug is active, you can quit to -the top level with @kbd{q} or abort one recursive edit level with -@kbd{C-]}. You can display a backtrace of all the -pending evaluations with @kbd{d}. +You can invoke commands from Edebug that activate Edebug again +recursively. Whenever Edebug is active, you can quit to the top level +with @kbd{q} or abort one recursive edit level with @kbd{C-]}. You can +display a backtrace of all the pending evaluations with @kbd{d}. @node Breakpoints @subsection Breakpoints @cindex breakpoints -Edebug's step mode stops execution at the next stop point reached. +Edebug's step mode stops execution when the next stop point is reached. There are three other ways to stop Edebug execution once it has started: breakpoints, the global break condition, and source breakpoints. While using Edebug, you can specify @dfn{breakpoints} in the program you -are testing: points where execution should stop. You can set a +are testing: these are places where execution should stop. You can set a breakpoint at any stop point, as defined in @ref{Using Edebug}. For setting and unsetting breakpoints, the stop point that is affected is the first one at or after point in the source code buffer. Here are the @@ -440,8 +441,8 @@ @item b Set a breakpoint at the stop point at or after point (@code{edebug-set-breakpoint}). If you use a prefix argument, the -breakpoint is temporary (it turns off the first time it stops the -program). +breakpoint is temporary---it turns off the first time it stops the +program. @item u Unset the breakpoint (if any) at the stop point at or after @@ -463,7 +464,8 @@ then type @kbd{b} or @kbd{u} to set or unset a breakpoint there. Unsetting a breakpoint where none has been set has no effect. -Re-evaluating or reinstrumenting a definition forgets all its breakpoints. +Re-evaluating or reinstrumenting a definition removes all of its +previous breakpoints. A @dfn{conditional breakpoint} tests a condition each time the program gets there. Any errors that occur as a result of evaluating the @@ -478,7 +480,7 @@ breakpoint. When a temporary breakpoint stops the program, it is automatically unset. -Edebug always stops or pauses at a breakpoint except when the Edebug +Edebug always stops or pauses at a breakpoint, except when the Edebug mode is Go-nonstop. In that mode, it ignores breakpoints entirely. To find out where your breakpoints are, use the @kbd{B} command, which @@ -500,7 +502,7 @@ @cindex global break condition A @dfn{global break condition} stops execution when a specified condition is satisfied, no matter where that may occur. Edebug -evaluates the global break condition at every stop point. If it +evaluates the global break condition at every stop point; if it evaluates to a non-@code{nil} value, then execution stops or pauses depending on the execution mode, as if a breakpoint had been hit. If evaluating the condition gets an error, execution does not stop. @@ -520,11 +522,12 @@ @findex edebug @cindex source breakpoints All breakpoints in a definition are forgotten each time you -reinstrument it. To make a breakpoint that won't be forgotten, you can -write a @dfn{source breakpoint}, which is simply a call to the function -@code{edebug} in your source code. You can, of course, make such a call -conditional. For example, in the @code{fac} function, insert the first -line as shown below to stop when the argument reaches zero: +reinstrument it. If you wish to make a breakpoint that won't be +forgotten, you can write a @dfn{source breakpoint}, which is simply a +call to the function @code{edebug} in your source code. You can, of +course, make such a call conditional. For example, in the @code{fac} +function, you can insert the first line as shown below, to stop when the +argument reaches zero: @example (defun fac (n) @@ -553,10 +556,10 @@ When Edebug responds to an error, it shows the last stop point encountered before the error. This may be the location of a call to a -function which was not instrumented, within which the error actually +function which was not instrumented, and within which the error actually occurred. For an unbound variable error, the last known stop point might be quite distant from the offending variable reference. In that -case you might want to display a full backtrace (@pxref{Edebug Misc}). +case, you might want to display a full backtrace (@pxref{Edebug Misc}). @c Edebug should be changed for the following: -- dan If you change @code{debug-on-error} or @code{debug-on-quit} while @@ -616,12 +619,12 @@ @node Edebug Eval @subsection Evaluation - While within Edebug, you can evaluate expressions ``as if'' Edebug were -not running. Edebug tries to be invisible to the expression's + While within Edebug, you can evaluate expressions ``as if'' Edebug +were not running. Edebug tries to be invisible to the expression's evaluation and printing. Evaluation of expressions that cause side -effects will work as expected except for things that Edebug explicitly -saves and restores. @xref{The Outside Context}, for details on this -process. +effects will work as expected, except for changes to data that Edebug +explicitly saves and restores. @xref{The Outside Context}, for details +on this process. @table @kbd @item e @var{exp} @key{RET} @@ -739,9 +742,9 @@ To delete a group, move point into it and type @kbd{C-c C-d}, or simply delete the text for the group and update the evaluation list with @kbd{C-c C-u}. To add a new expression to the evaluation list, insert -the expression at a suitable place, and insert a new comment line. (You -need not insert dashes in the comment line---its contents don't matter.) -Then type @kbd{C-c C-u}. +the expression at a suitable place, insert a new comment line, then type +@kbd{C-c C-u}. You need not insert dashes in the comment line---its +contents don't matter. After selecting @samp{*edebug*}, you can return to the source code buffer with @kbd{C-c C-w}. The @samp{*edebug*} buffer is killed when @@ -764,22 +767,18 @@ @xref{Output Variables}. @defopt edebug-print-length -If non-@code{nil}, bind @code{print-length} to this while printing -results in Edebug. The default value is @code{50}. +If non-@code{nil}, Edebug binds @code{print-length} to this value while +printing results. The default value is @code{50}. @end defopt @defopt edebug-print-level -If non-@code{nil}, bind @code{print-level} to this while printing -results in Edebug. The default value is @code{50}. +If non-@code{nil}, Edebug binds @code{print-level} to this value while +printing results. The default value is @code{50}. @end defopt You can also print circular structures and structures that share -elements more informatively by using the @file{cust-print} package. - - To load @file{cust-print} and activate custom printing only for -Edebug, simply use the command @kbd{M-x edebug-install-custom-print}. -To restore the standard print functions, use @kbd{M-x -edebug-uninstall-custom-print}. +elements more informatively by binding @code{print-circle} +to a non-@code{nil} value. Here is an example of code that creates a circular structure: @@ -796,8 +795,8 @@ vectors. @defopt edebug-print-circle -If non-@code{nil}, bind @code{print-circle} to this while printing -results in Edebug. The default value is @code{nil}. +If non-@code{nil}, Edebug binds @code{print-circle} to this value while +printing results. The default value is @code{nil}. @end defopt Other programs can also use custom printing; see @file{cust-print.el} @@ -816,9 +815,9 @@ mode (@pxref{Edebug Execution Modes}). When trace recording is enabled, each function entry and exit adds -lines to the trace buffer. A function entry record looks like -@samp{::::@{} followed by the function name and argument values. A -function exit record looks like @samp{::::@}} followed by the function +lines to the trace buffer. A function entry record consists of +@samp{::::@{}, followed by the function name and argument values. A +function exit record consists of @samp{::::@}}, followed by the function name and result of the function. The number of @samp{:}s in an entry shows its recursion depth. You @@ -834,7 +833,7 @@ @defmac edebug-tracing string body@dots{} This macro requests additional trace information around the execution of the @var{body} forms. The argument @var{string} specifies text -to put in the trace buffer. All the arguments are evaluated. +to put in the trace buffer. All the arguments are evaluated, and @code{edebug-tracing} returns the value of the last form in @var{body}. @end defmac @@ -964,15 +963,15 @@ the program), it restores the previous window configuration. Emacs redisplays only when it pauses. Usually, when you continue -execution, the program comes back into Edebug at a breakpoint or after -stepping without pausing or reading input in between. In such cases, +execution, the program re-enters Edebug at a breakpoint or after +stepping, without pausing or reading input in between. In such cases, Emacs never gets a chance to redisplay the ``outside'' configuration. -What you see is the same window configuration as the last time Edebug -was active, with no interruption. +Consequently, what you see is the same window configuration as the last +time Edebug was active, with no interruption. Entry to Edebug for displaying something also saves and restores the -following data, but some of these are deliberately not restored if an -error or quit signal occurs. +following data (though some of them are deliberately not restored if an +error or quit signal occurs). @itemize @bullet @item
--- a/lispref/elisp.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/elisp.texi Fri Sep 17 06:59:04 1999 +0000 @@ -12,8 +12,8 @@ @smallbook @ifinfo -This Info file contains edition 2.5.1 of the GNU Emacs Lisp -Reference Manual, corresponding to Emacs version 20.4. +This Info file contains edition 2.6 of the GNU Emacs Lisp +Reference Manual, corresponding to Emacs version 21.1. @c Please REMEMBER to update edition number in *four* places in this file @c and also in *one* place in intro.texi @@ -75,7 +75,7 @@ @subtitle For Emacs Version 20.4 @c The edition number appears in several places in this file @c and also in the file intro.texi. -@subtitle Revision 2.5.1, January 1999 +@subtitle Revision 2.6, September 1999 @author by Bil Lewis, Dan LaLiberte, Richard Stallman @author and the GNU Manual Group @@ -85,11 +85,11 @@ Free Software Foundation, Inc. @sp 2 -Edition 2.5.1 @* -Revised for Emacs Version 20.4,@* -January 1999.@* +Edition 2.6 @* +Revised for Emacs Version 21.1,@* +September 1999.@* @sp 2 -ISBN 1-882114-72-8 +ISBN 1-882114-73-6 @sp 2 Published by the Free Software Foundation @* @@ -120,8 +120,8 @@ @node Top, Copying, (dir), (dir) @ifinfo -This Info file contains edition 2.5.1 of the GNU Emacs Lisp -Reference Manual, corresponding to GNU Emacs version 20.4. +This Info file contains edition 2.6 of the GNU Emacs Lisp +Reference Manual, corresponding to GNU Emacs version 21.1. @end ifinfo @menu @@ -136,6 +136,7 @@ * Sequences Arrays Vectors:: Lists, strings and vectors are called sequences. Certain functions act on any kind of sequence. The description of vectors is here as well. +* Hash Tables:: Very fast lookup-tables. * Symbols:: Symbols represent names, uniquely. * Evaluation:: How Lisp expressions are evaluated. @@ -867,10 +868,10 @@ Starting Up Emacs -* Start-up Summary:: Sequence of actions Emacs performs at start-up. +* Startup Summary:: Sequence of actions Emacs performs at start-up. * Init File:: Details on reading the init file (@file{.emacs}). * Terminal-Specific:: How the terminal-specific Lisp file is read. -* Command Line Arguments:: How command line arguments are processed, +* Command-Line Arguments:: How command line arguments are processed, and how you can customize them. Getting out of Emacs @@ -914,6 +915,7 @@ @include lists.texi @include sequences.texi +@include hash.texi @include symbols.texi @include eval.texi
--- a/lispref/errors.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/errors.texi Fri Sep 17 06:59:04 1999 +0000 @@ -64,12 +64,12 @@ @item end-of-file @code{"End of file during parsing"}@* -Note that this is not a @code{file-error} +Note that this is not a subcategory of @code{file-error}, because it pertains to the Lisp reader, not to file I/O. @xref{Input Functions}. @item file-already-exists -This is a @code{file-error}.@* +This is a subcategory of @code{file-error}.@* @xref{Writing to Files}. @item file-date-error @@ -84,11 +84,11 @@ @xref{Files}. @item file-locked -This is a @code{file-error}.@* +This is a subcategory of @code{file-error}.@* @xref{File Locks}. @item file-supersession -This is a @code{file-error}.@* +This is a subcategory of @code{file-error}.@* @xref{Modification Time}. @item invalid-function
--- a/lispref/files.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/files.texi Fri Sep 17 06:59:04 1999 +0000 @@ -126,7 +126,7 @@ This function displays warning or advisory messages in various peculiar cases, unless the optional argument @var{nowarn} is non-@code{nil}. For example, if it needs to create a buffer, and there is no file named -@var{filename}, it displays the message @samp{New file} in the echo +@var{filename}, it displays the message @samp{(New file)} in the echo area, and leaves the buffer empty. The @code{find-file-noselect} function normally calls @@ -260,7 +260,7 @@ If reading the file got an error because the file does not exist, but its directory does exist, the caller should pass a non-@code{nil} value for @var{error}. In that case, @code{after-find-file} issues a warning: -@samp{(New File)}. For more serious errors, the caller should usually not +@samp{(New file)}. For more serious errors, the caller should usually not call @code{after-find-file}. If @var{warn} is non-@code{nil}, then this function issues a warning @@ -312,7 +312,7 @@ The optional @var{exiting} argument, if non-@code{nil}, requests this function to offer also to save certain other buffers that are not visiting files. These are buffers that have a non-@code{nil} -buffer-local value of @code{buffer-offer-save}. (A user who says yes to +buffer-local value of @code{buffer-offer-save}. (A user who says @samp{yes} to saving one of these is asked to specify a file name to use.) The @code{save-buffers-kill-emacs} function passes a non-@code{nil} value for this argument. @@ -447,7 +447,9 @@ 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}. +Properties}. Normally, one of the functions in the +@code{after-insert-file-functions} list determines the coding system +(@pxref{Coding Systems}) used for decoding the file's contents. 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 @@ -510,19 +512,29 @@ or a nonexistent file in a directory where files cannot be created. @end deffn -@deffn Command write-region start end filename &optional append visit confirm +@deffn Command write-region start end filename &optional append visit mustbenew This function writes the region delimited by @var{start} and @var{end} in the current buffer into the file specified by @var{filename}. @c Emacs 19 feature If @var{start} is a string, then @code{write-region} writes or appends -that string, rather than text from the buffer. +that string, rather than text from the buffer. @var{end} is ignored in +this case. If @var{append} is non-@code{nil}, then the specified text is appended to the existing file contents (if any). -If @var{confirm} is non-@code{nil}, then @code{write-region} asks +If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks for confirmation if @var{filename} names an existing file. +Starting in Emacs 21, if @var{mustbenew} is the symbol @code{excl}, +then @code{write-region} does not ask for confirmation, but instead +it signals an error @code{file-already-exists} if the file already +exists. + +The test for an existing file, when @var{mustbenew} is @code{excl}, uses +a special system feature. At least for files on a local disk, there is +no chance that some other program could create a file of the same name +before Emacs does, without Emacs's noticing. If @var{visit} is @code{t}, then Emacs establishes an association between the buffer and the file: the buffer is then visiting that file. @@ -615,6 +627,10 @@ does nothing if the current buffer is not visiting a file. @end defun + File locking is not supported on some systems. On systems that do not +support it, the functions @code{lock-buffer}, @code{unlock-buffer} and +@code{file-locked-p} do nothing and return @code{nil}. + @defun ask-user-about-lock file other-user This function is called when the user tries to modify @var{file}, but it is locked by another user named @var{other-user}. The default @@ -710,10 +726,10 @@ @c Emacs 19 feature @defun file-executable-p filename This function returns @code{t} if a file named @var{filename} exists and -you can execute it. It returns @code{nil} otherwise. If the file is a -directory, execute permission means you can check the existence and -attributes of files inside the directory, and open those files if their -modes permit. +you can execute it. It returns @code{nil} otherwise. On Unix, if the +file is a directory, execute permission means you can check the +existence and attributes of files inside the directory, and open those +files if their modes permit. @end defun @defun file-writable-p filename @@ -1081,7 +1097,8 @@ last had its inode changed on Aug 19 00:09. @item 14906 -is 14906 characters long. +is 14906 bytes long. (It may not contain 14906 characters, though, +if some of the bytes belong to multibyte sequences.) @item "-rw-rw-rw-" has a mode of read and write access for the owner, group, and world. @@ -1186,7 +1203,8 @@ @end example This function is meaningless on operating systems where multiple names -for one file are not allowed. +for one file are not allowed. Some systems implement multiple names +by copying the file instead. See also @code{file-nlinks} in @ref{File Attributes}. @end defun @@ -1241,6 +1259,9 @@ In an interactive call, this function prompts for @var{filename} and @var{newname} in the minibuffer; also, it requests confirmation if @var{newname} already exists. + +This function is not available on systems that don't support symbolic +links. @end deffn @defun define-logical-name varname string @@ -1275,9 +1296,13 @@ @cindex MS-DOS and file modes @cindex file modes and MS-DOS On MS-DOS, there is no such thing as an ``executable'' file mode bit. -So Emacs considers a file executable if its name ends in @samp{.com}, -@samp{.bat} or @samp{.exe}. This is reflected in the values returned -by @code{file-modes} and @code{file-attributes}. +So Emacs considers a file executable if its name ends in one of the +standard executable extensions, such as @file{.com}, @file{.bat}, +@file{.exe}, and some others. Files that begin with the Unix-standard +@samp{#!} signature, such as shell and Perl scripts, are also considered +as executable files. This is reflected in the values returned by +@code{file-modes} and @code{file-attributes}. Directories are also +reported with executable bit set, for compatibility with Unix. @node File Names @section File Names @@ -1327,22 +1352,22 @@ (or @dfn{file name within the directory}). Either part may be empty. Concatenating these two parts reproduces the original file name. - On Unix, the directory part is everything up to and including the last -slash; the nondirectory part is the rest. The rules in VMS syntax are -complicated. + On most systems, the directory part is everything up to and including +the last slash; the nondirectory part is the rest. The rules in VMS +syntax are complicated. For some purposes, the nondirectory part is further subdivided into -the name proper and the @dfn{version number}. On Unix, only backup -files have version numbers in their names. On VMS, every file has a -version number, but most of the time the file name actually used in -Emacs omits the version number, so that version numbers in Emacs are +the name proper and the @dfn{version number}. On most systems, only +backup files have version numbers in their names. On VMS, every file +has a version number, but most of the time the file name actually used +in Emacs omits the version number, so that version numbers in Emacs are found mostly in directory lists. @defun file-name-directory filename This function returns the directory part of @var{filename} (or @code{nil} if @var{filename} does not include a directory part). On -Unix, the function returns a string ending in a slash. On VMS, it -returns a string ending in one of the three characters @samp{:}, +most systems, the function returns a string ending in a slash. On VMS, +it returns a string ending in one of the three characters @samp{:}, @samp{]}, or @samp{>}. @example @@ -1429,7 +1454,7 @@ kind of file, and it has a file name, which is related to the directory name but not identical to it. (This is not quite the same as the usual Unix terminology.) These two different names for the same entity are -related by a syntactic transformation. On Unix, this is simple: a +related by a syntactic transformation. On most systems, this is simple: a directory name ends in a slash, whereas the directory's name as a file lacks that slash. On VMS, the relationship is more complicated. @@ -1444,9 +1469,9 @@ @defun file-name-as-directory filename This function returns a string representing @var{filename} in a form -that the operating system will interpret as the name of a directory. In -Unix, this means appending a slash to the string (if it does not already -end in one). On VMS, the function converts a string of the form +that the operating system will interpret as the name of a directory. On +most systems, this means appending a slash to the string (if it does not +already end in one). On VMS, the function converts a string of the form @file{[X]Y.DIR.1} to the form @file{[X.Y]}. @example @@ -1459,9 +1484,9 @@ @defun directory-file-name dirname This function returns a string representing @var{dirname} in a form that -the operating system will interpret as the name of a file. On Unix, -this means removing the final slash from the string. On VMS, the -function converts a string of the form @file{[X.Y]} to +the operating system will interpret as the name of a file. On most +systems, this means removing the final slash from the string. On VMS, +the function converts a string of the form @file{[X.Y]} to @file{[X]Y.DIR.1}. @example @@ -1522,8 +1547,10 @@ file name. Or it can specify the position of the file in the tree relative to a default directory; then it is called a @dfn{relative} file name. On Unix, an absolute file name starts with a slash or a -tilde (@samp{~}), and a relative one does not. The rules on VMS are -complicated. +tilde (@samp{~}), and a relative one does not. On MS-DOS and +MS-Windows, an absolute file name starts with a slash or a backslash, or +with a drive specification @samp{@var{x}:/}, where @var{x} is the +@dfn{drive letter}. The rules on VMS are complicated. @defun file-name-absolute-p filename This function returns @code{t} if file @var{filename} is an absolute @@ -1625,7 +1652,7 @@ @code{expand-file-name} uses the default directory when its second argument is @code{nil}. -On Unix systems, the value is always a string ending with a slash. +Aside from VMS, the value is always a string ending with a slash. @example @group @@ -1680,7 +1707,54 @@ @subsection Generating Unique File Names Some programs need to write temporary files. Here is the usual way to -construct a name for such a file: +construct a name for such a file, starting in Emacs 21: + +@example +(make-temp-file @var{name-of-application}) +@end example + +@noindent +The job of @code{make-temp-file} is to prevent two different users or +two different jobs from trying to use the exact same file name. + +@defun make-temp-file prefix &optional dir-flag +@tindex make-temp-file +This function creates a temporary file and returns its name. +The name starts with @var{prefix}; it also contains a number that is +different in each Emacs job. If @var{prefix} is a relative file name, +it is expanded against @code{temporary-file-directory}. + +@example +@group +(make-temp-file "foo") + @result{} "/tmp/foo232J6v" +@end group +@end example + +When @code{make-temp-file} returns, the file has been created and is +empty. At that point, you should write the intended contents into the +file. + +If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates +an empty directory instead of an empty file. + +To prevent conflicts among different libraries running in the same +Emacs, each Lisp program that uses @code{make-temp-file} should have its +own @var{prefix}. The number added to the end of @var{prefix} +distinguishes between the same application running in different Emacs +jobs. Additional added characters permit a large number of distinct +names even in one Emacs job. +@end defun + + The default directory for temporary files is controlled by the +variable @code{temporary-file-directory}. This variable gives the user +a uniform way to specify the directory for all temporary files. Some +programs use @code{small-temporary-file-directory} instead, if that is +non-@code{nil}. To use it, you should expand the prefix against +the proper directory before calling @code{make-temp-file}. + + In older Emacs versions where @code{make-temp-file} does not exist, +you should use @code{make-temp-name} instead: @example (make-temp-name @@ -1688,37 +1762,19 @@ temporary-file-directory)) @end example -@noindent -The job of @code{make-temp-name} is to prevent two different users or -two different jobs from trying to use the exact same file name. This -example uses the variable @code{temporary-file-directory} to decide -where to put the temporary file. All Emacs Lisp programs should -use @code{temporary-file-directory} for this purpose, to give the user -a uniform way to specify the directory for all temporary files. - @defun make-temp-name string This function generates a string that can be used as a unique file name. The name starts with @var{string}, and contains a number that is -different in each Emacs job. - -@example -@group -(make-temp-name "/tmp/foo") - @result{} "/tmp/foo232J6v" -@end group -@end example - -To prevent conflicts among different libraries running in the same -Emacs, each Lisp program that uses @code{make-temp-name} should have its -own @var{string}. The number added to the end of @var{string} -distinguishes between the same application running in different Emacs -jobs. Additional added characters permit a large number of distinct -names even in one Emacs job. +different in each Emacs job. It is like @code{make-temp-file} except +that it just constructs a name, and does not create a file. On MS-DOS, +the @var{string} prefix can be truncated to fit into the 8+3 file-name +limits. @end defun @defvar temporary-file-directory -@cindex @code{TMPDIR} environment variable. -@cindex @code{TMP} environment variable. +@cindex @code{TMPDIR} environment variable +@cindex @code{TMP} environment variable +@cindex @code{TEMP} environment variable This variable specifies the directory name for creating temporary files. Its value should be a directory name (@pxref{Directory Names}), but it is good for Lisp programs to cope if the value is a directory's file @@ -1726,12 +1782,31 @@ @code{expand-file-name} is a good way to achieve that. The default value is determined in a reasonable way for your operating -system; on GNU and Unix systems it is based on the @code{TMP} and -@code{TMPDIR} environment variables. +system; it is based on the @code{TMPDIR}, @code{TMP} and @code{TEMP} +environment variables, with a fall-back to a system-dependent name if +none of these variables is defined. Even if you do not use @code{make-temp-name} to choose the temporary file's name, you should still use this variable to decide which -directory to put the file in. +directory to put the file in. However, if you expect the file to be +small, you should use @code{small-temporary-file-directory} first if +that is non-@code{nil}. +@end defvar + +@tindex small-temporary-file-directory +@defvar small-temporary-file-directory +This variable (new in Emacs 21) specifies the directory name for +creating certain temporary files, which are likely to be small. + +If you want to write a temporary file which is likely to be small, you +should compute the directory like this: + +@example +(make-temp-file + (expand-file-name @var{prefix} + (or small-temporary-file-directory + temporary-file-directory))) +@end example @end defvar @node File Name Completion @@ -1953,15 +2028,20 @@ describe a directory itself as a file, rather than showing its contents.) -This function works by running a directory listing program whose name is -in the variable @code{insert-directory-program}. If @var{wildcard} is -non-@code{nil}, it also runs the shell specified by +On most systems, this function works by running a directory listing +program whose name is in the variable @code{insert-directory-program}. +If @var{wildcard} is non-@code{nil}, it also runs the shell specified by @code{shell-file-name}, to expand the wildcards. + +MS-DOS and MS-Windows systems usually lack the standard Unix program +@code{ls}, so this function emulates the standard Unix program @code{ls} +with Lisp code. @end defun @defvar insert-directory-program This variable's value is the program to run to generate a directory listing -for the function @code{insert-directory}. +for the function @code{insert-directory}. It is ignored on systems +which generate the listing with Lisp code. @end defvar @node Create/Delete Dirs @@ -2070,6 +2150,7 @@ @end ifinfo @iftex @noindent +@flushleft @code{add-name-to-file}, @code{copy-file}, @code{delete-directory}, @code{delete-file}, @code{diff-latest-backup-file}, @@ -2103,6 +2184,7 @@ @code{vc-regis@discretionary{}{}{}tered}, @code{verify-visited-file-modtime}, @code{write-region}. +@end flushleft @end iftex Handlers for @code{insert-file-contents} typically need to clear the
--- a/lispref/frames.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/frames.texi Fri Sep 17 06:59:04 1999 +0000 @@ -24,8 +24,22 @@ display several such frames at once as is usual for window systems. @defun framep object -This predicate returns @code{t} if @var{object} is a frame, and -@code{nil} otherwise. +This predicate returns a non-@code{nil} value if @var{object} is a +frame, and @code{nil} otherwise. For a frame, the value indicates which +kind of display the frame uses: + +@table @code +@item x +The frame is displayed in an X window. +@item t +A terminal frame on a character display. +@item mac +The frame is displayed on a Macintosh. +@item w32 +The frame is displayed on MS-Windows 9X/NT. +@item pc +The frame is displayed on an MS-DOS terminal. +@end table @end defun @menu @@ -49,10 +63,8 @@ * Dialog Boxes:: Displaying a box to ask yes or no. * Pointer Shapes:: Specifying the shape of the mouse pointer. * Window System Selections:: Transferring text to and from other X clients. -* Font Names:: Looking up font names. -* Fontsets:: A fontset is a collection of fonts - for displaying various character sets. * Color Names:: Getting the definitions of color names. +* Text Terminal Colors:: Defining colors for text-only terminals. * Resources:: Getting resource values from the server. * Server Data:: Getting info about the X server. @end menu @@ -86,8 +98,8 @@ frame. @end defvar -@defvar after-make-frame-hook -@tindex after-make-frame-hook +@defvar after-make-frame-functions +@tindex after-make-frame-functions An abnormal hook run by @code{make-frame} after it creates the frame. Each function in @code{after-make-frame-hook} receives one argument, the frame just created. @@ -163,14 +175,17 @@ @node Frame Parameters @section Frame Parameters -A frame has many parameters that control its appearance and behavior. + A frame has many parameters that control its appearance and behavior. 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, mostly for compatibility's sake; only the @code{height}, -@code{width}, @code{name}, @code{title}, @code{buffer-list} and -@code{buffer-predicate} parameters do something special. + Frame parameters exist mostly for the sake of window systems. A +terminal frame has a few parameters, mostly for compatibility's sake; +only the @code{height}, @code{width}, @code{name}, @code{title}, +@code{menu-bar-lines}, @code{buffer-list} and @code{buffer-predicate} +parameters do something special. If the terminal supports colors, the +parameters @code{foreground-color}, @code{background-color}, +@code{background-mode} and @code{display-type} are also meaningful. @menu * Parameter Access:: How to change a frame's parameters. @@ -222,7 +237,7 @@ 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 +appearance with X resources; those do take effect 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 @@ -391,7 +406,9 @@ @item font The name of the font for displaying text in the frame. This is a string, either a valid font name for your system or the name of an Emacs -fontset (@pxref{Fontsets}). +fontset (@pxref{Fontsets}). Changing this frame parameter on a frame, +also changes the font-related attributes of the default face on that +frame. @item auto-raise Whether selecting the frame raises it (non-@code{nil} means yes). @@ -424,30 +441,40 @@ @item foreground-color The color to use for the image of a character. This is a string; the -window system defines the meaningful color names. - -If you set the @code{foreground-color} frame parameter, you should -call @code{frame-update-face-colors} to update faces accordingly. +window system defines the meaningful color names. Changing this +parameter is equivalent to changing the foreground color of the face +@code{default} on the frame in question. @item background-color -The color to use for the background of characters. - -If you set the @code{background-color} frame parameter, you should -call @code{frame-update-face-colors} to update faces accordingly. -@xref{Face Functions}. +The color to use for the background of characters. Changing this +parameter is equivalent to changing the foreground color of the face +@code{default} on the frame in question. @item background-mode This parameter is either @code{dark} or @code{light}, according to whether the background color is a light one or a dark one. @item mouse-color -The color for the mouse pointer. +The color for the mouse pointer. Changing this parameter is equivalent +to changing the background color of face @code{mouse}. @item cursor-color -The color for the cursor that shows point. +The color for the cursor that shows point. Changing this parameter is +equivalent to changing the background color of face @code{cursor}. @item border-color -The color for the border of the frame. +The color for the border of the frame. Changing this parameter is +equivalent to changing the background color of face @code{border}. + +@item scroll-bar-foreground +If non-@code{nil}, the color for the foreground of scroll bars. +Changing this parameter is equivalent to setting the foreground color of +face @code{scroll-bar}. + +@item scroll-bar-background +If non-@code{nil}, the color for the background of scroll bars. +Changing this parameter is equivalent to setting the foreground color of +face @code{scroll-bar}. @item display-type This parameter describes the range of possible colors that can be used @@ -482,6 +509,17 @@ toolkit, there is only one menu bar line; all that matters about the number you specify is whether it is greater than zero.) +@item screen-gamma +If this is a number, Emacs performs ``gamma correction'' on colors. The +value should be the screen gamma of your display, a floating point +number. Usual PC monitors have a screen gamma of 2.2. Smaller values +result in darker colors; you might want to try a screen gamma of 1.5 for +LCD color displays. The viewing gamma Emacs uses is 0.4545 (1/2.2). + +@item tool-bar-lines +The number of lines to use for the toolbar. A value of @code{nil} means +don't display a tool bar. + @ignore @item parent-id @c ??? Not yet working. @@ -755,7 +793,7 @@ the lower right corner (always the minibuffer window, if the frame has one), and then it moves back to the top. @xref{Cyclic Window Ordering}. -@defun frame-top-window frame +@defun frame-first-window frame This returns the topmost, leftmost window of frame @var{frame}. @end defun @@ -1309,180 +1347,160 @@ @defvar selection-coding-system @tindex selection-coding-system This variable specifies the coding system to use when reading and -writing a selections, the clipboard, or a cut buffer. @xref{Coding +writing selections, the clipboard, or a cut buffer. @xref{Coding Systems}. The default is @code{compound-text}. @end defvar -@need 1500 -@node Font Names -@section Looking up Font Names - -@defun x-list-font pattern &optional face frame maximum -This function returns a list of available font names that match -@var{pattern}. If the optional arguments @var{face} and @var{frame} are -specified, then the list is limited to fonts that are the same size as -@var{face} currently is on @var{frame}. - -The argument @var{pattern} should be a string, perhaps with wildcard -characters: the @samp{*} character matches any substring, and the -@samp{?} character matches any single character. Pattern matching -of font names ignores case. - -If you specify @var{face} and @var{frame}, @var{face} should be a face name -(a symbol) and @var{frame} should be a frame. - -The optional argument @var{maximum} sets a limit on how many fonts to -return. If this is non-@code{nil}, then the return value is truncated -after the first @var{maximum} matching fonts. Specifying a small value -for @var{maximum} can make this function much faster, in cases where -many fonts match the pattern. -@end defun - -@node Fontsets -@section Fontsets - - A @dfn{fontset} is a list of fonts, each assigned to a range of -character codes. An individual font cannot display the whole range of -characters that Emacs supports, but a fontset can. Fontsets have names, -just as fonts do, and you can use a fontset name in place of a font name -when you specify the ``font'' for a frame or a face. Here is -information about defining a fontset under Lisp program control. - -@defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror -This function defines a new fontset according to the specification -string @var{fontset-spec}. The string should have this format: - -@smallexample -@var{fontpattern}, @r{[}@var{charsetname}:@var{fontname}@r{]@dots{}} -@end smallexample - -@noindent -Whitespace characters before and after the commas are ignored. - -The first part of the string, @var{fontpattern}, should have the form of -a standard X font name, except that the last two fields should be -@samp{fontset-@var{alias}}. - -The new fontset has two names, one long and one short. The long name is -@var{fontpattern} in its entirety. The short name is -@samp{fontset-@var{alias}}. You can refer to the fontset by either -name. If a fontset with the same name already exists, an error is -signaled, unless @var{noerror} is non-@code{nil}, in which case this -function does nothing. +@cindex clipboard support (for MS-Windows) +When Emacs runs on MS-Windows, it does not implement X selections in +general, but it it does support the clipboard. @code{x-get-selection} +and @code{x-set-selection} on MS-Windows support the text data type +only; if the clipboard holds other types of data, Emacs treats the +clipboard as empty. -If optional argument @var{style-variant-p} is non-@code{nil}, that says -to create bold, italic and bold-italic variants of the fontset as well. -These variant fontsets do not have a short name, only a long one, which -is made by altering @var{fontpattern} to indicate the bold or italic -status. - -The specification string also says which fonts to use in the fontset. -See below for the details. -@end defun - - The construct @samp{@var{charset}:@var{font}} specifies which font to -use (in this fontset) for one particular character set. Here, -@var{charset} is the name of a character set, and @var{font} is the font -to use for that character set. You can use this construct any number of -times in the specification string. - - For the remaining character sets, those that you don't specify -explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces -@samp{fontset-@var{alias}} with a value that names one character set. -For the @sc{ASCII} character set, @samp{fontset-@var{alias}} is replaced -with @samp{ISO8859-1}. - - In addition, when several consecutive fields are wildcards, Emacs -collapses them into a single wildcard. This is to prevent use of -auto-scaled fonts. Fonts made by scaling larger fonts are not usable -for editing, and scaling a smaller font is not useful because it is -better to use the smaller font in its own size, which Emacs does. - - Thus if @var{fontpattern} is this, - -@example --*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24 -@end example - -@noindent -the font specification for ASCII characters would be this: - -@example --*-fixed-medium-r-normal-*-24-*-ISO8859-1 -@end example - -@noindent -and the font specification for Chinese GB2312 characters would be this: - -@example --*-fixed-medium-r-normal-*-24-*-gb2312*-* -@end example - - You may not have any Chinese font matching the above font -specification. Most X distributions include only Chinese fonts that -have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In -such a case, @samp{Fontset-@var{n}} can be specified as below: - -@smallexample -Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\ - chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-* -@end smallexample - -@noindent -Then, the font specifications for all but Chinese GB2312 characters have -@samp{fixed} in the @var{family} field, and the font specification for -Chinese GB2312 characters has a wild card @samp{*} in the @var{family} -field. +@defopt x-select-enable-clipboard +If this is non-@code{nil}, the Emacs yank functions consult the +clipboard before the primary selection, and the kill functions store in +the clipboard as well as the primary selection. Otherwise they do not +access the clipboard at all. The default is @code{nil} on most systems, +but @code{t} on MS-Windows. +@end defopt @node Color Names @section Color Names -@defun x-color-defined-p color &optional frame + These functions provide a way to determine which color names are +valid, and what they look like. + +@defun color-defined-p color &optional frame +@tindex color-defined-p This function reports whether a color name is meaningful. It returns @code{t} if so; otherwise, @code{nil}. The argument @var{frame} says which frame's display to ask about; if @var{frame} is omitted or @code{nil}, the selected frame is used. Note that this does not tell you whether the display you are using -really supports that color. You can ask for any defined color on any -kind of display, and you will get some result---that is how the X server -works. Here's an approximate way to test whether your display supports -the color @var{color}: +really supports that color. When using X, you can ask for any defined +color on any kind of display, and you will get some result---typically, +the best it knows how to do. Here's an approximate way to test whether +your display supports the color @var{color}: @example (defun x-color-supported-p (color &optional frame) - (and (x-color-defined-p color frame) + (and (color-defined-p color frame) (or (x-display-color-p frame) (member color '("black" "white")) (and (> (x-display-planes frame) 1) (equal color "gray"))))) @end example + +This function used to be called @code{x-color-defined-p}, +and that name is still supported as an alias. @end defun -@defun x-color-values color &optional frame +@defun defined-colors &optional frame +@tindex defined-colors +This function returns a list of the color names that are defined +and supported on frame @var{frame} (default, the selected frame). + +This function used to be called @code{x-defined-colors}, +and that name is still supported as an alias. +@end defun + +@defun color-values color &optional frame +@tindex color-values This function returns a value that describes what @var{color} should ideally look like. If @var{color} is defined, the value is a list of three integers, which give the amount of red, the amount of green, and the amount of blue. Each integer ranges in principle from 0 to 65535, -but in practice no value seems to be above 65280. If @var{color} is not -defined, the value is @code{nil}. +but in practice no value seems to be above 65280. This kind +of three-element list is called an @dfn{rgb value}. + +If @var{color} is not defined, the value is @code{nil}. @example -(x-color-values "black") +(color-values "black") @result{} (0 0 0) -(x-color-values "white") +(color-values "white") @result{} (65280 65280 65280) -(x-color-values "red") +(color-values "red") @result{} (65280 0 0) -(x-color-values "pink") +(color-values "pink") @result{} (65280 49152 51968) -(x-color-values "hungry") +(color-values "hungry") @result{} nil @end example The color values are returned for @var{frame}'s display. If @var{frame} is omitted or @code{nil}, the information is returned for the selected frame's display. + +This function used to be called @code{x-color-values}, +and that name is still supported as an alias. +@end defun + +@node Text Terminal Colors +@section Text Terminal Colors +@cindex colors on text-only terminals + + Emacs can display color on text-only terminals, starting with version +21. These terminals support only a small number of colors, and the +computer uses small integers to select colors on the terminal. This +means that the computer cannot reliably tell what the selected color +looks like; instead, you have to inform your application which small +integers correspond to which colors. However, Emacs does know the +standard set of colors and will try to use them automatically. + +@cindex rgb value + Several of these functions use or return @dfn{rgb values}. An rgb +value is a list of three integers, which give the amount of red, the +amount of green, and the amount of blue. Each integer ranges in +principle from 0 to 65535, but in practice the largest value used is +65280. + +@defun tty-define-color name number &optional rgb +@tindex tty-define-color +This function associates the color name @var{name} with +color number @var{number} on the terminal. + +The optional argument @var{rgb}, if specified, is an rgb value; it says +what the color actually looks like. If you do not specify @var{rgb}, +then this color cannot be used by @code{tty-color-approximate} to +approximate other colors, because Emacs does not know what it looks +like. +@end defun + +@defun tty-clear-colors +@tindex tty-clear-colors +This function clears the table of defined colors for a text-only terminal. +@end defun + +@defvar tty-color-alist +@tindex tty-color-alist +This variable holds an alist recording the colors supported by the +terminal. + +Each element has the form @code{(@var{name} @var{number} . @var{rgb})} +or @code{(@var{name} @var{number})}. Here, @var{name} is the color +name, @var{number} is the number used to specify it to the terminal. +If present, @var{rgb} is an rgb value that says what the color +actually looks like. +@end defun + +@defun tty-color-approximate rgb +@tindex tty-color-approximate +This function finds the closest available color, among those in +@code{tty-color-alist}, to that described by the rgb value @var{rgb}. +@end defun + +@defun tty-color-translate color +@tindex tty-color-translate +This function finds the closest available color, among those in +@code{tty-color-alist}, to the name @var{color}. If that name +is not defined, the value is @code{nil}. + +@var{color} can be an X-style @code{#@var{xxxyyyzzz}} specification +instead of an actual name. @end defun @node Resources
--- a/lispref/functions.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/functions.texi Fri Sep 17 06:59:04 1999 +0000 @@ -879,6 +879,7 @@ (function @var{symbol}) @equiv{} (quote @var{symbol}) @equiv{} '@var{symbol} @end example +@cindex @samp{#'} syntax The read syntax @code{#'} is a short-hand for using @code{function}. For example,
--- a/lispref/internals.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/internals.texi Fri Sep 17 06:59:04 1999 +0000 @@ -97,7 +97,7 @@ @item Specify a non-@code{nil} value for -@code{byte-compile-dynamic-docstrings} as a local variable in each these +@code{byte-compile-dynamic-docstrings} as a local variable in each of these files, and load them with either @file{site-load.el} or @file{site-init.el}. (This method has the drawback that the documentation strings take up space in Emacs all the time.) @@ -107,7 +107,7 @@ @file{site-init.el} that would alter any of the features that users expect in an ordinary unmodified Emacs. If you feel you must override normal features for your site, do it with @file{default.el}, so that -users can override your changes if they wish. @xref{Start-up Summary}. +users can override your changes if they wish. @xref{Startup Summary}. @defun dump-emacs to-file from-file @cindex unexec @@ -125,7 +125,7 @@ Emacs Lisp uses two kinds of storage for user-created Lisp objects: @dfn{normal storage} and @dfn{pure storage}. Normal storage is where -all the new data created during an Emacs session is kept; see the +all the new data created during an Emacs session are kept; see the following section for information on normal storage. Pure storage is used for certain data in the preloaded standard Lisp files---data that should never change during actual use of Emacs. @@ -142,8 +142,8 @@ preload additional libraries or add features to the standard ones. @defun purecopy object -This function makes a copy of @var{object} in pure storage and returns -it. It copies strings by simply making a new string with the same +This function makes a copy in pure storage of @var{object}, and returns +it. It copies a string by simply making a new string with the same characters in pure storage. It recursively copies the contents of vectors and cons cells. It does not make copies of other objects such as symbols, but just returns them unchanged. It signals an error if @@ -553,10 +553,10 @@ Alas, we can't explain all the tricky details here. You must not use C initializers for static or global variables unless -they are never written once Emacs is dumped. These variables with -initializers are allocated in an area of memory that becomes read-only -(on certain operating systems) as a result of dumping Emacs. @xref{Pure -Storage}. +the variables are never stored in once Emacs is dumped. These variables +with initializers are allocated in an area of memory that becomes +read-only (on certain operating systems) as a result of dumping Emacs. +@xref{Pure Storage}. Do not use static variables within functions---place all static variables at top level in the file. This is necessary because Emacs on @@ -587,16 +587,19 @@ of these functions are called, and add a call to @code{syms_of_@var{filename}} there. +@vindex byte-boolean-vars The function @code{syms_of_@var{filename}} is also the place to define any C variables that are to be visible as Lisp variables. @code{DEFVAR_LISP} makes a C variable of type @code{Lisp_Object} visible in Lisp. @code{DEFVAR_INT} makes a C variable of type @code{int} visible in Lisp with a value that is always an integer. @code{DEFVAR_BOOL} makes a C variable of type @code{int} visible in Lisp -with a value that is either @code{t} or @code{nil}. +with a value that is either @code{t} or @code{nil}. Note that variables +defined with @code{DEFVAR_BOOL} are automatically added to the list +@code{byte-boolean-vars} used by the byte compiler. If you define a file-scope C variable of type @code{Lisp_Object}, -you must protect it for garbage-collection by calling @code{staticpro} +you must protect it from garbage-collection by calling @code{staticpro} in @code{syms_of_@var{filename}}, like this: @example @@ -681,6 +684,11 @@ @file{lisp.h} contains the definitions for some important macros and functions. + If you define a function which is side-effect free, update the code in +@file{byte-opt.el} which binds @code{side-effect-free-fns} and +@code{side-effect-and-error-free-fns} to include it. This will help the +optimizer. + @node Object Internals @appendixsec Object Internals @cindex object internals @@ -729,9 +737,9 @@ @item modtime This field contains the modification time of the visited file. It is -set when the file is written or read. Every time the buffer is written -to the file, this field is compared to the modification time of the -file. @xref{Buffer Modification}. +set when the file is written or read. Before writing the buffer into a +file, this field is compared to the modification time of the file to see +if the file has changed on disk. @xref{Buffer Modification}. @item auto_save_modified This field contains the time when the buffer was last auto-saved. @@ -872,7 +880,9 @@ The height of the window, measured in lines. @item width -The width of the window, measured in columns. +The width of the window, measured in columns. This width includes the +scroll bar and fringes, and/or the separator line on the right of the +window (if any). @item next This is the window that is the next in the chain of siblings. It is
--- a/lispref/intro.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/intro.texi Fri Sep 17 06:59:04 1999 +0000 @@ -343,7 +343,7 @@ @smallexample @var{one line to give the program's name and an idea of what it does.} -Copyright (C) 19@var{yy} @var{name of author} +Copyright (C) @var{year} @var{name of author} This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License @@ -366,7 +366,7 @@ when it starts in an interactive mode: @smallexample -Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} +Gnomovision version 69, Copyright (C) @var{year} @var{name of author} Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' @@ -521,7 +521,7 @@ @pindex cl A certain amount of Common Lisp emulation is available via the -@file{cl} library @xref{Top,, Common Lisp Extension, cl, Common Lisp +@file{cl} library. @xref{Top,, Common Lisp Extension, cl, Common Lisp Extensions}. Emacs Lisp is not at all influenced by Scheme; but the GNU project has @@ -556,10 +556,9 @@ programs, including those you write. @cindex fonts - Examples of Lisp code appear in this font or form: @code{(list 1 2 -3)}. Names that represent metasyntactic variables, or arguments to a -function being described, appear in this font or form: -@var{first-number}. + Examples of Lisp code are formatted like this: @code{(list 1 2 3)}. +Names that represent metasyntactic variables, or arguments to a function +being described, are formatted like this: @var{first-number}. @node nil and t @subsection @code{nil} and @code{t} @@ -685,13 +684,13 @@ @subsection Buffer Text Notation @cindex buffer text notation - Some examples show modifications to text in a buffer, with ``before'' -and ``after'' versions of the text. These examples show the contents of -the buffer in question between two lines of dashes containing the buffer -name. In addition, @samp{@point{}} indicates the location of point. -(The symbol for point, of course, is not part of the text in the buffer; -it indicates the place @emph{between} two characters where point is -currently located.) + Some examples describe modifications to the contents of a buffer, by +showing the ``before'' and ``after'' versions of the text. These +examples show the contents of the buffer in question between two lines +of dashes containing the buffer name. In addition, @samp{@point{}} +indicates the location of point. (The symbol for point, of course, is +not part of the text in the buffer; it indicates the place +@emph{between} two characters where point is currently located.) @example ---------- Buffer: foo ---------- @@ -900,7 +899,9 @@ The value of this variable is the version of Emacs being run. It is a string such as @code{"20.3.1"}. The last number in this string is not really part of the Emacs release version number; it is incremented each -time you build Emacs in any given directory. +time you build Emacs in any given directory. A value with three numeric +components, such as @code{"20.3.9.1"}, indicates an unreleased test +version. @end defvar The following two variables have existed since Emacs version 19.23:
--- a/lispref/keymaps.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/keymaps.texi Fri Sep 17 06:59:04 1999 +0000 @@ -124,17 +124,17 @@ @item @var{vector} If an element of a keymap is a vector, the vector counts as bindings for -all the @sc{ASCII} characters, codes 0 through 127; vector element +all the @sc{ascii} characters, codes 0 through 127; vector element @var{n} is the binding for the character with code @var{n}. This is a compact way to record lots of bindings. A keymap with such a vector is called a @dfn{full keymap}. Other keymaps are called @dfn{sparse keymaps}. When a keymap contains a vector, it always defines a binding for each -@sc{ASCII} character, even if the vector contains @code{nil} for that +@sc{ascii} character, even if the vector contains @code{nil} for that character. Such a binding of @code{nil} overrides any default key -binding in the keymap, for @sc{ASCII} characters. However, default -bindings are still meaningful for events other than @sc{ASCII} +binding in the keymap, for @sc{ascii} characters. However, default +bindings are still meaningful for events other than @sc{ascii} characters. A binding of @code{nil} does @emph{not} override lower-precedence keymaps; thus, if the local map gives a binding of @code{nil}, Emacs uses the binding from the global map. @@ -215,8 +215,8 @@ @c ??? This should come after make-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} -characters). The new keymap initially binds all @sc{ASCII} characters +containing a vector of length 128 for defining all the @sc{ascii} +characters). The new keymap initially binds all @sc{ascii} characters to @code{nil}, and does not bind any other kind of event. @example @@ -567,7 +567,7 @@ This function returns the current buffer's local keymap, or @code{nil} if it has none. In the following example, the keymap for the @samp{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap -in which the entry for @key{ESC}, @sc{ASCII} code 27, is another sparse +in which the entry for @key{ESC}, @sc{ascii} code 27, is another sparse keymap. @example @@ -953,7 +953,7 @@ translating a meta character to a two-character sequence so it can be looked up in a keymap. For useful results, the value should be a prefix event (@pxref{Prefix Keys}). The default value is 27, which is the -@sc{ASCII} code for @key{ESC}. +@sc{ascii} code for @key{ESC}. As long as the value of @code{meta-prefix-char} remains 27, key lookup translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally @@ -1256,6 +1256,35 @@ redefines the first (leftmost) mouse button, typed with the Meta key, to set point where you click. +@cindex non-ASCII text in keybindings + Be careful when using non-@sc{ascii} text characters in Lisp +specifications of keys to bind. If these are read as multibyte text, as +they usually will be in a Lisp file (@pxref{Loading Non-ASCII}), you +must type the keys as multibyte too. For instance, if you use this: + +@smallexample +(global-set-key "@"o" 'my-function) ; bind o-umlaut +@end smallexample + +@noindent +or + +@smallexample +(global-set-key ?@"o 'my-function) ; bind o-umlaut +@end smallexample + +@noindent +and your language environment is multibyte Latin-1, these commands +actually bind the multibyte character with code 2294, not the unibyte +Latin-1 character with code 246 (@kbd{M-v}). In order to use this +binding, you need to enter the multibyte Latin-1 character as keyboard +input. One way to do this is by using an appropriate input method +(@pxref{Input Methods, , Input Methods, emacs,The GNU Emacs Manual}). + + If you want to use a unibyte character in the key binding, you can +construct the key sequence string using @code{multibyte-char-to-unibyte} +or @code{string-make-unibyte} (@pxref{Converting Representations}). + @deffn Command global-set-key key definition This function sets the binding of @var{key} in the current global map to @var{definition}. @@ -1431,7 +1460,7 @@ string representing the first key sequence found, rather than a list of all possible key sequences. If @var{firstonly} is @code{t}, then the value is the first key sequence, except that key sequences consisting -entirely of @sc{ASCII} characters (or meta variants of @sc{ASCII} +entirely of @sc{ascii} characters (or meta variants of @sc{ascii} characters) are preferred to all other key sequences. If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't @@ -1457,13 +1486,13 @@ The listing describes meta characters as @key{ESC} followed by the corresponding non-meta character. -When several characters with consecutive @sc{ASCII} codes have the +When several characters with consecutive @sc{ascii} codes have the same definition, they are shown together, as @samp{@var{firstchar}..@var{lastchar}}. In this instance, you need to -know the @sc{ASCII} codes to understand which characters this means. +know the @sc{ascii} codes to understand which characters this means. For example, in the default global map, the characters @samp{@key{SPC} -..@: ~} are described by a single line. @key{SPC} is @sc{ASCII} 32, -@kbd{~} is @sc{ASCII} 126, and the characters between them include all +..@: ~} are described by a single line. @key{SPC} is @sc{ascii} 32, +@kbd{~} is @sc{ascii} 126, and the characters between them include all the normal printing characters, (e.g., letters, digits, punctuation, etc.@:); all these characters are bound to @code{self-insert-command}. @end deffn @@ -1483,6 +1512,7 @@ * Keyboard Menus:: How they actuate it with the keyboard. * Menu Example:: Making a simple menu. * Menu Bar:: How to customize the menu bar. +* Tool Bar:: A tool bar is a row of images. * Modifying Menus:: How to add new items to a menu. @end menu @@ -1509,10 +1539,11 @@ @menu * Simple Menu Items:: A simple kind of menu key binding, limited in capabilities. -* Alias Menu Items:: Using command aliases in menu items. * Extended Menu Items:: More powerful menu item definitions let you specify keywords to enable various features. +* Menu Separators:: Drawing a horizontal line through a menu. +* Alias Menu Items:: Using command aliases in menu items. @end menu @node Simple Menu Items @@ -1591,7 +1622,8 @@ @end example @noindent -where a string consisting of two or more dashes specifies a separator line. +A string starting with two or more dashes specifies a separator line; +see @ref{Menu Separators}. To define a real menu item which can be selected, the extended format item looks like this: @@ -1609,11 +1641,12 @@ other information. Here is a table of the properties that are supported: @table @code -@item :enable FORM +@item :enable @var{form} The result of evaluating @var{form} determines whether the item is -enabled (non-@code{nil} means yes). +enabled (non-@code{nil} means yes). If the item is not enabled, +you can't really click on it. -@item :visible FORM +@item :visible @var{form} The result of evaluating @var{form} determines whether the item should actually appear in the menu (non-@code{nil} means yes). If the item does not appear, then the menu is displayed as if this item were @@ -1684,6 +1717,80 @@ function should return the binding to use instead. @end table +@node Menu Separators +@subsubsection Menu Separators +@cindex menu separators + + A menu separator is a kind of menu item that doesn't display any +text--instead, it divides the menu into subparts with a horizontal line. +A separator looks like this in the menu keymap: + +@example +(menu-item @var{separator-type}) +@end example + +@noindent +where @var{separator-type} is a string starting with two or more dashes. + + In the simplest case, @var{separator-type} consists of only dashes. +That specifies the default kind of separator. (For compatibility, +@code{""} and @code{-} also count as separators.) + + Starting in Emacs 21, certain other values of @var{separator-type} +specify a different style of separator. Here is a table of them: + +@table @code +@item "--no-line" +@itemx "--space" +An extra vertical space, with no actual line. + +@item "--single-line" +A single line in the menu's foreground color. + +@item "--double-line" +A double line in the menu's foreground color. + +@item "--single-dashed-line" +A single dashed line in the menu's foreground color. + +@item "--double-dashed-line" +A double dashed line in the menu's foreground color. + +@item "--shadow-etched-in" +A single line with a 3D sunken appearance. This is the default, +used separators consisting of dashes only. + +@item "--shadow-etched-out" +A single line with a 3D raised appearance. + +@item "--shadow-etched-in-dash" +A single dashed line with a 3D sunken appearance. + +@item "--shadow-etched-out-dash" +A single dashed line with a 3D raised appearance. + +@item "--shadow-double-etched-in" +Two lines with a 3D sunken appearance. + +@item "--shadow-double-etched-out" +Two lines with a 3D raised appearance. + +@item "--shadow-double-etched-in-dash" +Two dashed lines with a 3D sunken appearance. + +@item "--shadow-double-etched-out-dash" +Two dashed lines with a 3D raised appearance. +@end table + + You can also give these names in another style, adding a colon after +the double-dash and replacing each single dash with capitalization of +the following word. Thus, @code{"--:singleLine"}, is equivalent to +@code{"--single-line"}. + + Some systems and display toolkits don't really handle all of these +separator types. If you use a type that isn't supported, the menu +displays a similar kind of separator that is supported. + @node Alias Menu Items @subsubsection Alias Menu Items @@ -1978,6 +2085,115 @@ should vary. @end defvar +@node Tool Bar +@subsection Tool bars +@cindex tool bar + + A @dfn{tool bar} is a row of icons at the top of a frame, that execute +commands when you click on them---in effect, a kind of graphical menu +bar. Emacs supports tool bars starting with version 21. + + The frame parameter @code{tool-bar-lines} (X resource @samp{toolBar}) +controls how may lines' worth of height to reserve for the tool bar. A +zero value suppresses the tool bar. If the value is nonzero, and +@code{auto-resize-tool-bars} is non-@code{nil}, the tool bar expands and +contracts automatically as needed to hold the specified contents. + + The tool bar contents are controlled by a menu keymap attached to a +fake ``function key'' called @code{tool-bar} (much like the way the menu +bar is controlled). So you define a tool bar item using +@code{define-key}, like this: + +@example +(define-key global-map [tool-bar @var{key}] @var{item}) +@end example + +@noindent +where @var{key} is a fake ``function key'' to distinguish this item from +other items, and @var{item} is a menu item key binding (@pxref{Extended +Menu Items}), which says how to display this item and how it behaves. + + The usual menu keymap item properties, @code{:visible}, +@code{:enable}, @code{:button}, and @code{:filter}, are useful in +tool bar bindings and have their normal meanings. The @var{real-binding} +in the item must be a command, not a keymap; in other words, it does not +work to define a tool bar icon as a prefix key. + + The @code{:help} property is meaningful, and specifies a ``help-echo'' +string to display while the mouse is on that item. + + In addition, you should use the @code{:image} property; +this is how you specify the image to display in the tool bar: + +@table @code +@item :image @var{image} +@var{images} is either a single image specification or a vector of four +image specifications. If you use a vector of four, +one of them is used, depending on circumstances: + +@table @asis +@item item 0 +Used when the iitem is enabled and selected. +@item item 1 +Used when the item is enabled and deselected. +@item item 2 +Used when the item is disabled and selected. +@item item 3 +Used when the item is disabled and deselected. +@end table +@end table + +@tindex auto-resize-tool-bar +@defvar auto-resize-tool-bar +If this variable is non-@code{nil}, the tool bar automatically resizes to +show all defined tool bar items---but not larger than a quarter of the +frame's height. +@end defvar + +@tindex auto-raise-tool-bar-items +@defvar auto-raise-tool-bar-items +If this variable is non-@code{nil}, tool bar items display +in raised form when the mouse moves over them. +@end defvar + +@tindex tool-bar-item-margin +@defvar tool-bar-item-margin +This variable specifies an extra margin to add around tool bar items. +The value is an integer, a number of pixels. The default is 1. +@end defvar + +@tindex tool-bar-item-relief +@defvar tool-bar-item-relief +This variable specifies the shadow width for tool bar items. +The value is an integer, a number of pixels. The default is 3. +@end defvar + + You can define a special meaning for clicking on a tool bar item with +the shift, control, meta, etc., modifiers. You do this by setting up +additional items that relate to the original item through the fake +function keys. Specifically, the additional items should use the +modified versions of the same fake function key used to name the +original item. + + Thus, if the original item was defined this way, + +@example +(define-key global-map [tool-bar shell] + '(menu-item "Shell" shell + :image (image :type xpm :file "shell.xpm"))) +@end example + +@noindent +then here is how you can define clicking on the same tool bar image with +the shift modifier: + +@example +(define-key global-map [tool-bar S-shell] 'some-command) +@end example + +@xref{Function Keys}, for more information about how to add modifiers to +function keys. + @node Modifying Menus @subsection Modifying Menus
--- a/lispref/lists.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/lists.texi Fri Sep 17 06:59:04 1999 +0000 @@ -302,6 +302,26 @@ @end example @end defun +@tindex pop +@defmac pop listname +This macro is a way of examining the @sc{car} of a list, +and taking it off the list, all at once. It is new in Emacs 21. + +It operates on the list which is stored in the symbol @var{listname}. +It removes this element from the list by setting @var{listname} +to the @sc{cdr} of its old value---but it also returns the @sc{car} +of that list, which is the element being removed. + +@example +x + @result{} (a b c) +(pop x) + @result{} a +x + @result{} (b c) +@end example +@end defmac + @defun nth n list This function returns the @var{n}th element of @var{list}. Elements are numbered starting with zero, so the @sc{car} of @var{list} is @@ -441,6 +461,13 @@ any symbol can serve both purposes. @end defun +@tindex push +@defmac push newelt listname +This macro provides an alternative way to write +@code{(setq @var{listname} (cons @var{newelt} @var{listname}))}. +It is new in Emacs 21. +@end defmac + @defun list &rest objects This function creates a list with @var{objects} as its elements. The resulting list is always @code{nil}-terminated. If no @var{objects} @@ -1509,4 +1536,14 @@ @end smallexample @end defun +@defun assoc-delete-all key alist +@tindex assoc-delete-all +This function deletes from @var{alist} all the elements whose @sc{car} +is @var{key}. It returns the modified alist. +@example +(assoc-delete-all 'foo + '((foo 1) (bar 2) (foo 3) (lose 4))) + @result{} ((bar 2) (lose 4)) +@end example +@end defun
--- a/lispref/loading.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/loading.texi Fri Sep 17 06:59:04 1999 +0000 @@ -36,7 +36,7 @@ @menu * How Programs Do Loading:: The @code{load} function and others. * Library Search:: Finding a library to load. -* Loading Non-ASCII:: Non-@sc{ASCII} characters in Emacs Lisp files. +* Loading Non-ASCII:: Non-@sc{ascii} characters in Emacs Lisp files. * Autoload:: Setting up a function to autoload. * Repeated Loading:: Precautions about loading a file twice. * Named Features:: Loading a library if it isn't already loaded. @@ -257,10 +257,10 @@ Not all subdirectories are included, though. Subdirectories whose names do not start with a letter or digit are excluded. Subdirectories -named @file{RCS} are excluded. Also, a subdirectory which contains a -file named @file{.nosearch} is excluded. You can use these methods to -prevent certain subdirectories of the @file{site-lisp} directories from -being searched. +named @file{RCS} or @file{CVS} are excluded. Also, a subdirectory which +contains a file named @file{.nosearch} is excluded. You can use these +methods to prevent certain subdirectories of the @file{site-lisp} +directories from being searched. If you run Emacs from the directory where it was built---that is, an executable that has not been formally installed---then @code{load-path} @@ -287,7 +287,7 @@ @node Loading Non-ASCII @section Loading Non-ASCII Characters - When Emacs Lisp programs contain string constants with non-@sc{ASCII} + When Emacs Lisp programs contain string constants with non-@sc{ascii} characters, these can be represented within Emacs either as unibyte strings or as multibyte strings (@pxref{Text Representations}). Which representation is used depends on how the file is read into Emacs. If @@ -301,7 +301,7 @@ To make the results more predictable, Emacs always performs decoding into the multibyte representation when loading Lisp files, even if it was started with the @samp{--unibyte} option. This means that string -constants with non-@sc{ASCII} characters translate into multibyte +constants with non-@sc{ascii} characters translate into multibyte strings. The only exception is when a particular file specifies no decoding. @@ -313,13 +313,13 @@ @code{default-enable-multibyte-characters}, and convert representations appropriately. - In most Emacs Lisp programs, the fact that non-@sc{ASCII} strings are + In most Emacs Lisp programs, the fact that non-@sc{ascii} strings are multibyte strings should not be noticeable, since inserting them in unibyte buffers converts them to unibyte automatically. However, if this does make a difference, you can force a particular Lisp file to be interpreted as unibyte by writing @samp{-*-unibyte: t;-*-} in a comment on the file's first line. With that designator, the file will -be unconditionally be interpreted as unibyte, even in an ordinary +unconditionally be interpreted as unibyte, even in an ordinary multibyte Emacs session. @node Autoload @@ -432,13 +432,20 @@ The same magic comment can copy any kind of form into @file{loaddefs.el}. If the form following the magic comment is not a -function definition, it is copied verbatim. You can also use a magic -comment to execute a form at build time @emph{without} executing it when -the file itself is loaded. To do this, write the form @emph{on the same -line} as the magic comment. Since it is in a comment, it does nothing -when you load the source file; but @kbd{M-x update-file-autoloads} -copies it to @file{loaddefs.el}, where it is executed while building -Emacs. +function-defining form or a @code{defcustom} form, it is copied +verbatim. ``Function-defining forms'' include @code{define-skeleton}, +@code{define-derived-mode}, @code{define-generic-mode} and +@code{easy-mmode-define-minor-mode} as well as @code{defun} and +@code{defmacro}. To save space, a @code{defcustom} form is converted to +a @code{defvar} in @file{loaddefs.el}, with some additional information +if it uses @code{:require}. + + You can also use a magic comment to execute a form at build time +@emph{without} executing it when the file itself is loaded. To do this, +write the form @emph{on the same line} as the magic comment. Since it +is in a comment, it does nothing when you load the source file; but +@kbd{M-x update-file-autoloads} copies it to @file{loaddefs.el}, where +it is executed while building Emacs. The following example shows how @code{doctor} is prepared for autoloading with a magic comment: @@ -456,17 +463,17 @@ Here's what that produces in @file{loaddefs.el}: @smallexample -(autoload 'doctor "doctor" - "\ +(autoload 'doctor "doctor" "\ Switch to *doctor* buffer and start giving psychotherapy." t) @end smallexample @noindent The backslash and newline immediately following the double-quote are a -convention used only in the preloaded Lisp files such as +convention used only in the preloaded uncompiled Lisp files such as @file{loaddefs.el}; they tell @code{make-docfile} to put the documentation string in the @file{etc/DOC} file. @xref{Building Emacs}. +See also the commentary in @file{lib-src/make-docfile.c}. @node Repeated Loading @section Repeated Loading @@ -591,7 +598,9 @@ When @code{require} is used at top level in a file, it takes effect when you byte-compile that file (@pxref{Byte Compilation}) as well as when you load it. This is in case the required package contains macros -that the byte compiler must know about. +that the byte compiler must know about. It also avoids byte-compiler +warnings for functions and variables defined in the file loaded with +@code{require}. Although top-level calls to @code{require} are evaluated during byte compilation, @code{provide} calls are not. Therefore, you can @@ -701,6 +710,8 @@ definitions, @emph{instead of} the usual hook-removing actions. The unload hook ought to undo all the global state changes made by the library that might cease to work once the library is unloaded. +@code{unload-feature} can cause problems with libraries that fail to do +this, so it should be used with caution. Ordinarily, @code{unload-feature} refuses to unload a library on which other loaded libraries depend. (A library @var{a} depends on library @@ -741,7 +752,16 @@ by adding the symbols defined to the element for the file being visited, rather than replacing that element. @xref{Eval}. - Preloaded libraries don't contribute to @code{load-history}. + Preloaded libraries don't contribute initially to @code{load-history}. +Instead, preloading writes information about preloaded libraries into a +file, which can be loaded later on to to add information to +@code{load-history} describing the preloaded files. This file is +installed in @code{exec-directory} and has a name of the form +@file{fns-@var{emacsversion}.el}. + +@findex symbol-file + See the source for the function @code{symbol-file}, for an example of +code that loads this file to find functions in preloaded libraries. @tindex loadhist-special-hooks @defvar loadhist-special-hooks @@ -784,8 +804,8 @@ programs meant for wider use. @defvar after-load-alist -An alist of expressions to evaluate if and when particular libraries are -loaded. Each element looks like this: +This variable holds an alist of expressions to evaluate if and when +particular libraries are loaded. Each element looks like this: @example (@var{filename} @var{forms}@dots{})
--- a/lispref/maps.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/maps.texi Fri Sep 17 06:59:04 1999 +0000 @@ -67,34 +67,35 @@ @item facemenu-menu @vindex facemenu-menu -The keymap that displays the Text Properties menu. +The sparse 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 +The sparse 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. +The sparse 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 +The sparse 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. +The sparse 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 +The sparse 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 +The sparse keymap that displays the Special Props submenu of the Text Properties menu. @item function-key-map @@ -104,7 +105,7 @@ @item fundamental-mode-map @vindex fundamental-mode-map -The local keymap for Fundamental mode.@* +The sparse keymap for Fundamental mode.@* It is empty and should not be changed. @item Helper-help-map @@ -132,7 +133,7 @@ @item lisp-interaction-mode-map @vindex lisp-interaction-mode-map -A sparse keymap used by Lisp mode. +A sparse keymap used by Lisp Interaction mode. @item lisp-mode-map @vindex lisp-mode-map @@ -171,10 +172,10 @@ @item occur-mode-map @vindex occur-mode-map -A local keymap used by Occur mode. +A sparse keymap used by Occur mode. @item query-replace-map -A local keymap used for responses in @code{query-replace} and related +A sparse 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 time.
--- a/lispref/markers.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/markers.texi Fri Sep 17 06:59:04 1999 +0000 @@ -136,7 +136,7 @@ @end defun @node Creating Markers -@section Functions That Create Markers +@section Functions that Create Markers When you create a new marker, you can make it point nowhere, or point to the present position of point, or to the beginning or end of the
--- a/lispref/minibuf.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/minibuf.texi Fri Sep 17 06:59:04 1999 +0000 @@ -42,12 +42,26 @@ no minibuffer window, and sometimes a special kind of frame contains nothing but a minibuffer window; see @ref{Minibuffers and Frames}.) - The minibuffer's window is normally a single line. You can resize it -temporarily with the window sizing commands; it reverts to its normal -size when the minibuffer is exited. You can resize it permanently by -using the window sizing commands in the frame's other window, when the -minibuffer is not active. If the frame contains just a minibuffer, you -can change the minibuffer's size by changing the frame's size. + The text in the minibuffer always starts with the @dfn{prompt string}, +the text that was specified by the program that is using the minibuffer +to tell the user what sort of input to type. This text is marked +read-only so you won't accidentally delete or change it. In other +respects, it is an ordinary part of the buffer contents, but certain +functions such as @code{erase-buffer}, @code{buffer-string}, +@code{beginning-of-line}, @code{forward-word}, @code{forward-sentence}, +and @code{forward-paragraph}, treat it a little bit specially. (In +older Emacs versions, the prompt was displayed using a special mechanism +and was not part of the buffer contents.) + +@c ??? + The minibuffer's window is normally a single line; it grows +automatically if necessary if the contents require more space. You can +explicitly resize it temporarily with the window sizing commands; it +reverts to its normal size when the minibuffer is exited. You can +resize it permanently by using the window sizing commands in the frame's +other window, when the minibuffer is not active. If the frame contains +just a minibuffer, you can change the minibuffer's size by changing the +frame's size. If a command uses a minibuffer while there is an active minibuffer, this is called a @dfn{recursive minibuffer}. The first minibuffer is @@ -724,7 +738,7 @@ @end defun @node Completion Commands -@subsection Minibuffer Commands That Do Completion +@subsection Minibuffer Commands that Do Completion This section describes the keymaps, commands and user options used in the minibuffer to do completion. @@ -1483,9 +1497,16 @@ 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. +@tindex minubuffer-prompt-end +@defun minubuffer-prompt-end +This function, available starting in Emacs 21, returns the current +position of the end of the minibuffer prompt, if a minibuffer is +current. Otherwise, it returns zero. +@end defun + +@defun minubuffer-prompt-width +This function returns the current display-width of the minibuffer +prompt, if a minibuffer is current. Otherwise, it returns zero. @end defun @defvar minibuffer-setup-hook
--- a/lispref/modes.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/modes.texi Fri Sep 17 06:59:04 1999 +0000 @@ -61,7 +61,7 @@ Rmail Edit mode offers an example of changing the major mode temporarily for a buffer, so it can be edited in a different way (with ordinary Emacs commands rather than Rmail commands). In such cases, the -temporary major mode usually has a command to switch back to the +temporary major mode usually provides a command to switch back to the buffer's usual mode (Rmail mode, in this case). You might be tempted to present the temporary redefinitions inside a recursive edit and restore the usual ones when the user exits; but this is a bad idea because it @@ -70,8 +70,8 @@ alternative major mode avoids this limitation. @xref{Recursive Editing}. - The standard GNU Emacs Lisp library directory contains the code for -several major modes, in files such as @file{text-mode.el}, + The standard GNU Emacs Lisp library directory tree contains the code +for several major modes, in files such as @file{text-mode.el}, @file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and @file{rmail.el}. You can study these libraries to see how modes are written. Text mode is perhaps the simplest major mode aside from @@ -245,7 +245,7 @@ @end example @noindent -This tells Emacs that new buffers created while the current buffer has +This tells Emacs that new buffers created while the current buffer is in Funny mode should not inherit Funny mode. Modes such as Dired, Rmail, and Buffer List use this feature. @@ -368,7 +368,7 @@ @group ;; @r{Set syntax of chars up to 0 to class of chars that are} ;; @r{part of symbol names but not words.} - ;; @r{(The number 0 is @code{48} in the @sc{ASCII} character set.)} + ;; @r{(The number 0 is @code{48} in the @sc{ascii} character set.)} (while (< i ?0) (modify-syntax-entry i "_ " emacs-lisp-mode-syntax-table) (setq i (1+ i))) @@ -782,7 +782,8 @@ ``generally available, optional feature modes,'' except that such a name would be unwieldy. - A minor mode is not usually a modification of single major mode. For + A minor mode is not usually meant as a variation of a single major mode. +Usually they are general and can apply to many major modes. For example, Auto Fill mode works with any major mode that permits text insertion. To be general, a minor mode must be effectively independent of the things major modes do. @@ -825,7 +826,7 @@ should set this variable (@code{nil} to disable; anything else to enable). -If it is possible, implement the mode so that setting the variable +If possible, implement the mode so that setting the variable automatically enables or disables the mode. Then the minor mode command does not need to do anything except set the variable. @@ -890,6 +891,40 @@ You can also use @code{add-to-list} to add an element to this list just once (@pxref{Setting Variables}). + Global minor modes distributed with Emacs should if possible support +enabling and disabling via Custom (@pxref{Customization}). To do this, +the first step is to define the mode variable with @code{defcustom}, and +specify @code{:type boolean}. + + If just setting the variable is not sufficient to enable the mode, you +should also specify a @code{:set} method which enables the mode by +invoke the mode command. Note in the variable's documentation string that +setting the variable other than via Custom may not take effect. + + Also mark the definition with an autoload cookie (@pxref{Autoload}), +and specify a @code{:require} so that customizing the variable will load +the library that defines the mode. This will copy suitable definitions +into @file{loaddefs.el} so that users can use @code{customize-option} to +enable the mode. For example: + +@smallexample +@group + +;;;###autoload +(defcustom msb-mode nil + "Toggle msb-mode. +Setting this variable directly does not take effect; +use either \\[customize] or the function `msb-mode'." + :set (lambda (symbol value) + (msb-mode (or value 0))) + :initialize 'custom-initialize-default + :version "20.4" + :type 'boolean + :group 'msb + :require 'msb) +@end group +@end smallexample + @node Keymaps and Minor Modes @subsection Keymaps and Minor Modes @@ -908,15 +943,15 @@ The key sequences bound in a minor mode should consist of @kbd{C-c} followed by a punctuation character @emph{other than} @kbd{@{}, -@kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}. (Those few punctuation +@kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:}, and @kbd{;}. (Those few punctuation characters are reserved for major modes.) @node Easy-Mmode @subsection Easy-Mmode The easy-mmode package provides a convenient way of implementing a -minor mode; with it, you can specify everything about a simple minor -mode in one self-contained definition. +mode in one self-contained definition. It currently supports only +buffer-local minor modes, not global ones. @defmac easy-mmode-define-minor-mode mode doc &optional init-value mode-indicator keymap @tindex easy-mmode-define-minor-mode @@ -978,35 +1013,39 @@ @section Mode Line Format @cindex mode line - Each Emacs window (aside from minibuffer windows) includes a mode line, -which displays status information about the buffer displayed in the -window. The mode line contains information about the buffer, such as its -name, associated file, depth of recursive editing, and the major and -minor modes. + Each Emacs window (aside from minibuffer windows) typically has a mode +line at the bottom, which displays status information about the buffer +displayed in the window. The mode line contains information about the +buffer, such as its name, associated file, depth of recursive editing, +and major and minor modes. A window can also have a @dfn{header +line}, which is much like the mode line but appears at the top of the +window (starting in Emacs 21). - This section describes how the contents of the mode line are -controlled. We include it in this chapter because much of the + This section describes how to control the contents of the mode line +and header line. We include it in this chapter because much of the information displayed in the mode line relates to the enabled major and 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 -their mode lines appear the same (except for scrolling percentages, and -line and column numbers). +windows for the same buffer use the same @code{mode-line-format}, so +their mode lines appear the same---except for scrolling percentages, and +line and column numbers, since those depend on point and on how the +window is scrolled. @code{header-line-format} is used likewise for +header lines. - The mode line of a window is normally updated whenever a different -buffer is shown in the window, or when the buffer's modified-status -changes from @code{nil} to @code{t} or vice-versa. If you modify any of -the variables referenced by @code{mode-line-format} (@pxref{Mode Line -Variables}), or any other variables and data structures that affect how -text is displayed (@pxref{Display}), you may want to force an update of -the mode line so as to display the new information or display it in -the new way. + The mode line and header line of a window are normally updated +whenever a different buffer is shown in the window, or when the buffer's +modified-status changes from @code{nil} to @code{t} or vice-versa. If +you modify any of the variables referenced by @code{mode-line-format} +(@pxref{Mode Line Variables}), or any other variables and data +structures that affect how text is displayed (@pxref{Display}), you may +want to force an update of the mode line so as to display the new +information or display it in the new way. @c Emacs 19 feature @defun force-mode-line-update -Force redisplay of the current buffer's mode line. +Force redisplay of the current buffer's mode line and header line. @end defun The mode line is usually displayed in inverse video; see @@ -1016,6 +1055,8 @@ * Mode Line Data:: The data structure that controls the mode line. * Mode Line Variables:: Variables used in that data structure. * %-Constructs:: Putting information into a mode line. +* Properties in Mode:: Using text properties in the mode line. +* Header Lines:: Like a mode line, but at the top. @end menu @node Mode Line Data @@ -1034,6 +1075,9 @@ responsibility for the mode line format. The value of this variable controls which other variables are used to form the mode line text, and where they appear. + +If you set this variable to @code{nil} in a buffer, that buffer does not +have a mode line. (This feature was added in Emacs 21.) @end defvar A mode line construct may be as simple as a fixed string of text, but @@ -1050,6 +1094,11 @@ A mode line construct may be a list, a symbol, or a string. If the value is a list, each element may be a list, a symbol, or a string. + The mode line can display various faces, if the strings that control +it have the @code{face} property. @xref{Properties in Mode}. In +addition, the face @code{mode-line} is used as a default for the whole +mode line (@pxref{Standard Faces}). + @table @code @cindex percent symbol in mode line @item @var{string} @@ -1061,7 +1110,7 @@ @item @var{symbol} A symbol as a mode line construct stands for its value. The value of @var{symbol} is used as a mode line construct, in place of @var{symbol}. -However, the symbols @code{t} and @code{nil} are ignored; so is any +However, the symbols @code{t} and @code{nil} are ignored, as is any symbol whose value is void. There is one exception: if the value of @var{symbol} is a string, it is @@ -1072,14 +1121,19 @@ elements recursively and concatenate the results. This is the most common form of mode line construct. +@item (:eval @var{form}) +A list whose first element is the symbol @code{:eval} says to evaluate +@var{form}, and use the result as a string to display. +(This feature is new as of Emacs 21.) + @item (@var{symbol} @var{then} @var{else}) -A list whose first element is a symbol is a conditional. Its meaning -depends on the value of @var{symbol}. If the value is non-@code{nil}, -the second element, @var{then}, is processed recursively as a mode line -element. But if the value of @var{symbol} is @code{nil}, the third -element, @var{else}, is processed recursively. You may omit @var{else}; -then the mode line element displays nothing if the value of @var{symbol} -is @code{nil}. +A list whose first element is a symbol that is not a keyword specifies a +conditional. Its meaning depends on the value of @var{symbol}. If the +value is non-@code{nil}, the second element, @var{then}, is processed +recursively as a mode line element. But if the value of @var{symbol} is +@code{nil}, the third element, @var{else}, is processed recursively. +You may omit @var{else}; then the mode line element displays nothing if +the value of @var{symbol} is @code{nil}. @item (@var{width} @var{rest}@dots{}) A list whose first element is an integer specifies truncation or @@ -1124,7 +1178,7 @@ " " 'global-mode-string " %[(" - 'mode-name + '(:eval (mode-line-mode-name)) 'mode-line-process 'minor-mode-alist "%n" @@ -1268,7 +1322,7 @@ global-mode-string @group " %[(" - mode-name + (:eval (mode-line-mode-name)) mode-line-process minor-mode-alist "%n" @@ -1315,7 +1369,8 @@ The current column number of point. @item %l -The current line number of point. +The current line number of point, counting within the accessible portion +of the buffer. @item %* @samp{%} if the buffer is read only (see @code{buffer-read-only}); @* @@ -1383,6 +1438,64 @@ @code{display-time} modifies the value of @code{global-mode-string}. @end table +@node Properties in Mode +@subsection Properties in the Mode Line + + Starting in Emacs 21, certain text properties are meaningful in the +mode line. The @code{face} property affects the appearance of text; the +@code{help-echo} property associate help strings with the text, and +@code{local-map} can make the text mouse-sensitive. + + There are three ways to specify text properties for text in the mode +line: + +@enumerate +@item +Put a string with the @code{local-map} property directly into the +mode-line data structure. + +@item +Put a @code{local-map} property on a mode-line %-construct +such as @samp{%12b}; then the expansion of the %-construct +will have that same text property. + +@item +Use a list containing @code{:eval @var{form}} in the mode-line data +structure, and make @var{form} evaluate to a string that has a +@code{local-map} property. +@end enumerate + + You use the @code{local-map} property to specify a keymap. Like any +keymap, it can bind character keys and function keys; but that has no +effect, since is impossible to move point into the mode line, This +keymap can only take real effect for mouse clicks. + +@node Header Lines +@subsection Window Header Lines +@cindex header line (of a window) +@cindex window header line + + Starting in Emacs 21, a window can have a @dfn{header line} at the +top, just as it can have a mode line at the bottom. The header line +feature works just like the mode line feature, except that it's +controlled by different variables. + +@tindex header-line-format +@defvar header-line-format +This variable, local in every buffer, specifies how to display the +header line, for windows displaying the buffer. The format of the value +is the same as for @code{mode-line-format} (@xref{Mode Line Data}). +@end defvar + +@tindex default-header-line-format +@defvar default-header-line-format +This variable holds the default @code{header-line-format} for buffers +that do not override it. This is the same as @code{(default-value +'header-line-format)}. + +It is normally @code{nil}, so that ordinary buffers have no header line. +@end defvar + @node Imenu @section Imenu @@ -1390,9 +1503,10 @@ @dfn{Imenu} is a feature that lets users select a definition or section in the buffer, from a menu which lists all of them, to go directly to that location in the buffer. Imenu works by constructing a -buffer index which lists the names and positions of the definitions or -portions of in the buffer, so the user can pick one of them to move to. -This section explains how to customize Imenu for a major mode. +buffer index which lists the names and buffer positions of the +definitions, or portions of the buffer, so the user can pick one of them +to move to. This section explains how to customize Imenu for a major +mode. The usual and simplest way is to set the variable @code{imenu-generic-expression}: @@ -1413,9 +1527,10 @@ in the top level of the buffer index. The second item in the list, @var{regexp}, is a regular expression -(@pxref{Regular Expressions}); wherever it matches, that is a definition -to mention in the buffer index. The third item, @var{subexp}, indicates -which subexpression in @var{regexp} matches the definition's name. +(@pxref{Regular Expressions}); anything in the buffer that it matches is +considered a definition, to mention in the buffer index. The third +item, @var{subexp}, indicates which subexpression in @var{regexp} +matches the definition's name. An element can also look like this: @@ -1483,7 +1598,7 @@ The @code{imenu-generic-expression} patterns can then use @samp{\\sw+} instead of @samp{\\(\\sw\\|\\s_\\)+}. Note that this technique may be -inconvenient to use when the mode needs to limit the initial character +inconvenient when the mode needs to limit the initial character of a name to a smaller set of characters than are allowed in the rest of a name. @@ -1682,7 +1797,7 @@ highlighted (instead of the entire text that @var{matcher} matched). @example -;; @r{Highlight the @samp{bar} in each occurrences of @samp{fubar},} +;; @r{Highlight the @samp{bar} in each occurrence of @samp{fubar},} ;; @r{using @code{font-lock-keyword-face}.} ("fu\\(bar\\)" . 1) @end example @@ -1734,7 +1849,7 @@ ;; @r{@code{foo-bar-face} should be a variable whose value is a face.} ("foo\\|bar" 0 foo-bar-face t) -;; @r{Highlight the first subexpression within each occurrences} +;; @r{Highlight the first subexpression within each occurrence} ;; @r{that the function @code{fubar-match} finds,} ;; @r{using the face which is the value of @code{fubar-face}.} (fubar-match 1 fubar-face)
--- a/lispref/nonascii.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/nonascii.texi Fri Sep 17 06:59:04 1999 +0000 @@ -8,7 +8,7 @@ @cindex multibyte characters @cindex non-ASCII characters - This chapter covers the special issues relating to non-@sc{ASCII} + This chapter covers the special issues relating to non-@sc{ascii} characters and how they are stored in strings and buffers. @menu @@ -40,8 +40,8 @@ @cindex unibyte text In unibyte representation, each character occupies one byte and therefore the possible character codes range from 0 to 255. Codes 0 -through 127 are @sc{ASCII} characters; the codes from 128 through 255 -are used for one non-@sc{ASCII} character set (you can choose which +through 127 are @sc{ascii} characters; the codes from 128 through 255 +are used for one non-@sc{ascii} character set (you can choose which character set by setting the variable @code{nonascii-insert-offset}). @cindex leading code @@ -132,30 +132,30 @@ acceptable because the buffer's representation is a choice made by the user that cannot be overridden automatically. - Converting unibyte text to multibyte text leaves @sc{ASCII} characters -unchanged, and likewise 128 through 159. It converts the non-@sc{ASCII} + Converting unibyte text to multibyte text leaves @sc{ascii} characters +unchanged, and likewise 128 through 159. It converts the non-@sc{ascii} codes 160 through 255 by adding the value @code{nonascii-insert-offset} to each character code. By setting this variable, you specify which character set the unibyte characters correspond to (@pxref{Character Sets}). For example, if @code{nonascii-insert-offset} is 2048, which is @code{(- (make-char 'latin-iso8859-1) 128)}, then the unibyte -non-@sc{ASCII} characters correspond to Latin 1. If it is 2688, which +non-@sc{ascii} characters correspond to Latin 1. If it is 2688, which is @code{(- (make-char 'greek-iso8859-7) 128)}, then they correspond to Greek letters. - Converting multibyte text to unibyte is simpler: it performs -logical-and of each character code with 255. If -@code{nonascii-insert-offset} has a reasonable value, corresponding to -the beginning of some character set, this conversion is the inverse of -the other: converting unibyte text to multibyte and back to unibyte -reproduces the original unibyte text. + Converting multibyte text to unibyte is simpler: it discards all but +the low 8 bits of each character code. If @code{nonascii-insert-offset} +has a reasonable value, corresponding to the beginning of some character +set, this conversion is the inverse of the other: converting unibyte +text to multibyte and back to unibyte reproduces the original unibyte +text. @defvar nonascii-insert-offset @tindex nonascii-insert-offset -This variable specifies the amount to add to a non-@sc{ASCII} character +This variable specifies the amount to add to a non-@sc{ascii} character when converting unibyte text to multibyte. It also applies when @code{self-insert-command} inserts a character in the unibyte -non-@sc{ASCII} range, 128 through 255. However, the function +non-@sc{ascii} range, 128 through 255. However, the function @code{insert-char} does not perform this conversion. The right value to use to select character set @var{cs} is @code{(- @@ -245,7 +245,7 @@ codes for multibyte representation range from 0 to 524287, but not all values in that range are valid. In particular, the values 128 through 255 are not legitimate in multibyte text (though they can occur in ``raw -bytes''; @pxref{Explicit Encoding}). Only the @sc{ASCII} codes 0 +bytes''; @pxref{Explicit Encoding}). Only the @sc{ascii} codes 0 through 127 are fully legitimate in both representations. @defun char-valid-p charcode @@ -281,7 +281,7 @@ @defun charsetp object @tindex charsetp -Return @code{t} if @var{object} is a character set name symbol, +Returns @code{t} if @var{object} is a symbol that names a character set, @code{nil} otherwise. @end defun @@ -296,6 +296,15 @@ belongs to. @end defun +@defun charset-plist charset +@tindex charset-plist +This function returns the charset property list of the character set +@var{charset}. Although @var{charset} is a symbol, this is not the same +as the property list of that symbol. Charset properties are used for +special purposes within Emacs; for example, @code{x-charset-registry} +helps determine which fonts to use (@pxref{Font Selection}). +@end defun + @node Chars and Bytes @section Characters and Bytes @cindex bytes and characters @@ -304,7 +313,7 @@ @cindex dimension (of character set) In multibyte representation, each character occupies one or more bytes. Each character set has an @dfn{introduction sequence}, which is -normally one or two bytes long. (Exception: the @sc{ASCII} character +normally one or two bytes long. (Exception: the @sc{ascii} character set has a zero-length introduction sequence.) The introduction sequence is the beginning of the byte sequence for any character in the character set. The rest of the character's bytes distinguish it from the other @@ -354,7 +363,7 @@ @result{} (ascii 65) @end example -Unibyte non-@sc{ASCII} characters are considered as part of +Unibyte non-@sc{ascii} characters are considered as part of the @code{ascii} character set: @example @@ -418,7 +427,7 @@ @itemize @bullet @item -When a unibyte buffer contains non-@sc{ASCII} characters. +When a unibyte buffer contains non-@sc{ascii} characters. @item When a multibyte buffer contains invalid byte-sequences (raw bytes). @@ -445,10 +454,10 @@ translation tables; there are also default translation tables which apply to all other coding systems. -@defun make-translation-table translations -This function returns a translation table based on the arguments -@var{translations}. Each argument---each element of -@var{translations}---should be a list of the form @code{(@var{from} +@defun make-translation-table &rest translations +This function returns a translation table based on the argument +@var{translations}. Each element of +@var{translations} should be a list of the form @code{(@var{from} . @var{to})}; this says to translate the character @var{from} into @var{to}. @@ -495,7 +504,8 @@ character code conversion and end-of-line conversion as specified by a particular @dfn{coding system}. - How to define a coding system is an arcane matter, not yet documented. + How to define a coding system is an arcane matter, and is not +documented here. @menu * Coding System Basics:: @@ -523,16 +533,15 @@ (Russian) alphabet: ISO, Alternativnyj, and KOI8. Most coding systems specify a particular character code for -conversion, but some of them leave this unspecified---to be chosen -heuristically based on the data. +conversion, but some of them leave the choice unspecified---to be chosen +heuristically for each file, based on the data. @cindex end of line conversion @dfn{End of line conversion} handles three different conventions used on various systems for representing end of line in files. The Unix convention is to use the linefeed character (also called newline). The -DOS convention is to use the two character sequence, carriage-return -linefeed, at the end of a line. The Mac convention is to use just -carriage-return. +DOS convention is to use a carriage-return and a linefeed at the end of +a line. The Mac convention is to use just carriage-return. @cindex base coding system @cindex variant coding system @@ -610,10 +619,14 @@ @defvar save-buffer-coding-system @tindex save-buffer-coding-system This variable specifies the coding system for saving the buffer---but it -is not used for @code{write-region}. When saving the buffer asks the -user to specify a different coding system, and -@code{save-buffer-coding-system} was used, then it is updated to the -coding system that was specified. +is not used for @code{write-region}. + +When a command to save the buffer starts out to use +@code{save-buffer-coding-system}, and that coding system cannot handle +the actual text in the buffer, the command asks the user to choose +another coding system. After that happens, the command also updates +@code{save-buffer-coding-system} to represent the coding system that the +user specified. @end defvar @defvar last-coding-system-used @@ -623,8 +636,8 @@ functions (@pxref{Explicit Encoding}) set it too. @strong{Warning:} Since receiving subprocess output sets this variable, -it can change whenever Emacs waits; therefore, you should use copy the -value shortly after the function call which stores the value you are +it can change whenever Emacs waits; therefore, you should copy the +value shortly after the function call that stores the value you are interested in. @end defvar @@ -634,7 +647,7 @@ @node Lisp and Coding Systems @subsection Coding Systems in Lisp - Here are Lisp facilities for working with coding systems; + Here are the Lisp facilities for working with coding systems: @defun coding-system-list &optional base-only @tindex coding-system-list @@ -711,7 +724,7 @@ return value is just one coding system, the one that is highest in priority. -If the region contains only @sc{ASCII} characters, the value +If the region contains only @sc{ascii} characters, the value is @code{undecided} or @code{(undecided)}. @end defun @@ -788,13 +801,14 @@ names that match @var{pattern}. The @sc{cdr} of the element, @var{coding}, should be either a coding -system, a cons cell containing two coding systems, or a function symbol. -If @var{val} is a coding system, that coding system is used for both -reading the file and writing it. If @var{val} is a cons cell containing -two coding systems, its @sc{car} specifies the coding system for -decoding, and its @sc{cdr} specifies the coding system for encoding. +system, a cons cell containing two coding systems, or a function name (a +symbol with a function definition). If @var{coding} is a coding system, +that coding system is used for both reading the file and writing it. If +@var{coding} is a cons cell containing two coding systems, its @sc{car} +specifies the coding system for decoding, and its @sc{cdr} specifies the +coding system for encoding. -If @var{val} is a function symbol, the function must return a coding +If @var{coding} is a function name, the function must return a coding system or a cons cell containing two coding systems. This value is used as described above. @end defvar @@ -810,8 +824,8 @@ other coding systems later using @code{set-process-coding-system}. @end defvar - @strong{Warning:} Coding systems such as @code{undecided} which -determine the coding system from the data do not work entirely reliably + @strong{Warning:} Coding systems such as @code{undecided}, which +determine the coding system from the data, do not work entirely reliably with asynchronous subprocess output. This is because Emacs handles asynchronous subprocess output in batches, as it arrives. If the coding system leaves the character code conversion unspecified, or leaves the @@ -859,13 +873,14 @@ @var{encoding-system} is the coding system for encoding (in case @var{operation} does encoding). -The argument @var{operation} should be an Emacs I/O primitive: +The argument @var{operation} should be a symbol, one of @code{insert-file-contents}, @code{write-region}, @code{call-process}, @code{call-process-region}, @code{start-process}, or -@code{open-network-stream}. +@code{open-network-stream}. These are the names of the Emacs I/O primitives +that can do coding system conversion. The remaining arguments should be the same arguments that might be given -to that I/O primitive. Depending on which primitive, one of those +to that I/O primitive. Depending on the primitive, one of those arguments is selected as the @dfn{target}. For example, if @var{operation} does file I/O, whichever argument specifies the file name is the target. For subprocess primitives, the process name is the @@ -1079,13 +1094,15 @@ @cindex text files and binary files @cindex binary files and text files - Emacs on MS-DOS and on MS-Windows recognizes certain file names as -text files or binary files. By ``binary file'' we mean a file of -literal byte values that are not necessary meant to be characters. -Emacs does no end-of-line conversion and no character code conversion -for a binary file. Meanwhile, when you create a new file which is -marked by its name as a ``text file'', Emacs uses DOS end-of-line -conversion. + On MS-DOS and Microsoft Windows, Emacs guesses the appropriate +end-of-line conversion for a file by looking at the file's name. This +feature classifies fils as @dfn{text files} and @dfn{binary files}. By +``binary file'' we mean a file of literal byte values that are not +necessarily meant to be characters; Emacs does no end-of-line conversion +and no character code conversion for them. On the other hand, the bytes +in a text file are intended to represent characters; when you create a +new file whose name implies that it is a text file, Emacs uses DOS +end-of-line conversion. @defvar buffer-file-type This variable, automatically buffer-local in each buffer, records the @@ -1108,7 +1125,7 @@ compute which. If it is a function, then it is called with a single argument (the file name) and should return @code{t} or @code{nil}. -Emacs when running on MS-DOS or MS-Windows checks this alist to decide +When running on MS-DOS or MS-Windows, Emacs checks this alist to decide which coding system to use when reading a file. For a text file, @code{undecided-dos} is used. For a binary file, @code{no-conversion} is used. @@ -1131,9 +1148,9 @@ @section Input Methods @cindex input methods - @dfn{Input methods} provide convenient ways of entering non-@sc{ASCII} + @dfn{Input methods} provide convenient ways of entering non-@sc{ascii} characters from the keyboard. Unlike coding systems, which translate -non-@sc{ASCII} characters to and from encodings meant to be read by +non-@sc{ascii} characters to and from encodings meant to be read by programs, input methods provide human-friendly commands. (@xref{Input Methods,,, emacs, The GNU Emacs Manual}, for information on how users use input methods to enter text.) How to define input methods is not
--- a/lispref/numbers.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/numbers.texi Fri Sep 17 06:59:04 1999 +0000 @@ -40,14 +40,14 @@ -2**27 @end ifinfo @tex -$-2^{27}$ +@math{-2^{27}} @end tex to @ifinfo 2**27 - 1), @end ifinfo @tex -$2^{27}-1$), +@math{2^{27}-1}), @end tex but some machines may provide a wider range. Many examples in this chapter assume an integer has 28 bits. @@ -312,6 +312,8 @@ @defun max number-or-marker &rest numbers-or-markers This function returns the largest of its arguments. +If any of the argument is floating-point, the value is returned +as floating point, even if it was given as an integer. @example (max 20) @@ -319,12 +321,14 @@ (max 1 2.5) @result{} 2.5 (max 1 3 2.5) - @result{} 3 + @result{} 3.0 @end example @end defun @defun min number-or-marker &rest numbers-or-markers This function returns the smallest of its arguments. +If any of the argument is floating-point, the value is returned +as floating point, even if it was given as an integer. @example (min -4 1) @@ -958,14 +962,14 @@ @minus{}pi/2 @end ifinfo @tex -$-\pi/2$ +@math{-\pi/2} @end tex and @ifinfo pi/2 @end ifinfo @tex -$\pi/2$ +@math{\pi/2} @end tex (inclusive) whose sine is @var{arg}; if, however, @var{arg} is out of range (outside [-1, 1]), then the result is a NaN. @@ -977,7 +981,7 @@ pi @end ifinfo @tex -$\pi$ +@math{\pi} @end tex (inclusive) whose cosine is @var{arg}; if, however, @var{arg} is out of range (outside [-1, 1]), then the result is a NaN. @@ -989,14 +993,14 @@ @minus{}pi/2 @end ifinfo @tex -$-\pi/2$ +@math{-\pi/2} @end tex and @ifinfo pi/2 @end ifinfo @tex -$\pi/2$ +@math{\pi/2} @end tex (exclusive) whose tangent is @var{arg}. @end defun @@ -1004,14 +1008,14 @@ @defun exp arg This is the exponential function; it returns @tex -$e$ +@math{e} @end tex @ifinfo @i{e} @end ifinfo to the power @var{arg}. @tex -$e$ +@math{e} @end tex @ifinfo @i{e} @@ -1024,7 +1028,7 @@ This function returns the logarithm of @var{arg}, with base @var{base}. If you don't specify @var{base}, the base @tex -$e$ +@math{e} @end tex @ifinfo @i{e} @@ -1085,9 +1089,9 @@ -1457731, and the second one always returns -7692030. This repeatability is helpful for debugging. -If you want truly unpredictable random numbers, execute @code{(random -t)}. This chooses a new seed based on the current time of day and on -Emacs's process @sc{id} number. +If you want random numbers that don't always come out the same, execute +@code{(random t)}. This chooses a new seed based on the current time of +day and on Emacs's process @sc{id} number. @defun random &optional limit This function returns a pseudo-random integer. Repeated calls return a
--- a/lispref/objects.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/objects.texi Fri Sep 17 06:59:04 1999 +0000 @@ -25,7 +25,7 @@ which all other types are constructed, are called @dfn{primitive types}. Each object belongs to one and only one primitive type. These types include @dfn{integer}, @dfn{float}, @dfn{cons}, @dfn{symbol}, -@dfn{string}, @dfn{vector}, @dfn{subr}, @dfn{byte-code function}, plus +@dfn{string}, @dfn{vector}, @dfn{subr}, and @dfn{byte-code function}, plus several special types, such as @dfn{buffer}, that are related to editing. (@xref{Editing Types}.) @@ -52,6 +52,7 @@ * Comments:: Comments and their formatting conventions. * Programming Types:: Types found in all Lisp systems. * Editing Types:: Types specific to Emacs. +* Circular Objects:: Read syntax for circular structure. * Type Predicates:: Tests related to types. * Equality Predicates:: Tests of equality between any two objects. @end menu @@ -146,6 +147,7 @@ * Vector Type:: One-dimensional arrays. * Char-Table Type:: One-dimensional sparse arrays indexed by characters. * Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}. +* Hash Table Type:: Super-fast lookup tables. * Function Type:: A piece of executable code you can call from elsewhere. * Macro Type:: A method of expanding an expression into another expression, more fundamental but less pretty. @@ -164,14 +166,14 @@ -2**27 @end ifinfo @tex -$-2^{27}$ +@math{-2^{27}} @end tex to @ifinfo 2**27 - 1) @end ifinfo @tex -$2^{28}-1$) +@math{2^{28}-1}) @end tex on most machines. (Some machines may provide a wider range.) It is important to note that the Emacs Lisp arithmetic functions do not check @@ -187,7 +189,7 @@ @group -1 ; @r{The integer -1.} 1 ; @r{The integer 1.} -1. ; @r{Also The integer 1.} +1. ; @r{Also the integer 1.} +1 ; @r{Also the integer 1.} 268435457 ; @r{Also the integer 1 on a 28-bit implementation.} @end group @@ -212,7 +214,7 @@ @node Character Type @subsection Character Type -@cindex @sc{ASCII} character codes +@cindex @sc{ascii} character codes A @dfn{character} in Emacs Lisp is nothing more than an integer. In other words, characters are represented by their character codes. For @@ -290,6 +292,7 @@ ?\r @result{} 13 ; @r{carriage return, @key{RET}, @kbd{C-m}} ?\e @result{} 27 ; @r{escape character, @key{ESC}, @kbd{C-[}} ?\\ @result{} 92 ; @r{backslash character, @kbd{\}} +?\d @result{} 127 ; @r{delete character, @key{DEL}} @end example @cindex escape sequence @@ -312,17 +315,17 @@ @end example In strings and buffers, the only control characters allowed are those -that exist in @sc{ASCII}; but for keyboard input purposes, you can turn +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 +codes for these non-@sc{ascii} control characters include the @tex -$2^{26}$ +@math{2^{26}} @end tex @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} +character. Ordinary terminals have no way of generating non-@sc{ascii} control characters, but you can generate them straightforwardly using X and other window systems. @@ -349,7 +352,7 @@ A @dfn{meta character} is a character typed with the @key{META} modifier key. The integer that represents such a character has the @tex -$2^{27}$ +@math{2^{27}} @end tex @ifinfo 2**27 @@ -360,14 +363,14 @@ In a string, the @tex -$2^{7}$ +@math{2^{7}} @end tex @ifinfo 2**7 @end ifinfo bit attached to an ASCII character indicates a meta character; thus, 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} +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 outside of strings as well.) @@ -379,11 +382,11 @@ @samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}. The case of a graphic character is indicated by its character code; -for example, @sc{ASCII} distinguishes between the characters @samp{a} -and @samp{A}. But @sc{ASCII} has no way to represent whether a control +for example, @sc{ascii} distinguishes between the characters @samp{a} +and @samp{A}. But @sc{ascii} has no way to represent whether a control character is upper case or lower case. Emacs uses the @tex -$2^{25}$ +@math{2^{25}} @end tex @ifinfo 2**25 @@ -405,7 +408,7 @@ @kbd{Alt-Hyper-Meta-x}. @tex Numerically, the -bit values are $2^{22}$ for alt, $2^{23}$ for super and $2^{24}$ for hyper. +bit values are @math{2^{22}} for alt, @math{2^{23}} for super and @math{2^{24}} for hyper. @end tex @ifinfo Numerically, the @@ -420,9 +423,9 @@ mark followed by a backslash and the octal character code (up to three octal digits); thus, @samp{?\101} for the character @kbd{A}, @samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the -character @kbd{C-b}. Although this syntax can represent any @sc{ASCII} +character @kbd{C-b}. Although this syntax can represent any @sc{ascii} character, it is preferred only when the precise octal value is more -important than the @sc{ASCII} representation. +important than the @sc{ascii} representation. @example @group @@ -520,6 +523,11 @@ @end group @end example +@cindex @samp{#:} read syntax + Normally the Lisp reader interns all symbols (@pxref{Creating +Symbols}). To prevent interning, you can write @samp{#:} before the +name of the symbol. + @node Sequence Type @subsection Sequence Types @@ -559,7 +567,7 @@ A @dfn{cons cell} is an object that consists of two slots, called the @sc{car} slot and the @sc{cdr} slot. Each slot can @dfn{hold} or -@dfn{refer to} any Lisp object. We also say that the ``the @sc{car} of +@dfn{refer to} any Lisp object. We also say that ``the @sc{car} of this cons cell is'' whatever object its @sc{car} slot currently holds, and likewise for the @sc{cdr}. @@ -794,7 +802,8 @@ first element, @code{rose} is the key and @code{red} is the value. @xref{Association Lists}, for a further explanation of alists and for -functions that work on alists. +functions that work on alists. @xref{Hash Tables}, for another kind of +lookup table, which is much faster for handling a large number of keys. @node Array Type @subsection Array Type @@ -884,9 +893,9 @@ @node Non-ASCII in Strings @subsubsection Non-ASCII Characters in Strings - You can include a non-@sc{ASCII} international character in a string + You can include a non-@sc{ascii} international character in a string constant by writing it literally. There are two text representations -for non-@sc{ASCII} characters in Emacs strings (and in buffers): unibyte +for non-@sc{ascii} characters in Emacs strings (and in buffers): unibyte and multibyte. If the string constant is read from a multibyte source, such as a multibyte buffer or string, or a file that would be visited as multibyte, then the character is read as a multibyte character, and that @@ -895,7 +904,7 @@ string unibyte. You can also represent a multibyte non-@sc{ASCII} character with its -character code, using a hex escape, @samp{\x@var{nnnnnnn}}, with as many +character code: use a hex escape, @samp{\x@var{nnnnnnn}}, with as many digits as necessary. (Multibyte non-@sc{ASCII} character codes are all greater than 256.) Any character which is not a valid hex digit terminates this construct. If the next character in the string could be @@ -906,7 +915,7 @@ character to the string, but it does terminate the preceding hex escape. Using a multibyte hex escape forces the string to multibyte. You can -represent a unibyte non-@sc{ASCII} character with its character code, +represent a unibyte non-@sc{ascii} character with its character code, which must be in the range from 128 (0200 octal) to 255 (0377 octal). This forces a unibyte string. @@ -925,16 +934,16 @@ However, not all of the characters you can write with backslash escape-sequences are valid in strings. The only control characters that -a string can hold are the @sc{ASCII} control characters. Strings do not -distinguish case in @sc{ASCII} control characters. +a string can hold are the @sc{ascii} control characters. Strings do not +distinguish case in @sc{ascii} control characters. Properly speaking, strings cannot hold meta characters; but when a string is to be used as a key sequence, there is a special convention -that provides a way to represent meta versions of @sc{ASCII} characters in a +that provides a way to represent meta versions of @sc{ascii} characters in a string. If you use the @samp{\M-} syntax to indicate a meta character in a string constant, this sets the @tex -$2^{7}$ +@math{2^{7}} @end tex @ifinfo 2**7 @@ -1043,7 +1052,7 @@ A @dfn{bool-vector} is a one-dimensional array of elements that must be @code{t} or @code{nil}. - The printed representation of a Bool-vector is like a string, except + The printed representation of a bool-vector is like a string, except that it begins with @samp{#&} followed by the length. The string constant that follows actually specifies the contents of the bool-vector as a bitmap---each ``character'' in the string contains 8 bits, which @@ -1063,6 +1072,19 @@ @result{} t @end example +@node Hash Table Type +@subsection Hash Table Type + + A hash table is a very fast kind of lookup table, somewhat like an +alist in that it maps keys to corresponding values, but much faster. +Hash tables are a new feature in Emacs 21; they have no read syntax, and +print using hash notation. @xref{Hash Tables}. + +@example +(make-hash-table) + @result{} #<hash-table 'eql nil 0/65 0x83af980> +@end example + @node Function Type @subsection Function Type @@ -1156,11 +1178,11 @@ @subsection Autoload Type An @dfn{autoload object} is a list whose first element is the symbol -@code{autoload}. It is stored as the function definition of a symbol as -a placeholder for the real definition; it says that the real definition -is found in a file of Lisp code that should be loaded when necessary. -The autoload object contains the name of the file, plus some other -information about the real definition. +@code{autoload}. It is stored as the function definition of a symbol, +where it serves as a placeholder for the real definition. The autoload +object says that the real definition is found in a file of Lisp code +that should be loaded when necessary. It contains the name of the file, +plus some other information about the real definition. After the file has been loaded, the symbol should have a new function definition that is not an autoload object. The new definition is then @@ -1207,9 +1229,9 @@ The contents of a buffer are much like a string, but buffers are not used like strings in Emacs Lisp, and the available operations are different. For example, you can insert text efficiently into an -existing buffer, whereas ``inserting'' text into a string requires -concatenating substrings, and the result is an entirely new string -object. +existing buffer, altering the buffer's contents, whereas ``inserting'' +text into a string requires concatenating substrings, and the result is +an entirely new string object. Each buffer has a designated position called @dfn{point} (@pxref{Positions}). At any time, one buffer is the @dfn{current @@ -1431,6 +1453,69 @@ @xref{Overlays}, for how to create and use overlays. +@node Circular Objects +@section Read Syntax for Circular Objects +@cindex circular structure, read syntax +@cindex shared structure, read syntax +@cindex @samp{#@var{n}=} read syntax +@cindex @samp{#@var{n}#} read syntax + + In Emacs 21, to represent shared or circular structure within a +complex of Lisp objects, you can use the reader constructs +@samp{#@var{n}=} and @samp{#@var{n}#}. + + Use @code{#@var{n}=} before an object to label it for later reference; +subsequently, you can use @code{#@var{n}#} to refer the same object in +another place. Here, @var{n} is some integer. For example, here is how +to make a list in which the first element recurs as the third element: + +@example +(#1=(a) b #1#) +@end example + +@noindent +This differs from ordinary syntax such as this + +@example +((a) b (a)) +@end example + +@noindent +which would result in a list whose first and third elements +look alike but are not the same Lisp object. This shows the difference: + +@example +(prog1 nil + (setq x '(#1=(a) b #1#))) +(eq (nth 0 x) (nth 2 x)) + @result{} t +(setq x '((a) b (a))) +(eq (nth 0 x) (nth 2 x)) + @result{} nil +@end example + + You can also use the same syntax to make a circular structure, which +appears as an ``element'' within itself. Here is an example: + +@example +#1=(a #1#) +@end example + +@noindent +This makes a list whose second element is the list itself. +Here's how you can see that it really works: + +@example +(prog1 nil + (setq x '#1=(a #1#))) +(eq x (cadr x)) + @result{} t +@end example + + The Lisp printer can produce this syntax to record circular and shared +structure in a Lisp object, if you bind the variable @code{print-circle} +to a non-@code{nil} value. @xref{Output Variables}. + @node Type Predicates @section Type Predicates @cindex predicates @@ -1764,7 +1849,7 @@ Comparison of strings is case-sensitive, but does not take account of text properties---it compares only the characters in the strings. A unibyte string never equals a multibyte string unless the -contents are entirely @sc{ASCII} (@pxref{Text Representations}). +contents are entirely @sc{ascii} (@pxref{Text Representations}). @example @group
--- a/lispref/os.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/os.texi Fri Sep 17 06:59:04 1999 +0000 @@ -15,7 +15,7 @@ pertaining to the terminal and the screen. @menu -* Starting Up:: Customizing Emacs start-up processing. +* Starting Up:: Customizing Emacs startup processing. * Getting Out:: How exiting works (permanent or temporary). * System Environment:: Distinguish the name and kind of system. * User Identification:: Finding the name and user id of the user. @@ -25,6 +25,7 @@ * Timers:: Setting a timer to call a function at a certain time. * Terminal Input:: Recording terminal input for debugging. * Terminal Output:: Recording terminal output for debugging. +* Sound Output:: Playing sounds on the computer's speaker. * Special Keysyms:: Defining system-specific key symbols for X windows. * Flow Control:: How to turn output flow control on or off. * Batch Mode:: Running Emacs without terminal interaction. @@ -37,17 +38,17 @@ can customize these actions. @menu -* Start-up Summary:: Sequence of actions Emacs performs at start-up. +* Startup Summary:: Sequence of actions Emacs performs at startup. * Init File:: Details on reading the init file (@file{.emacs}). * Terminal-Specific:: How the terminal-specific Lisp file is read. -* Command Line Arguments:: How command line arguments are processed, +* Command-Line Arguments:: How command-line arguments are processed, and how you can customize them. @end menu -@node Start-up Summary -@subsection Summary: Sequence of Actions at Start Up +@node Startup Summary +@subsection Summary: Sequence of Actions at Startup @cindex initialization -@cindex start up of Emacs +@cindex startup of Emacs @cindex @file{startup.el} The order of operations performed (in @file{startup.el}) by Emacs when @@ -86,7 +87,7 @@ @item It loads the file @file{~/.emacs}, unless @samp{-q} or @samp{-batch} was specified on the command line. The @samp{-u} option can specify another -user name whose home directory should be used instead of @file{~}. +user whose home directory should be used instead of @file{~}. @item It loads the library @file{default}, unless @code{inhibit-default-init} @@ -127,7 +128,7 @@ @item It displays copyleft, nonwarranty, and basic use information, provided -there were no remaining command line arguments (a few steps above), +there were no remaining command-line arguments (a few steps above), the value of @code{inhibit-startup-message} is @code{nil}, and the buffer is still empty. @end enumerate @@ -170,12 +171,12 @@ @cindex @file{.emacs} When you start Emacs, it normally attempts to load the file -@file{.emacs} from your home directory. This file, if it exists, must -contain Lisp code. It is called your @dfn{init file}. The command line -switches @samp{-q} and @samp{-u} affect the use of the init file; -@samp{-q} says not to load an init file, and @samp{-u} says to load a -specified user's init file instead of yours. @xref{Entering Emacs,,, -emacs, The GNU Emacs Manual}. +@file{.emacs} from your home directory. This file is called your +@dfn{init file}. If it exists, it must contain Lisp code. The +command-line switches @samp{-q} and @samp{-u} affect the use of the init +file; @samp{-q} says not to load an init file, and @samp{-u} says to +load a specified user's init file instead of yours. @xref{Entering +Emacs,,, emacs, The GNU Emacs Manual}. @cindex default init file A site may have a @dfn{default init file}, which is the library named @@ -200,9 +201,8 @@ @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} -file load the other file using @code{load} (@pxref{Loading}). +can make it load faster by renaming it to @file{.emacs.el} +and then byte-compiling it (@pxref{Byte Compilation}). @xref{Init File Examples,,, emacs, The GNU Emacs Manual}, for examples of how to make various commonly desired customizations in your @@ -234,7 +234,8 @@ Each terminal type can have its own Lisp library that Emacs loads when run on that type of terminal. The library's name is constructed by concatenating the value of the variable @code{term-file-prefix} and the -terminal type. Normally, @code{term-file-prefix} has the value +terminal type (specified by the environment variable @code{TERM}). +Normally, @code{term-file-prefix} has the value @code{"term/"}; changing this is not recommended. Emacs finds the file in the normal manner, by searching the @code{load-path} directories, and trying the @samp{.elc} and @samp{.el} suffixes. @@ -279,6 +280,9 @@ @file{.emacs} file if you do not wish to load the terminal-initialization file. To do this, put the following in your @file{.emacs} file: @code{(setq term-file-prefix nil)}. + +On MS-DOS, if the environment variable @code{TERM} is not set, Emacs +uses @samp{internal} as the terminal type. @end defvar @defvar term-setup-hook @@ -293,27 +297,27 @@ See @code{window-setup-hook} in @ref{Window Systems}, for a related feature. -@node Command Line Arguments -@subsection Command Line Arguments -@cindex command line arguments +@node Command-Line Arguments +@subsection Command-Line Arguments +@cindex command-line arguments - You can use command line arguments to request various actions when you + You can use command-line arguments to request various actions when you start Emacs. Since you do not need to start Emacs more than once per day, and will often leave your Emacs session running longer than that, -command line arguments are hardly ever used. As a practical matter, it +command-line arguments are hardly ever used. As a practical matter, it is best to avoid making the habit of using them, since this habit would encourage you to kill and restart Emacs unnecessarily often. These options exist for two reasons: to be compatible with other editors (for invocation by other programs) and to enable shell scripts to run specific Lisp programs. - This section describes how Emacs processes command line arguments, + This section describes how Emacs processes command-line arguments, and how you can customize them. @ignore (Note that some other editors require you to start afresh each time you want to edit a file. With this kind of editor, you will probably -specify the file as a command line argument. The recommended way to +specify the file as a command-line argument. The recommended way to use GNU Emacs is to start it only once, just after you log in, and do all your editing in the same Emacs process. Each time you want to edit a different file, you visit it with the existing Emacs, which eventually @@ -333,19 +337,19 @@ If you redump Emacs by calling @code{dump-emacs}, you may wish to set this variable to @code{nil} first in order to cause the new dumped Emacs -to process its new command line arguments. +to process its new command-line arguments. @end defvar @defvar command-switch-alist @cindex switches on command line @cindex options on command line -@cindex command line options +@cindex command-line options The value of this variable is an alist of user-defined command-line options and associated handler functions. This variable exists so you can add elements to it. -A @dfn{command line option} is an argument on the command line of the -form: +A @dfn{command-line option} is an argument on the command line, which +has the form: @example -@var{option} @@ -357,8 +361,10 @@ (@var{option} . @var{handler-function}) @end example -The @var{handler-function} is called to handle @var{option} and receives -the option name as its sole argument. +The @sc{car}, @var{option}, is a string, the name of a command-line +option (not including the initial hyphen). The @var{handler-function} +is called to handle @var{option}, and receives the option name as its +sole argument. In some cases, the option is followed in the command line by an argument. In these cases, the @var{handler-function} can find all the @@ -366,14 +372,14 @@ @code{command-line-args-left}. (The entire list of command-line arguments is in @code{command-line-args}.) -The command line arguments are parsed by the @code{command-line-1} +The command-line arguments are parsed by the @code{command-line-1} function in the @file{startup.el} file. See also @ref{Command Switches, , Command Line Switches and Arguments, emacs, The GNU Emacs Manual}. @end defvar @defvar command-line-args -The value of this variable is the list of command line arguments passed +The value of this variable is the list of command-line arguments passed to Emacs. @end defvar @@ -436,10 +442,10 @@ @end defun All the information in the Emacs process, aside from files that have -been saved, is lost when the Emacs is killed. Because killing Emacs -inadvertently can lose a lot of work, Emacs queries for confirmation -before actually terminating if you have buffers that need saving or -subprocesses that are running. This is done in the function +been saved, is lost when the Emacs process is killed. Because killing +Emacs inadvertently can lose a lot of work, Emacs queries for +confirmation before actually terminating if you have buffers that need +saving or subprocesses that are running. This is done in the function @code{save-buffers-kill-emacs}. @defvar kill-emacs-query-functions @@ -475,7 +481,7 @@ may not have a parent that can resume it again, and in any case you can give input to some other job such as a shell merely by moving to a different window. Therefore, suspending is not allowed when Emacs is using -a window system. +a window system (X Windows or MS Windows). @defun suspend-emacs string This function stops Emacs and returns control to the superior process. @@ -545,11 +551,12 @@ @end defun @defvar suspend-hook -This variable is a normal hook run before suspending. +This variable is a normal hook that Emacs runs before suspending. @end defvar @defvar suspend-resume-hook -This variable is a normal hook run after suspending. +This variable is a normal hook that Emacs runs on resuming +after a suspension. @end defvar @node System Environment @@ -598,7 +605,9 @@ Silicon Graphics Irix system. @item ms-dos -Microsoft MS-DOS ``operating system.'' +Microsoft MS-DOS ``operating system.'' Emacs compiled with DJGPP for +MS-DOS binds @code{system-type} to @code{ms-dos} even when you run it on +MS-Windows. @item next-mach NeXT Mach-based system. @@ -616,7 +625,8 @@ VAX VMS. @item windows-nt -Microsoft windows NT. +Microsoft windows NT. The same executable supports Windows 9X, but the +value of @code{system-type} is @code{windows-nt} in either case. @item xenix SCO Xenix 386. @@ -710,7 +720,7 @@ 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. +and MS-Windows. @end defvar @defvar invocation-name @@ -770,10 +780,11 @@ @defun setprv privilege-name &optional setp getprv This function sets or resets a VMS privilege. (It does not exist on -Unix.) The first arg is the privilege name, as a string. The second -argument, @var{setp}, is @code{t} or @code{nil}, indicating whether the -privilege is to be turned on or off. Its default is @code{nil}. The -function returns @code{t} if successful, @code{nil} otherwise. +other systems.) The first argument is the privilege name, as a string. +The second argument, @var{setp}, is @code{t} or @code{nil}, indicating +whether the privilege is to be turned on or off. Its default is +@code{nil}. The function returns @code{t} if successful, @code{nil} +otherwise. If the third argument, @var{getprv}, is non-@code{nil}, @code{setprv} does not change the privilege, but returns @code{t} or @code{nil} @@ -785,7 +796,7 @@ @defvar init-file-user This variable says which user's init files should be used by Emacs---or -@code{nil} if none. The value reflects command line options such as +@code{nil} if none. The value reflects command-line options such as @samp{-q} or @samp{-u @var{user}}. Lisp packages that load files of customizations, or any other sort of @@ -830,8 +841,9 @@ @defun user-full-name &optional uid This function returns the full name of the logged-in user---or the value -of the environment variables @code{NAME}, if that is set. +of the environment variable @code{NAME}, if that is set. +@c "Bil" is the correct spelling. @example @group (user-full-name) @@ -907,7 +919,7 @@ This function returns the system's time value as a list of three integers: @code{(@var{high} @var{low} @var{microsec})}. The integers @var{high} and @var{low} combine to give the number of seconds since -0:00 January 1, 1970, which is +0:00 January 1, 1970 (local time), which is @ifinfo @var{high} * 2**16 + @var{low}. @end ifinfo @@ -916,8 +928,8 @@ @end tex The third element, @var{microsec}, gives the microseconds since the -start of the current second (or 0 for systems that return time only on -the resolution of a second). +start of the current second (or 0 for systems that return time with +the resolution of only one second). The first two elements can be compared with file time values such as you get with the function @code{file-attributes}. @xref{File Attributes}. @@ -931,7 +943,7 @@ The value has the form @code{(@var{offset} @var{name})}. Here @var{offset} is an integer giving the number of seconds ahead of UTC (east of Greenwich). A negative value means west of Greenwich. The -second element, @var{name} is a string giving the name of the time +second element, @var{name}, is a string giving the name of the time zone. Both elements change when daylight savings time begins or ends; if the user has specified a time zone that does not use a seasonal time adjustment, then the value is constant through time. @@ -998,7 +1010,7 @@ @item %H This stands for the hour (00-23). @item %I -This stands for the hour (00-12). +This stands for the hour (01-12). @item %j This stands for the day of the year (001-366). @item %k @@ -1018,7 +1030,7 @@ @item %R This is a synonym for @samp{%H:%M}. @item %S -This stands for the seconds (00-60). +This stands for the seconds (00-59). @item %t This stands for a tab character. @item %T @@ -1068,9 +1080,9 @@ Here is what the elements mean: @table @var -@item sec +@item seconds The number of seconds past the minute, as an integer between 0 and 59. -@item minute +@item minutes The number of minutes past the hour, as an integer between 0 and 59. @item hour The hour of the day, as an integer between 0 and 23. @@ -1099,9 +1111,9 @@ 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 want them to stand for years above 1900, you must alter them yourself -before you call @code{encode-time}. +Year numbers less than 100 are not treated specially. If you want them +to stand for years above 1900, you must alter them yourself before you +call @code{encode-time}. The optional argument @var{zone} defaults to the current time zone and its daylight savings time rules. If specified, it can be either a list @@ -1121,7 +1133,7 @@ @end example You can perform simple date arithmetic by using out-of-range values for -the @var{sec}, @var{minute}, @var{hour}, @var{day}, and @var{month} +the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month} arguments; for example, day 0 means the day preceding the given month. The operating system puts limits on the range of possible time values; @@ -1175,6 +1187,9 @@ denotes exactly 103 months, 123 days, and 10862 seconds from now. @end table +For relative time values, Emacs considers a month to be exactly thirty +days, and a year to be exactly 365.25 days. + If @var{time} is a number (integer or floating point), that specifies a relative time measured in seconds. @@ -1236,10 +1251,10 @@ Emacs becomes ``idle'' when it starts waiting for user input, and it remains idle until the user provides some input. If a timer is set for five seconds of idleness, it runs approximately five seconds after Emacs -first became idle. Even if its @var{repeat} is true, this timer will -not run again as long as Emacs remains idle, because the duration of -idleness will continue to increase and will not go down to five seconds -again. +first becomes idle. Even if @var{repeat} is non-@code{nil}, this timer +will not run again as long as Emacs remains idle, because the duration +of idleness will continue to increase and will not go down to five +seconds again. Emacs can do various things while idle: garbage collect, autosave or handle data from a subprocess. But these interludes during idleness do @@ -1247,7 +1262,7 @@ idleness to zero. An idle timer set for 600 seconds will run when ten minutes have elapsed since the last user command was finished, even if subprocess output has been accepted thousands of times within those ten -minutes, even if there have been garbage collections and autosaves. +minutes, and even if there have been garbage collections and autosaves. When the user supplies input, Emacs becomes non-idle while executing the input. Then it becomes idle again, and all the idle timers that are @@ -1284,7 +1299,7 @@ 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. The default setting is -system dependent. Some systems always use @sc{cbreak} mode regardless +system-dependent. Some systems always use @sc{cbreak} mode regardless of what is specified. When Emacs communicates directly with X, it ignores this argument and @@ -1314,7 +1329,7 @@ @c Emacs 19 feature @defun current-input-mode -This function returns current mode for reading keyboard input. It +This function returns the current mode for reading keyboard input. It returns a list, corresponding to the arguments of @code{set-input-mode}, of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in which: @@ -1379,10 +1394,10 @@ you reshuffle the keys on the keyboard without changing any command bindings. Its value is normally a char-table, or else @code{nil}. -If @code{keyboard-translate-table} is a char-table, then each character -read from the keyboard is looked up in this character. If the value -found there is non-@code{nil}, then it is used instead of the -actual input character. +If @code{keyboard-translate-table} is a char-table +(@pxref{Char-Tables}), then each character read from the keyboard is +looked up in this char-table. If the value found there is +non-@code{nil}, then it is used instead of the actual input character. In the example below, we set @code{keyboard-translate-table} to a char-table. Then we fill it in to swap the characters @kbd{C-s} and @@ -1573,7 +1588,7 @@ @section Terminal Output @cindex terminal output - The terminal output functions send output to the terminal or keep + The terminal output functions send output to the terminal, or keep track of output sent to the terminal. The variable @code{baud-rate} tells you what Emacs thinks is the output speed of the terminal. @@ -1607,8 +1622,8 @@ Control characters in @var{string} have terminal-dependent effects. One use of this function is to define function keys on terminals that -have downloadable function key definitions. For example, this is how on -certain terminals to define function key 4 to move forward four +have downloadable function key definitions. For example, this is how (on +certain terminals) to define function key 4 to move forward four characters (by transmitting the characters @kbd{C-u C-f} to the computer): @@ -1641,6 +1656,51 @@ @end example @end deffn +@node Sound Output +@section Sound Output +@cindex sound + + To play sound using Emacs, use the function @code{play-sound}. Only +certain systems are supported; if you call @code{play-sound} on a system +which cannot really do the job, it gives an error. Emacs version 20 and +earlier did not support sound at all. + + The sound must be stored as a file in RIFF-WAVE format (@samp{.wav}) +or Sun Audio format (@samp{.au}). + +@tindex play-sound +@defun play-sound sound +This function plays a specified sound. The argument, @var{sound}, has +the form @code{(sound @var{properties}...)}, where the @var{properties} +consist of alternating keywords (particular symbols recognized +specially) and values corresponding to them. + +Here is a table of the keywords that are currently meaningful in +@var{sound}, and their meanings: + +@table @code +@item :file @var{file} +This specifies the file containing the sound to play. +If the file name is not absolute, it is expanded against +the directory @code{data-directory}. + +@item :volume @var{volume} +This specifies how loud to play the sound. It should be a number in the +range of 0 to 1. The default is to use whatever volume has been +specified before. +@end table + +Before actually playing the sound, @code{play-sound} +calls the functions in the list @code{play-sound-functions}. +Each function is called with one argument, @var{sound}. +@end defun + +@tindex play-sound-functions +@defvar play-sound-functions +A list of functions to be called before playing a sound. Each function +is called with one argument, a property list that describes the sound. +@end defvar + @node Special Keysyms @section System-Specific X11 Keysyms @@ -1649,7 +1709,7 @@ @defvar system-key-alist This variable's value should be an alist with one element for each -system-specific keysym. An element has this form: @code{(@var{code} +system-specific keysym. Each element has the form @code{(@var{code} . @var{symbol})}, where @var{code} is the numeric keysym code (not including the ``vendor specific'' bit, @ifinfo @@ -1660,8 +1720,8 @@ @end tex and @var{symbol} is the name for the function key. -For example @code{(168 . mute-acute)} defines a system-specific key used -by HP X servers whose numeric code is +For example @code{(168 . mute-acute)} defines a system-specific key (used +by HP X servers) whose numeric code is @ifinfo -2**28 @end ifinfo @@ -1694,7 +1754,7 @@ @code{C-s} and @kbd{C-q} for flow control. Therefore, the choice of @kbd{C-s} and @kbd{C-q} as command characters for searching and quoting was natural and uncontroversial. With so many commands needing key -assignments, of course we assigned meanings to nearly all @sc{ASCII} +assignments, of course we assigned meanings to nearly all @sc{ascii} control characters. Later, some terminals were introduced which required these characters @@ -1769,7 +1829,7 @@ @cindex batch mode @cindex noninteractive use - The command line option @samp{-batch} causes Emacs to run + The command-line option @samp{-batch} causes Emacs to run noninteractively. In this mode, Emacs does not read commands from the terminal, it does not alter the terminal modes, and it does not expect to be outputting to an erasable screen. The idea is that you specify @@ -1779,7 +1839,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} +either using @code{message}, or using @code{prin1}, etc., with @code{t} 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
--- a/lispref/positions.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/positions.texi Fri Sep 17 06:59:04 1999 +0000 @@ -42,10 +42,10 @@ 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. -If narrowing is in effect (@pxref{Narrowing}), then point is constrained -to fall within the accessible portion of the buffer (possibly at one end -of it). + The value of point is a number no less than 1, and no greater than the +buffer size plus 1. If narrowing is in effect (@pxref{Narrowing}), then +point is constrained to fall within the accessible portion of the buffer +(possibly at one end of it). Each buffer has its own value of point, which is independent of the value of point in other buffers. Each window also has a value of point, @@ -81,7 +81,7 @@ This function returns the maximum accessible value of point in the current buffer. This is @code{(1+ (buffer-size))}, unless narrowing is in effect, in which case it is the position of the end of the region -that you narrowed to. (@pxref{Narrowing}). +that you narrowed to. (@xref{Narrowing}.) @end defun @defun buffer-end flag @@ -89,11 +89,14 @@ @code{(point-max)} otherwise. The argument @var{flag} must be a number. @end defun -@defun buffer-size +@defun buffer-size &optional buffer This function returns the total number of characters in the current buffer. In the absence of any narrowing (@pxref{Narrowing}), @code{point-max} returns a value one larger than this. +If you specify a buffer, @var{buffer}, then the value is the +size of @var{buffer}. + @example @group (buffer-size) @@ -190,6 +193,9 @@ @code{t}. Otherwise, the return value is @code{nil} and point stops at the buffer boundary. +In the minibuffer, the end of the prompt always acts as a word boundary, +regardless of what characters appear before and after it. + In an interactive call, @var{count} is set to the numeric prefix argument. @end deffn @@ -241,7 +247,8 @@ This function moves point to the beginning of the buffer (or the limits of the accessible portion, when narrowing is in effect), setting the mark at the previous position. If @var{n} is non-@code{nil}, then it -puts point @var{n} tenths of the way from the beginning of the buffer. +puts point @var{n} tenths of the way from the beginning of the +accessible portion of the buffer. In an interactive call, @var{n} is the numeric prefix argument, if provided; otherwise @var{n} defaults to @code{nil}. @@ -250,10 +257,11 @@ @end deffn @deffn Command end-of-buffer &optional n -This function moves point to the end of the buffer (or the limits of -the accessible portion, when narrowing is in effect), setting the mark -at the previous position. If @var{n} is non-@code{nil}, then it puts -point @var{n} tenths of the way from the end of the buffer. +This function moves point to the end of the buffer (or the limits of the +accessible portion, when narrowing is in effect), setting the mark at +the previous position. If @var{n} is non-@code{nil}, then it puts point +@var{n} tenths of the way from the end of the accessible portion of the +buffer. In an interactive call, @var{n} is the numeric prefix argument, if provided; otherwise @var{n} defaults to @code{nil}. @@ -308,6 +316,9 @@ If this function reaches the end of the buffer (or of the accessible portion, if narrowing is in effect), it positions point there. No error is signaled. + +As a special feature, in the minibuffer, this command will not +move back into the prompt, if it starts from after the prompt. @end deffn @defun line-beginning-position &optional count @@ -584,7 +595,7 @@ them in Emacs). The syntax table controls how these functions interpret various characters; see @ref{Syntax Tables}. @xref{Parsing Expressions}, for lower-level primitives for scanning sexps or parts of -sexps. For user-level commands, see @ref{Lists Commands,,, emacs, GNU +sexps. For user-level commands, see @ref{Lists Commands,,, emacs, The GNU Emacs Manual}. @deffn Command forward-list arg @@ -725,9 +736,9 @@ It is often useful to move point ``temporarily'' within a localized portion of the program, or to switch buffers temporarily. This is called an @dfn{excursion}, and it is done with the @code{save-excursion} -special form. This construct saves the current buffer and its values of -point and the mark so they can be restored after the completion of the -excursion. +special form. This construct initially remembers the identity of the +current buffer, and its values of point and the mark, and restores them +after the completion of the excursion. The forms for saving and restoring the configuration of windows are described elsewhere (see @ref{Window Configurations}, and @pxref{Frame
--- a/lispref/processes.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/processes.texi Fri Sep 17 06:59:04 1999 +0000 @@ -58,7 +58,7 @@ create a synchronous process and do not return a process object (@pxref{Synchronous Processes}). - Synchronous and asynchronous processes are explained in following + Synchronous and asynchronous processes are explained in the following sections. Since the three functions are all called in a similar fashion, their common arguments are described here. @@ -108,7 +108,7 @@ @defvar exec-directory @pindex movemail -The value of this variable is the name of a directory (a string) that +The value of this variable is a string, the name of a directory that contains programs that come with GNU Emacs, programs intended for Emacs to invoke. The program @code{movemail} is an example of such a program; Rmail uses it to fetch new mail from an inbox. @@ -130,7 +130,7 @@ @section Shell Arguments Lisp programs sometimes need to run a shell and give it a command -which contains file names that were specified by the user. These +that contains file names that were specified by the user. These programs ought to be able to support any valid file name. But the shell gives special treatment to certain characters, and if these characters occur in the file name, they will confuse the shell. To handle these @@ -143,16 +143,18 @@ and then pass it to a shell for execution. Precisely what this function does depends on your operating system. The -function is designed to work with the usual shell syntax; if you use an -unusual shell, you will need to redefine this function. On MS-DOS, the -function returns @var{argument} unchanged; while this is not really -correct, it is the best one can do, since the MS-DOS shell has no -quoting features. +function is designed to work with the syntax of your system's standard +shell; if you use an unusual shell, you will need to redefine this +function. @example ;; @r{This example shows the behavior on GNU and Unix systems.} (shell-quote-argument "foo > bar") @result{} "foo\\ \\>\\ bar" + +;; @r{This example shows the behavior on MS-DOS and MS-Windows systems.} +(shell-quote-argument "foo > bar") + @result{} "\"foo > bar\"" @end example Here's an example of using @code{shell-quote-argument} to construct @@ -171,18 +173,20 @@ @cindex synchronous subprocess After a @dfn{synchronous process} is created, Emacs waits for the -process to terminate before continuing. Starting Dired is an example of -this: it runs @code{ls} in a synchronous process, then modifies the -output slightly. Because the process is synchronous, the entire -directory listing arrives in the buffer before Emacs tries to do -anything with it. +process to terminate before continuing. Starting Dired on GNU or +Unix@footnote{On other systems, Emacs uses a Lisp emulation of +@code{ls}; see @ref{Contents of Directories}.} is an example of this: it +runs @code{ls} in a synchronous process, then modifies the output +slightly. Because the process is synchronous, the entire directory +listing arrives in the buffer before Emacs tries to do anything with it. While Emacs waits for the synchronous subprocess to terminate, the user can quit by typing @kbd{C-g}. The first @kbd{C-g} tries to kill the subprocess with a @code{SIGINT} signal; but it waits until the subprocess actually terminates before quitting. If during that time the user types another @kbd{C-g}, that kills the subprocess instantly with -@code{SIGKILL} and quits immediately. @xref{Quitting}. +@code{SIGKILL} and quits immediately (except on MS-DOS, where killing +other processes doesn't work). @xref{Quitting}. The synchronous subprocess functions return an indication of how the process terminated. @@ -197,7 +201,7 @@ it to finish. The standard input for the process comes from file @var{infile} if -@var{infile} is not @code{nil}, and from @file{/dev/null} otherwise. +@var{infile} is not @code{nil}, and from the null device otherwise. The argument @var{destination} says where to put the process output. Here are the possibilities: @@ -216,7 +220,7 @@ Discard the output. @item 0 -Discard the output, and return immediately without waiting +Discard the output, and return @code{nil} immediately without waiting for the subprocess to finish. In this case, the process is not truly synchronous, since it can run in @@ -224,6 +228,9 @@ Emacs is essentially finished with the subprocess as soon as this function returns. +MS-DOS doesn't support asynchronous subprocesses, so this option doesn't +work there. + @item @code{(@var{real-destination} @var{error-destination})} Keep the standard output stream separate from the standard error stream; deal with the ordinary output as specified by @var{real-destination}, @@ -242,11 +249,12 @@ the buffer as output is inserted. (However, if the coding system chosen for decoding output is @code{undecided}, meaning deduce the encoding from the actual data, then redisplay sometimes cannot continue once -non-@sc{ASCII} characters are encountered. There are fundamental -reasons why it is hard to fix this.) Otherwise the function -@code{call-process} does no redisplay, and the results become visible on -the screen only when Emacs redisplays that buffer in the normal course -of events. +non-@sc{ascii} characters are encountered. There are fundamental +reasons why it is hard to fix this; see @ref{Output from Processes}.) + +Otherwise the function @code{call-process} does no redisplay, and the +results become visible on the screen only when Emacs redisplays that +buffer in the normal course of events. The remaining arguments, @var{args}, are strings that specify command line arguments for the program. @@ -262,7 +270,7 @@ @smallexample @group (call-process "pwd" nil t) - @result{} nil + @result{} 0 ---------- Buffer: foo ---------- /usr/user/lewis/manual @@ -271,7 +279,7 @@ @group (call-process "grep" nil "bar" nil "lewis" "/etc/passwd") - @result{} nil + @result{} 0 ---------- Buffer: bar ---------- lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh @@ -294,7 +302,7 @@ @end defun @defun call-process-region start end program &optional delete destination display &rest args -This function sends the text between @var{start} to @var{end} as +This function sends the text from @var{start} to @var{end} as standard input to a process running @var{program}. It deletes the text sent if @var{delete} is non-@code{nil}; this is useful when @var{destination} is @code{t}, to insert the output in the current @@ -305,7 +313,8 @@ as it comes in. For details, see the description of @code{call-process}, above. If @var{destination} is the integer 0, @code{call-process-region} discards the output and returns @code{nil} -immediately, without waiting for the subprocess to finish. +immediately, without waiting for the subprocess to finish (this only +works if asynchronous subprocess are supported). The remaining arguments, @var{args}, are strings that specify command line arguments for the program. @@ -331,7 +340,7 @@ @group (call-process-region 1 6 "cat" nil t) - @result{} nil + @result{} 0 ---------- Buffer: foo ---------- inputinput@point{} @@ -368,7 +377,7 @@ After an @dfn{asynchronous process} is created, Emacs and the subprocess both continue running immediately. The process thereafter runs in parallel with Emacs, and the two can communicate with each other -using the functions described in following sections. However, +using the functions described in the following sections. However, communication is only partially asynchronous: Emacs sends data to the process only when certain functions are called, and Emacs accepts data from the process only when Emacs is waiting for input or for a time @@ -429,10 +438,10 @@ The point of running a program through the shell, rather than directly with @code{start-process}, is so that you can employ shell features such as wildcards in the arguments. It follows that if you include an -arbitrary user-specified filename in the command, you should quote it +arbitrary user-specified arguments in the command, you should quote it with @code{shell-quote-argument} first, so that any special shell -characters in the file name do @emph{not} have their special shell -meanings. @xref{Shell Arguments}. +characters do @emph{not} have their special shell meanings. @xref{Shell +Arguments}. @end defun @defvar process-connection-type @@ -450,7 +459,7 @@ addition, the total number of @sc{pty}s is limited on many systems and it is good not to waste them. -The value @code{process-connection-type} is used when +The value of @code{process-connection-type} is used when @code{start-process} is called. So you can specify how to communicate with one subprocess by binding the variable around the call to @code{start-process}. @@ -727,7 +736,7 @@ @end smallexample @end defun -@deffn Command process-send-region process-name start end +@defun process-send-region process-name start end This function sends the text in the region defined by @var{start} and @var{end} as standard input to @var{process-name}, which is a process or a process name. (If it is @code{nil}, the current buffer's process is @@ -736,7 +745,7 @@ An error is signaled unless both @var{start} and @var{end} are integers or markers that indicate positions in the current buffer. (It is unimportant which number is larger.) -@end deffn +@end defun @defun process-send-eof &optional process-name This function makes @var{process-name} see an end-of-file in its
--- a/lispref/searching.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/searching.texi Fri Sep 17 06:59:04 1999 +0000 @@ -34,9 +34,9 @@ These are the primitive functions for searching through the text in a buffer. They are meant for use in programs, but you may call them -interactively. If you do so, they prompt for the search string; -@var{limit} and @var{noerror} are set to @code{nil}, and @var{repeat} -is set to 1. +interactively. If you do so, they prompt for the search string; the +arguments @var{limit} and @var{noerror} are @code{nil}, and @var{repeat} +is 1. These search functions convert the search string to multibyte if the buffer is multibyte; they convert the search string to unibyte if the @@ -167,6 +167,7 @@ @menu * Syntax of Regexps:: Rules for writing regular expressions. +* Regexp Functions:: Functions for operating on regular expressions. * Regexp Example:: Illustrates regular expression syntax. @end menu @@ -182,21 +183,33 @@ appearing in a regular expression is ordinary, unless a @samp{\} precedes it. -For example, @samp{f} is not a special character, so it is ordinary, and + For example, @samp{f} is not a special character, so it is ordinary, and therefore @samp{f} is a regular expression that matches the string @samp{f} and no other string. (It does @emph{not} match the string -@samp{ff}.) Likewise, @samp{o} is a regular expression that matches -only @samp{o}.@refill +@samp{fg}, but it does match a @emph{part} of that string.) Likewise, +@samp{o} is a regular expression that matches only @samp{o}.@refill -Any two regular expressions @var{a} and @var{b} can be concatenated. The + Any two regular expressions @var{a} and @var{b} can be concatenated. The result is a regular expression that matches a string if @var{a} matches some amount of the beginning of that string and @var{b} matches the rest of the string.@refill -As a simple example, we can concatenate the regular expressions @samp{f} + As a simple example, we can concatenate the regular expressions @samp{f} and @samp{o} to get the regular expression @samp{fo}, which matches only the string @samp{fo}. Still trivial. To do something more powerful, you -need to use one of the special characters. Here is a list of them: +need to use one of the special regular expression constructs. + +@menu +* Regexp Special:: Special characters in regular expressions. +* Char Classes:: Character classes used in regular expressions. +* Regexp Backslash:: Backslash-sequences in regular expressions. +@end menu + +@node Regexp Special +@subsubsection Special Characters in Regular Expressions + + Here is a list of the characters that are special in a regular +expression. @need 800 @table @asis @@ -266,23 +279,10 @@ You can also include character ranges in a character alternative, by writing the starting and ending characters with a @samp{-} between them. -Thus, @samp{[a-z]} matches any lower-case @sc{ASCII} letter. Ranges may be +Thus, @samp{[a-z]} matches any lower-case @sc{ascii} letter. Ranges may be intermixed freely with individual characters, as in @samp{[a-z$%.]}, -which matches any lower case @sc{ASCII} letter or @samp{$}, @samp{%} or +which matches any lower case @sc{ascii} letter or @samp{$}, @samp{%} or period. - -You cannot always match all non-@sc{ASCII} characters with the regular -expression @samp{[\200-\377]}. This works when searching a unibyte -buffer or string (@pxref{Text Representations}), but not in a multibyte -buffer or string, because many non-@sc{ASCII} characters have codes -above octal 0377. However, the regular expression @samp{[^\000-\177]} -does match all non-@sc{ASCII} characters, in both multibyte and unibyte -representations, because only the @sc{ASCII} characters are excluded. - -The beginning and end of a range must be in the same character set -(@pxref{Character Sets}). Thus, @samp{[a-\x8e0]} is invalid because -@samp{a} is in the @sc{ASCII} character set but the character 0x8e0 -(@samp{a} with grave accent) is in the Emacs character set for Latin-1. Note that the usual regexp special characters are not special inside a character alternative. A completely different set of characters is @@ -297,6 +297,27 @@ To include @samp{^} in a character alternative, put it anywhere but at the beginning. +The beginning and end of a range must be in the same character set +(@pxref{Character Sets}). Thus, @samp{[a-\x8e0]} is invalid because +@samp{a} is in the @sc{ascii} character set but the character 0x8e0 +(@samp{a} with grave accent) is in the Emacs character set for Latin-1. + +You cannot always match all non-@sc{ascii} characters with the regular +expression @samp{[\200-\377]}. This works when searching a unibyte +buffer or string (@pxref{Text Representations}), but not in a multibyte +buffer or string, because many non-@sc{ascii} characters have codes +above octal 0377. However, the regular expression @samp{[^\000-\177]} +does match all non-@sc{ascii} characters (see below regarding @samp{^}), +in both multibyte and unibyte representations, because only the +@sc{ascii} characters are excluded. + +Starting in Emacs 21, a character alternative can also specify named +character classes (@pxref{Char Classes}). This is a POSIX feature whose +syntax is @samp{[:@var{class}:]}. Using a character class is equivalent +to mentioning each of the characters in that class; but the latter is +not feasible in practice, since some classes include thousands of +different characters. + @item @samp{[^ @dots{} ]} @cindex @samp{^} in regexp @samp{[^} begins a @dfn{complemented character alternative}, which matches any @@ -321,14 +342,21 @@ When matching a string instead of a buffer, @samp{^} matches at the beginning of the string or after a newline character @samp{\n}. +For historical compatibility reasons, @samp{^} can be used only at the +beginning of the regular expression, or after @samp{\(} or @samp{\|}. + @item @samp{$} @cindex @samp{$} in regexp +@cindex end of line in regexp is similar to @samp{^} but matches only at the end of a line. Thus, @samp{x+$} matches a string of one @samp{x} or more at the end of a line. When matching a string instead of a buffer, @samp{$} matches at the end of the string or before a newline character @samp{\n}. +For historical compatibility reasons, @samp{$} can be used only at the +end of the regular expression, or before @samp{\)} or @samp{\|}. + @item @samp{\} @cindex @samp{\} in regexp has two functions: it quotes the special characters (including @@ -354,11 +382,66 @@ can act. It is poor practice to depend on this behavior; quote the special character anyway, regardless of where it appears.@refill -For the most part, @samp{\} followed by any character matches only that -character. However, there are several exceptions: two-character -sequences starting with @samp{\} which have special meanings. (The -second character in such a sequence is always ordinary when used on its -own.) Here is a table of @samp{\} constructs. +@node Char Classes +@subsubsection Character Classes +@cindex character classes in regexp + + Here is a table of the classes you can use in a character alternative, +in Emacs 21, and what they mean: + +@table @samp +@item [:ascii:] +This matches any ASCII (unibyte) character. +@item [:alnum:] +This matches any letter or digit. (At present, for multibyte +characters, it matches anything that has word syntax.) +@item [:alpha:] +This matches any letter. (At present, for multibyte characters, it +matches anything that has word syntax.) +@item [:blank:] +This matches space and tab only. +@item [:cntrl:] +This matches any ASCII control character. +@item [:digit:] +This matches @samp{0} through @samp{9}. Thus, @samp{[-+[:digit:]]} +matches any digit, as well as @samp{+} and @samp{-}. +@item [:graph:] +This matches graphic characters---everything except ASCII control characters, +space, and DEL. +@item [:lower:] +This matches any lower-case letter, as determined by +the current case table (@pxref{Case Tables}). +@item [:nonascii:] +This matches any non-ASCII (multibyte) character. +@item [:print:] +This matches printing characters---everything except ASCII control +characters and DEL. +@item [:punct:] +This matches any punctuation character. (At present, for multibyte +characters, it matches anything that has non-word syntax.) +@item [:space:] +This matches any character that has whitespace syntax +(@pxref{Syntax Class Table}). +@item [:upper:] +This matches any upper-case letter, as determined by +the current case table (@pxref{Case Tables}). +@item [:word:] +This matches any character that has word syntax (@pxref{Syntax Class +Table}). +@item [:xdigit:] +This matches the hexadecimal digits: @samp{0} through @samp{9}, @samp{a} +through @samp{f} and @samp{A} through @samp{F}. +@end table + +@node Regexp Backslash +@subsubsection Backslash Constructs in Regular Expressions + + For the most part, @samp{\} followed by any character matches only +that character. However, there are several exceptions: certain +two-character sequences starting with @samp{\} that have special +meanings. (The character after the @samp{\} in such a sequence is +always ordinary when used on its own.) Here is a table of the special +@samp{\} constructs. @table @samp @item \| @@ -376,7 +459,9 @@ surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of @samp{\|}.@refill -Full backtracking capability exists to handle multiple uses of @samp{\|}. +Full backtracking capability exists to handle multiple uses of +@samp{\|}, if you use the POSIX regular expression functions +(@pxref{POSIX Regexps}). @item \( @dots{} \) @cindex @samp{(} in regexp @@ -505,62 +590,6 @@ an invalid regular expression is passed to any of the search functions, an @code{invalid-regexp} error is signaled. -@defun regexp-quote string -This function returns a regular expression string that matches exactly -@var{string} and nothing else. This allows you to request an exact -string match when calling a function that wants a regular expression. - -@example -@group -(regexp-quote "^The cat$") - @result{} "\\^The cat\\$" -@end group -@end example - -One use of @code{regexp-quote} is to combine an exact string match with -context described as a regular expression. For example, this searches -for the string that is the value of @var{string}, surrounded by -whitespace: - -@example -@group -(re-search-forward - (concat "\\s-" (regexp-quote string) "\\s-")) -@end group -@end example -@end defun - -@defun regexp-opt strings &optional paren -@tindex regexp-opt -This function returns an efficient regular expression that will match -any of the strings @var{strings}. This is useful when you need to make -matching or searching as fast as possible---for example, for Font Lock -mode. - -If the optional argument @var{paren} is non-@code{nil}, then the -returned regular expression is always enclosed by at least one -parentheses-grouping construct. - -This simplified definition of @code{regexp-opt} produces a -regular expression which is equivalent to the actual value -(but not as efficient): - -@example -(defun regexp-opt (strings paren) - (let ((open-paren (if paren "\\(" "")) - (close-paren (if paren "\\)" ""))) - (concat open-paren - (mapconcat 'regexp-quote strings "\\|") - close-paren))) -@end example -@end defun - -@defun regexp-opt-depth regexp -@tindex regexp-opt-depth -This function returns the total number of grouping constructs -(parenthesized expressions) in @var{regexp}. -@end defun - @node Regexp Example @comment node-name, next, previous, up @subsection Complex Regexp Example @@ -624,6 +653,72 @@ beyond the minimum needed to end a sentence. @end table +@node Regexp Functions +@subsection Regular Expression Functions + + These functions operate on regular expressions. + +@defun regexp-quote string +This function returns a regular expression whose only exact match is +@var{string}. Using this regular expression in @code{looking-at} will +succeed only if the next characters in the buffer are @var{string}; +using it in a search function will succeed if the text being searched +contains @var{string}. + +This allows you to request an exact string match or search when calling +a function that wants a regular expression. + +@example +@group +(regexp-quote "^The cat$") + @result{} "\\^The cat\\$" +@end group +@end example + +One use of @code{regexp-quote} is to combine an exact string match with +context described as a regular expression. For example, this searches +for the string that is the value of @var{string}, surrounded by +whitespace: + +@example +@group +(re-search-forward + (concat "\\s-" (regexp-quote string) "\\s-")) +@end group +@end example +@end defun + +@defun regexp-opt strings &optional paren +@tindex regexp-opt +This function returns an efficient regular expression that will match +any of the strings @var{strings}. This is useful when you need to make +matching or searching as fast as possible---for example, for Font Lock +mode. + +If the optional argument @var{paren} is non-@code{nil}, then the +returned regular expression is always enclosed by at least one +parentheses-grouping construct. + +This simplified definition of @code{regexp-opt} produces a +regular expression which is equivalent to the actual value +(but not as efficient): + +@example +(defun regexp-opt (strings paren) + (let ((open-paren (if paren "\\(" "")) + (close-paren (if paren "\\)" ""))) + (concat open-paren + (mapconcat 'regexp-quote strings "\\|") + close-paren))) +@end example +@end defun + +@defun regexp-opt-depth regexp +@tindex regexp-opt-depth +This function returns the total number of grouping constructs +(parenthesized expressions) in @var{regexp}. +@end defun + @node Regexp Search @section Regular Expression Searching @cindex regular expression searching @@ -908,10 +1003,19 @@ with. If it is a string, that string is used. It can also be a list of strings, to be used in cyclic order. +If @var{replacements} is a cons cell, @var{(@var{function} +. @var{data})}, this means to call @var{function} after each match to +get the replacement text. This function is called with two arguments: +@var{data}, and the number of replacements already made. + If @var{repeat-count} is non-@code{nil}, it should be an integer. Then it specifies how many times to use each of the strings in the @var{replacements} list before advancing cyclicly to the next one. +If @var{from-string} contains upper-case letters, then +@code{perform-replace} binds @code{case-fold-search} to @code{nil}, and +it uses the @code{replacements} without altering the case of them. + Normally, the keymap @code{query-replace-map} defines the possible user responses for queries. The argument @var{map}, if non-@code{nil}, is a keymap to use instead of @code{query-replace-map}. @@ -1009,7 +1113,7 @@ @end menu @node Replacing Match -@subsection Replacing the Text That Matched +@subsection Replacing the Text that Matched This function replaces the text matched by the last search with @var{replacement}. @@ -1039,9 +1143,6 @@ letter, @code{replace-match} considers this a capitalized first word rather than all upper case. -If @code{case-replace} is @code{nil}, then case conversion is not done, -regardless of the value of @var{fixed-case}. @xref{Searching and Case}. - If @var{literal} is non-@code{nil}, then @var{replacement} is inserted exactly as it is, the only alterations being case changes as needed. If it is @code{nil} (the default), then the character @samp{\} is treated @@ -1361,8 +1462,8 @@ replacement text verbatim. A non-@code{nil} value means to convert the case of the replacement text according to the text being replaced. -The function @code{replace-match} is where this variable actually has -its effect. @xref{Replacing Match}. +This variable is used by passing it as an argument to the function +@code{replace-match}. @xref{Replacing Match}. @end defopt @defopt case-fold-search
--- a/lispref/sequences.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/sequences.texi Fri Sep 17 06:59:04 1999 +0000 @@ -3,7 +3,7 @@ @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/sequences -@node Sequences Arrays Vectors, Symbols, Lists, Top +@node Sequences Arrays Vectors, Hash Tables, Lists, Top @chapter Sequences, Arrays, and Vectors @cindex sequence @@ -312,7 +312,7 @@ @end group @group (aref "abcdefg" 1) - @result{} 98 ; @r{@samp{b} is @sc{ASCII} code 98.} + @result{} 98 ; @r{@samp{b} is @sc{ascii} code 98.} @end group @end example
--- a/lispref/streams.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/streams.texi Fri Sep 17 06:59:04 1999 +0000 @@ -716,25 +716,25 @@ @tindex print-escape-nonascii @defvar print-escape-nonascii -If this variable is non-@code{nil}, then unibyte non-@sc{ASCII} +If this variable is non-@code{nil}, then unibyte non-@sc{ascii} characters in strings are unconditionally printed as backslash sequences by the print functions @code{prin1} and @code{print} that print with quoting. -Those functions also use backslash sequences for unibyte non-@sc{ASCII} +Those functions also use backslash sequences for unibyte non-@sc{ascii} characters, regardless of the value of this variable, when the output stream is a multibyte buffer or a marker pointing into one. @end defvar @tindex print-escape-multibyte @defvar print-escape-multibyte -If this variable is non-@code{nil}, then multibyte non-@sc{ASCII} +If this variable is non-@code{nil}, then multibyte non-@sc{ascii} characters in strings are unconditionally printed as backslash sequences by the print functions @code{prin1} and @code{print} that print with quoting. Those functions also use backslash sequences for multibyte -non-@sc{ASCII} characters, regardless of the value of this variable, +non-@sc{ascii} characters, regardless of the value of this variable, when the output stream is a unibyte buffer or a marker pointing into one. @end defvar @@ -766,3 +766,48 @@ exceeding this limit is abbreviated with an ellipsis. A value of @code{nil} (which is the default) means no limit. @end defvar + + These variables are used for detecting and reporting circular +and shared structure---but they are only defined in Emacs 21. + +@tindex print-circle +@defvar print-circle +If non-@code{nil}, this variable enables detection of circular +and shared structure in printing. +@end defvar + +@tindex print-gensym +@defvar print-gensym +If non-@code{nil}, this variable enables detection of uninterned symbols +(@pxref{Creating Symbols}) in printing. When this is enabled, +uninterned symbols print with the prefix @samp{#:}, which tells the Lisp +reader to produce an uninterned symbol. +@end defvar + +@tindex print-continuous-numbering +@defvar print-continuous-numbering +To print several objects with shared structure in common, you should +bind @code{print-continuous-numbering} to @code{t} around them all. +That tells @code{print} not to reinitialize @code{print-number-table} +each time. +@end defvar + +@tindex print-number-table +@defvar print-number-table +This variable holds the table used as the basis of outputting +@samp{#@var{n}=} and @samp{#@var{n}#} constructs for circular and shared +structure. When you want to print several objects with shared structure +in common, you should bind @code{print-number-table} to @code{nil} +around them all. +@end defvar + + Here is an example of printing two objects with a common +set of shared substructure: + +@example +(let ((print-circle t) + (print-continuous-numbering t) + print-number-table) + (print1 x) + (print1 y)) +@end example
--- a/lispref/strings.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/strings.texi Fri Sep 17 06:59:04 1999 +0000 @@ -27,7 +27,7 @@ * Creating Strings:: Functions to allocate new strings. * Modifying Strings:: Altering the contents of an existing string. * Text Comparison:: Comparing characters or strings. -* String Conversion:: Converting characters or strings and vice versa. +* String Conversion:: Converting to and from characters and strings. * Formatting Strings:: @code{format}: Emacs's analogue of @code{printf}. * Case Conversion:: Case conversion functions. * Case Tables:: Customizing case conversion. @@ -43,7 +43,7 @@ The length of a string (like any array) is fixed, and cannot be altered once the string exists. Strings in Lisp are @emph{not} terminated by a distinguished character code. (By contrast, strings in -C are terminated by a character with @sc{ASCII} code 0.) +C are terminated by a character with @sc{ascii} code 0.) Since strings are arrays, and therefore sequences as well, you can operate on them with the general array and sequence functions. @@ -51,25 +51,25 @@ change individual characters in a string using the functions @code{aref} and @code{aset} (@pxref{Array Functions}). - There are two text representations for non-@sc{ASCII} characters in + There are two text representations for non-@sc{ascii} characters in Emacs strings (and in buffers): unibyte and multibyte (@pxref{Text -Representations}). @sc{ASCII} characters always occupy one byte in a -string; in fact, when a string is all @sc{ASCII}, there is no real +Representations}). An @sc{ascii} character always occupies one byte in a +string; in fact, when a string is all @sc{ascii}, there is no real difference between the unibyte and multibyte representations. For most Lisp programming, you don't need to be concerned with these two representations. Sometimes key sequences are represented as strings. When a string is a key sequence, string elements in the range 128 to 255 represent meta -characters (which are extremely large integers) rather than character +characters (which are large integers) rather than character codes in the range 128 to 255. Strings cannot hold characters that have the hyper, super or alt -modifiers; they can hold @sc{ASCII} control characters, but no other -control characters. They do not distinguish case in @sc{ASCII} control +modifiers; they can hold @sc{ascii} control characters, but no other +control characters. They do not distinguish case in @sc{ascii} control characters. If you want to store such characters in a sequence, such as a key sequence, you must use a vector instead of a string. -@xref{Character Type}, for more information about representation of meta +@xref{Character Type}, for more information about the representation of meta and other modifiers for keyboard input characters. Strings are useful for holding regular expressions. You can also @@ -200,7 +200,7 @@ If the characters copied from @var{string} have text properties, the properties are copied into the new string also. @xref{Text Properties}. -@code{substring} also allows vectors for the first argument. +@code{substring} also accepts a vector for the first argument. For example: @example @@ -250,8 +250,8 @@ converted to a string of digits making up the decimal printed representation of the integer. @strong{Don't use this feature; we plan to eliminate it. If you already use this feature, change your programs -now!} The proper way to convert an integer to a decimal number in this -way is with @code{format} (@pxref{Formatting Strings}) or +now!} The proper way to convert an integer to its decimal printed form +is with @code{format} (@pxref{Formatting Strings}) or @code{number-to-string} (@pxref{String Conversion}). @example @@ -271,7 +271,7 @@ @defun split-string string separators @tindex split-string -Split @var{string} into substrings in between matches for the regular +This function splits @var{string} into substrings at matches for the regular expression @var{separators}. Each match for @var{separators} defines a splitting point; the substrings between the splitting points are made into a list, which is the value returned by @code{split-string}. @@ -367,7 +367,7 @@ strings. When @code{equal} (@pxref{Equality Predicates}) compares two strings, it uses @code{string=}. -If the strings contain non-@sc{ASCII} characters, and one is unibyte +If the strings contain non-@sc{ascii} characters, and one is unibyte while the other is multibyte, then they cannot be equal. @xref{Text Representations}. @end defun @@ -379,9 +379,9 @@ @cindex lexical comparison @defun string< string1 string2 @c (findex string< causes problems for permuted index!!) -This function compares two strings a character at a time. First it -scans both the strings at once to find the first pair of corresponding -characters that do not match. If the lesser character of those two is +This function compares two strings a character at a time. It +scans both the strings at the same time to find the first pair of corresponding +characters that do not match. If the lesser character of these two is the character from @var{string1}, then @var{string1} is less, and this function returns @code{t}. If the lesser character is the one from @var{string2}, then @var{string1} is greater, and this function returns @@ -389,11 +389,11 @@ Pairs of characters are compared according to their character codes. Keep in mind that lower case letters have higher numeric values in the -@sc{ASCII} character set than their upper case counterparts; digits and +@sc{ascii} character set than their upper case counterparts; digits and many punctuation characters have a lower numeric value than upper case -letters. An @sc{ASCII} character is less than any non-@sc{ASCII} -character; a unibyte non-@sc{ASCII} character is always less than any -multibyte non-@sc{ASCII} character (@pxref{Text Representations}). +letters. An @sc{ascii} character is less than any non-@sc{ascii} +character; a unibyte non-@sc{ascii} character is always less than any +multibyte non-@sc{ascii} character (@pxref{Text Representations}). @example @group @@ -433,11 +433,12 @@ @defun compare-strings string1 start1 end1 string2 start2 end2 &optional ignore-case @tindex compare-strings -This function compares a specified part of @var{string1} with a +This function compares the specified part of @var{string1} with the specified part of @var{string2}. The specified part of @var{string1} -runs from index @var{start1} up to index @var{end1} (default, the end of -the string). The specified part of @var{string2} runs from index -@var{start2} up to index @var{end2} (default, the end of the string). +runs from index @var{start1} up to index @var{end1} (@code{nil} means +the end of the string). The specified part of @var{string2} runs from +index @var{start2} up to index @var{end2} (@code{nil} means the end of +the string). The strings are both converted to multibyte for the comparison (@pxref{Text Representations}) so that a unibyte string can be equal to @@ -500,7 +501,7 @@ @cindex string to character This function returns the first character in @var{string}. If the string is empty, the function returns 0. The value is also 0 when the -first character of @var{string} is the null character, @sc{ASCII} code +first character of @var{string} is the null character, @sc{ascii} code 0. @example @@ -510,8 +511,10 @@ @result{} 120 (string-to-char "") @result{} 0 +@group (string-to-char "\000") @result{} 0 +@end group @end example This function may be eliminated in the future if it does not seem useful @@ -523,7 +526,7 @@ @cindex integer to decimal This function returns a string consisting of the printed base-ten representation of @var{number}, which may be an integer or a floating -point number. The value starts with a sign if the argument is +point number. The returned value starts with a minus sign if the argument is negative. @example @@ -553,8 +556,9 @@ The parsing skips spaces and tabs at the beginning of @var{string}, then reads as much of @var{string} as it can interpret as a number. (On some systems it ignores other whitespace at the beginning, not just spaces -and tabs.) If the first character after the ignored whitespace is not a -digit or a plus or minus sign, this function returns 0. +and tabs.) If the first character after the ignored whitespace is +neither a digit, nor a plus or minus sign, nor the leading dot of a +floating point number, this function returns 0. @example (string-to-number "256") @@ -607,6 +611,10 @@ @var{string} and then replacing any format specification in the copy with encodings of the corresponding @var{objects}. The arguments @var{objects} are the computed values to be formatted. + +The characters in @var{string}, other than the format specifications, +are copied directly into the output; starting in Emacs 21, if they have +text properties, these are copied into the output also. @end defun @cindex @samp{%} in format @@ -646,6 +654,10 @@ by their contents alone, with no @samp{"} characters, and symbols appear without @samp{\} characters. +Starting in Emacs 21, if the object is a string, its text properties are +copied into the output. The text properties of the @samp{%s} itself +are also copied, but those of the object take priority. + If there is no corresponding object, the empty string is used. @item %S @@ -774,15 +786,15 @@ The character case functions change the case of single characters or of the contents of strings. The functions normally convert only alphabetic characters (the letters @samp{A} through @samp{Z} and -@samp{a} through @samp{z}, as well as non-ASCII letters); other -characters are not altered. (You can specify a different case -conversion mapping by specifying a case table---@pxref{Case Tables}.) +@samp{a} through @samp{z}, as well as non-@sc{ascii} letters); other +characters are not altered. You can specify a different case +conversion mapping by specifying a case table (@pxref{Case Tables}). These functions do not modify the strings that are passed to them as arguments. The examples below use the characters @samp{X} and @samp{x} which have -@sc{ASCII} codes 88 and 120 respectively. +@sc{ascii} codes 88 and 120 respectively. @defun downcase string-or-char This function converts a character or a string to lower case. @@ -814,7 +826,7 @@ When the argument to @code{upcase} is a character, @code{upcase} returns the corresponding upper case character. This value is an integer. If the original character is upper case, or is not a letter, then the -value equals the original character. +value returned equals the original character. @example (upcase "The cat in the hat") @@ -921,7 +933,7 @@ The extra table @var{equivalences} is a map that cyclicly permutes each equivalence class (of characters with the same canonical -equivalent). (For ordinary @sc{ASCII}, this would map @samp{a} into +equivalent). (For ordinary @sc{ascii}, this would map @samp{a} into @samp{A} and @samp{A} into @samp{a}, and likewise for each set of equivalent characters.) @@ -958,7 +970,7 @@ @end defun The following three functions are convenient subroutines for packages -that define non-@sc{ASCII} character sets. They modify the specified +that define non-@sc{ascii} character sets. They modify the specified case table @var{case-table}; they also modify the standard syntax table. @xref{Syntax Tables}. Normally you would use these functions to change the standard case table.
--- a/lispref/symbols.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/symbols.texi Fri Sep 17 06:59:04 1999 +0000 @@ -3,7 +3,7 @@ @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/symbols -@node Symbols, Evaluation, Sequences Arrays Vectors, Top +@node Symbols, Evaluation, Hash Tables, Top @chapter Symbols @cindex symbol @@ -57,7 +57,7 @@ When a symbol is used as a function, its function definition is used in its place. This cell is also used to make a symbol stand for a keymap or a keyboard macro, for editor command execution. Because each symbol -has separate value and function cells, variables and function names do +has separate value and function cells, variables names and function names do not conflict. See @code{symbol-function} in @ref{Function Cells}. @item Property list @@ -194,7 +194,9 @@ and go from there. That is a simple version of hashing. Each element of the obarray is a @dfn{bucket} which holds all the symbols with a given hash code; to look for a given name, it is sufficient to look -through all the symbols in the bucket for that name's hash code. +through all the symbols in the bucket for that name's hash code. (The +same idea is used for general Emacs hash tables, but they are a +different data type; see @ref{Hash Tables}.) @cindex interning If a symbol with the desired name is found, the reader uses that @@ -208,6 +210,11 @@ same obarray. Thus, the reader gets the same symbols for the same names, as long as you keep reading with the same obarray. + Interning usually happens automatically in the reader, but sometimes +other programs need to do it. For example, after the @kbd{M-x} command +obtains the command name as a string using the minibuffer, it then +interns the string, to get the interned symbol with that name. + @cindex symbol equality @cindex uninterned symbol No obarray contains all symbols; in fact, some symbols are not in any @@ -216,6 +223,10 @@ to gain access to it is by finding it in some other object or as the value of a variable. + Creating an uninterned symbol is useful in generating Lisp code, +because an uninterned symbol used as a variable in the code you generate +cannot clash with any variables used in other Lisp programs. + In Emacs Lisp, an obarray is actually a vector. Each element of the vector is a bucket; its value is either an interned symbol whose name hashes to that bucket, or 0 if the bucket is empty. Each interned @@ -224,7 +235,7 @@ find all the symbols in an obarray except using @code{mapatoms} (below). The order of symbols in a bucket is not significant. - In an empty obarray, every element is 0, and you can create an obarray + In an empty obarray, every element is 0, so you can create an obarray with @code{(make-vector @var{length} 0)}. @strong{This is the only valid way to create an obarray.} Prime numbers as lengths tend to result in good hashing; lengths one less than a power of two are also
--- a/lispref/syntax.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/syntax.texi Fri Sep 17 06:59:04 1999 +0000 @@ -71,7 +71,7 @@ standard syntax table, while specifying other characters itself. The ``inherit'' syntax class means ``inherit this character's syntax from the standard syntax table.'' Just changing the standard syntax for a -characters affects all syntax tables which inherit from it. +character affects all syntax tables that inherit from it. @defun syntax-table-p object This function returns @code{t} if @var{object} is a syntax table. @@ -92,9 +92,11 @@ Each class is designated by a mnemonic character, which serves as the name of the class when you need to specify a class. Usually the -designator character is one that is frequently in that class; however, +designator character is one that is often assigned that class; however, its meaning as a designator is unvarying and independent of what syntax -that character currently has. +that character currently has. Thus, @samp{\} as a designator character +always gives ``escape character'' syntax, regardless of what syntax +@samp{\} currently has. @cindex syntax descriptor A syntax descriptor is a Lisp string that specifies a syntax class, a @@ -106,7 +108,7 @@ For example, the syntax descriptor for the character @samp{*} in C mode is @samp{@w{. 23}} (i.e., punctuation, matching character slot -unused, second character of a comment-starter, first character of an +unused, second character of a comment-starter, first character of a comment-ender), and the entry for @samp{/} is @samp{@w{. 14}} (i.e., punctuation, matching character slot unused, first character of a comment-starter, second character of a comment-ender). @@ -542,6 +544,10 @@ mentioned in @var{syntaxes}. It stops when it encounters the end of the buffer, or position @var{limit} (if specified), or a character it is not supposed to skip. + +If @var{syntaxes} starts with @samp{^}, then the function skips +characters whose syntax is @emph{not} in @var{syntaxes}. + The return value is the distance traveled, which is a nonnegative integer. @end defun @@ -549,8 +555,11 @@ @defun skip-syntax-backward syntaxes &optional limit This function moves point backward across characters whose syntax classes are mentioned in @var{syntaxes}. It stops when it encounters -the beginning of the buffer, or position @var{limit} (if specified), or a -character it is not supposed to skip. +the beginning of the buffer, or position @var{limit} (if specified), or +a character it is not supposed to skip. + +If @var{syntaxes} starts with @samp{^}, then the function skips +characters whose syntax is @emph{not} in @var{syntaxes}. The return value indicates the distance traveled. It is an integer that is zero or less. @@ -856,7 +865,7 @@ initialized by copying from the standard categories table, so that the standard categories are available in all modes. - Each category has a name, which is an @sc{ASCII} printing character in + Each category has a name, which is an @sc{ascii} printing character in the range @w{@samp{ }} to @samp{~}. You specify the name of a category when you define it with @code{define-category}.
--- a/lispref/text.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/text.texi Fri Sep 17 06:59:04 1999 +0000 @@ -220,6 +220,9 @@ " @end group @end example + +When this function is used in the minibuffer, the value does not include +the prompt. @end defun @defun thing-at-point thing @@ -275,7 +278,7 @@ at the second character. @example -(compare-buffer-substring nil 6 11 nil 16 21) +(compare-buffer-substrings nil 6 11 nil 16 21) @result{} 2 @end example @end defun @@ -482,6 +485,8 @@ error. Otherwise, it deletes the text without asking for any confirmation. It returns @code{nil}. +In the minibuffer, @code{erase-buffer} does not delete the prompt. + Normally, deleting a large amount of text from a buffer inhibits further auto-saving of that buffer ``because it has shrunk''. However, @code{erase-buffer} does not do this, the idea being that the future @@ -1790,8 +1795,8 @@ @var{force}, since there is no way to split them. The argument @var{force} also has an effect if the line isn't long -enough to reach column @var{column}; in that case, it says to add -whitespace at the end of the line to reach that column. +enough to reach column @var{column}; if it is @code{t}, that means to +add whitespace at the end of the line to reach that column. If @var{column} is not an integer, an error is signaled. @@ -2540,14 +2545,31 @@ @cindex face codes of text @kindex face @r{(text property)} You can use the property @code{face} to control the font and color of -text. Its value is a face name or a list of face names. @xref{Faces}, -for more information. - -If the property value is a list, elements may also have the form -@code{(foreground-color . @var{color-name})} or @code{(background-color -. @var{color-name})}. These elements specify just the foreground color -or just the background color; therefore, there is no need to create a -face for each color that you want to use. +text. @xref{Faces}, for more information. + +In the simplest case, the value is a face name. It can also be a list; +then each element can be any of these possibilities; + +@itemize @bullet +@item +A face name (a symbol or string). + +@item +Starting in Emacs 21, a property list of face attributes. This has the +form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a +face attribute name and @var{value} is a meaningful value for that +attribute. With this feature, you do not need to create a face each +time you want to specify a particular attribute for certain text. +@xref{Face Attributes}. + +@item +A cons cell of the form @code{(foreground-color . @var{color-name})} or +@code{(background-color . @var{color-name})}. These elements specify +just the foreground color or just the background color. + +@code{(foreground-color . @var{color-name})} is equivalent to +@code{(:foreground @var{color-name})}, and likewise for the background. +@end itemize @xref{Font Lock Mode}, for information on how to update @code{face} properties automatically based on the contents of the text. @@ -2559,6 +2581,26 @@ that all text between the character and where the mouse is have the same @code{mouse-face} property value. +@item fontified +@kindex fontified @r{(text property)} +This property, if non-@code{nil}, says that text in the buffer has +had faces assigned automatically by a feature such as Font-Lock mode. +@xref{Auto Faces}. + +@item display +@kindex display @r{(text property)} +This property activates various features that change the +way text is displayed. For example, it can make text appear taller +or shorter, higher or lower, wider or narror, or replaced with an image. +@xref{Display Property}. + +@item help-echo +@kindex help-echo @r{(text property)} +If text has a string as its @code{help-echo} property, then when you +move the mouse onto that text, Emacs displays that string in the echo +area, or in the tooltip window. This feature is used in the mode line. +It is available starting in Emacs 21. + @item local-map @cindex keymap of character @kindex local-map @r{(text property)} @@ -3231,7 +3273,7 @@ @cindex base 64 encoding Base 64 code is used in email to encode a sequence of 8-bit bytes as a -longer sequence of @sc{ASCII} graphic characters. This section +longer sequence of @sc{ascii} graphic characters. This section describes the functions for converting to and from this code. @defun base64-encode-region beg end &optional no-line-break @@ -3377,3 +3419,14 @@ This variable is a normal hook that is run whenever a buffer is changed that was previously in the unmodified state. @end defvar + +@defvar inhibit-modification-hooks +@tindex inhibit-modification-hooks +If this variable is non-@code{nil}, all of the change hooks are +disabled; none of them run. This affects all the hook variables +described above in this section, as well as the hooks attached to +certain special text properties (@pxref{Special Properties}) and overlay +properties (@pxref{Overlay Properties}). + +This variable is available starting in Emacs 21. +@end defvar
--- a/lispref/tips.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/tips.texi Fri Sep 17 06:59:04 1999 +0000 @@ -14,6 +14,12 @@ previous chapters, and describes conventions Emacs Lisp programmers should follow. + You can automatically check some of the conventions described below by +running the command @kbd{M-x checkdoc RET} when visiting a Lisp file. +It cannot check all of the conventions, and not all the warnings it +gives necessarily correspond to problems, but it is worth examining them +all. + @menu * Coding Conventions:: Conventions for clean and robust programs. * Compilation Tips:: Making compiled code run fast. @@ -287,6 +293,17 @@ Try to avoid compiler warnings about undefined free variables, by adding @code{defvar} definitions for these variables. +Sometimes adding a @code{require} for another package is useful to avoid +compilation warnings for variables and functions defined in that +package. If you do this, often it is better if the @cpde{require} acts +only at compile time. Here's how to do that: + +@example +(eval-when-compile + (require 'foo) + (defvar bar-baz)) +@end example + If you bind a variable in one function, and use it or set it in another function, the compiler warns about the latter function unless the variable has a definition. But often these variables have short names, @@ -421,12 +438,12 @@ that looks good. @item -For consistency, phrase the verb in the first sentence of a -function's documentation string as an infinitive with ``to'' omitted. For -instance, use ``Return the cons of A and B.'' in preference to ``Returns -the cons of A and B@.'' Usually it looks good to do likewise for the -rest of the first paragraph. Subsequent paragraphs usually look better -if they have proper subjects. +For consistency, phrase the verb in the first sentence of a function's +documentation string as an imperative--for instance, use ``Return the +cons of A and B.'' in preference to ``Returns the cons of A and B@.'' +Usually it looks good to do likewise for the rest of the first +paragraph. Subsequent paragraphs usually look better if each sentence +has a proper subject. @item Write documentation strings in the active voice, not the passive, and in @@ -485,9 +502,15 @@ @code{/} refers to its second argument as @samp{DIVISOR}, because the actual argument name is @code{divisor}. -Also use all caps for meta-syntactic variables, such as when you show +Also use all caps for metasyntactic variables, such as when you show the decomposition of a list or vector into subunits, some of which may -vary. +vary. @samp{KEY} and @samp{VALUE} in the following example +illustrate this practice: + +@example +The argument TABLE should be an alist whose elements +have the form (KEY . VALUE). Here, KEY is ... +@end example @item @iftex @@ -537,6 +560,14 @@ does not make a hyperlink to the documentation, irrelevant here, of the function @code{list}. +To make a hyperlink to Info documentation, write the name of the Info +node in single quotes, preceded by @samp{info node} or @samp{Info +node}. The Info file name defaults to @samp{emacs}. For example, + +@smallexample +See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'. +@end smallexample + @item Don't write key sequences directly in documentation strings. Instead, use the @samp{\\[@dots{}]} construct to stand for them. For example, @@ -659,7 +690,21 @@ Emacs has conventions for using special comments in Lisp libraries to divide them into sections and give information such as who wrote -them. This section explains these conventions. First, an example: +them. This section explains these conventions. + + We'll start with an example, a package that is included in the Emacs +distribution. + + Parts of this example reflect its status as part of Emacs; for +example, the copyright notice lists the Free Software Foundation as the +copyright holder, and the copying permission says the file is part of +Emacs. When you write a package and post it, the copyright holder would +be you (unless your employer claims to own it instead), and you should +get the suggested copying permission from the end of the GNU General +Public License itself. Don't say your file is part of Emacs +if we haven't installed it in Emacs yet! + + With that warning out of the way, on to the example: @smallexample @group @@ -773,7 +818,8 @@ store the change history there). For most of the Lisp files distributed with Emacs, the change history is kept in the file @file{ChangeLog} and not in the source file at all; these files do -not have a @samp{;;; Change Log:} line. +not have a @samp{;;; Change Log:} line. @samp{History} is an +alternative to @samp{Change Log}. @item ;;; Code: This begins the actual code of the program.
--- a/lispref/variables.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/variables.texi Fri Sep 17 06:59:04 1999 +0000 @@ -94,7 +94,7 @@ @end example @node Constant Variables -@section Variables That Never Change +@section Variables that Never Change @vindex nil @vindex t @kindex setting-constant @@ -104,8 +104,8 @@ with @samp{:}. These symbols cannot be rebound, nor can their values be changed. Any attempt to set or bind @code{nil} or @code{t} signals a @code{setting-constant} error. The same is true for a symbol whose name -starts with @samp{:}, except that you are allowed to set such a symbol to -itself. +starts with @samp{:} (if it is interned in the standard obarray), except +that you are allowed to set such a symbol to itself. @example @group @@ -563,8 +563,9 @@ If a user option variable has a @code{variable-interactive} property, 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 -to @code{interactive} (@pxref{Using Interactive}). However, this feature -is largely obsoleted by @code{defcustom} (@pxref{Customization}). +specified in @code{interactive} (@pxref{Using Interactive}). However, +this feature is largely obsoleted by @code{defcustom} +(@pxref{Customization}). @strong{Warning:} If the @code{defconst} and @code{defvar} special forms are used while the variable has a local binding, they set the @@ -606,8 +607,7 @@ @example (defvar my-mode-map nil @var{docstring}) -(if my-mode-map - nil +(unless my-mode-map (let ((map (make-sparse-keymap))) (define-key my-mode-map "\C-c\C-a" 'my-command) @dots{} @@ -624,8 +624,7 @@ @example (defvar my-mode-map nil @var{docstring}) -(if my-mode-map - nil +(unless my-mode-map (setq my-mode-map (make-sparse-keymap)) (define-key my-mode-map "\C-c\C-a" 'my-command) @dots{}) @@ -854,10 +853,10 @@ @cindex dynamic scoping Local bindings in Emacs Lisp have @dfn{indefinite scope} and @dfn{dynamic extent}. @dfn{Scope} refers to @emph{where} textually in -the source code the binding can be accessed. Indefinite scope means +the source code the binding can be accessed. ``Indefinite scope'' means that any part of the program can potentially access the variable binding. @dfn{Extent} refers to @emph{when}, as the program is -executing, the binding exists. Dynamic extent means that the binding +executing, the binding exists. ``Dynamic extent'' means that the binding lasts as long as the activation of the construct that established it. The combination of dynamic extent and indefinite scope is called @@ -902,9 +901,9 @@ In a lexically scoped language, the binding of @code{x} in @code{binder} would never be accessible in @code{user}, because @code{user} is not textually contained within the function -@code{binder}. However, in dynamically scoped Emacs Lisp, @code{user} +@code{binder}. However, in dynamically-scoped Emacs Lisp, @code{user} may or may not refer to the binding of @code{x} established in -@code{binder}, depending on circumstances: +@code{binder}, depending on the circumstances: @itemize @bullet @item @@ -1065,9 +1064,9 @@ @cindex buffer-local variables Global and local variable bindings are found in most programming -languages in one form or another. Emacs also supports additional, +languages in one form or another. Emacs, however, also supports additional, unusual kinds of variable binding: @dfn{buffer-local} bindings, which -apply only in one buffer, and frame-local bindings, which apply only in +apply only in one buffer, and @dfn{frame-local} bindings, which apply only in one frame. Having different values for a variable in different buffers and/or frames is an important customization method. @@ -1100,7 +1099,7 @@ A variable can have buffer-local bindings in some buffers but not in other buffers. The default binding is shared by all the buffers that don't have their own bindings for the variable. (This includes all -newly created buffers.) If you set the variable in a buffer that does +newly-created buffers.) If you set the variable in a buffer that does not have a buffer-local binding for it, this sets the default binding (assuming there are no frame-local bindings to complicate the matter), so the new value is visible in all the buffers that see the default @@ -1239,7 +1238,7 @@ variables cannot have buffer-local bindings as well. @xref{Multiple Displays}. -@strong{Note:} do not use @code{make-local-variable} for a hook +@strong{Note:} Do not use @code{make-local-variable} for a hook variable. Instead, use @code{make-local-hook}. @xref{Hooks}. @end deffn
--- a/lispref/windows.texi Fri Sep 17 06:53:20 1999 +0000 +++ b/lispref/windows.texi Fri Sep 17 06:59:04 1999 +0000 @@ -23,8 +23,9 @@ * Window Point:: Each window has its own location of point. * Window Start:: The display-start position controls which text is on-screen in the window. -* Vertical Scrolling:: Moving text up and down in the window. -* Horizontal Scrolling:: Moving text sideways on the window. +* Textual Scrolling:: Moving text up and down through the window. +* Vertical Scrolling:: Moving the contents up and down on the window. +* Horizontal Scrolling:: Moving the contents sideways on the window. * Size of Window:: Accessing the size of a window. * Resizing Windows:: Changing the size of a window. * Coordinates and Windows:: Converting coordinates to windows. @@ -251,40 +252,32 @@ characters; see @ref{Display Tables}. @end deffn -@deffn Command split-window-vertically size +@deffn Command split-window-vertically &optional size This function splits the selected window into two windows, one above the other, leaving the upper of the two windows selected, with @var{size} lines. (If @var{size} is negative, then the lower of the two windows gets @minus{} @var{size} lines and the upper window gets the rest, but the upper window is still the one selected.) - -This function is simply an interface to @code{split-window}. -Here is the complete function definition for it: - -@smallexample -@group -(defun split-window-vertically (&optional arg) - "Split current window into two windows, @dots{}" - (interactive "P") - (split-window nil (and arg (prefix-numeric-value arg)))) -@end group -@end smallexample @end deffn @deffn Command split-window-horizontally size This function splits the selected window into two windows side-by-side, leaving the selected window with @var{size} columns. -This function is simply an interface to @code{split-window}. Here is -the complete definition for @code{split-window-horizontally} (except for -part of the documentation string): +This function is basically an interface to @code{split-window}. +You could define a simplified version of the function like this: @smallexample @group (defun split-window-horizontally (&optional arg) "Split selected window into two windows, side by side..." (interactive "P") - (split-window nil (and arg (prefix-numeric-value arg)) t)) +@endgroup +@group + (let ((size (and arg (prefix-numeric-value arg)))) + (and size (< size 0) + (setq size (+ (window-width) size))) + (split-window nil size t))) @end group @end smallexample @end deffn @@ -565,11 +558,15 @@ include in the cycle, as in @code{next-window}. @end defun -@deffn Command other-window count +@deffn Command other-window count &optional all-frames This function selects the @var{count}th following window in the cyclic order. If count is negative, then it moves back @minus{}@var{count} windows in the cycle, rather than forward. It returns @code{nil}. +The argument @var{all-frames} has the same meaning is as in +@code{next-window}, but the @var{minibuf} argument of @code{next-window} +is always effectively @code{nil}. + In an interactive call, @var{count} is the numeric prefix argument. @end deffn @@ -895,11 +892,11 @@ @code{pop-up-frame-alist}. @end defvar -@defvar pop-up-frame-alist +@defopt pop-up-frame-alist This variable holds an alist specifying frame parameters used when @code{display-buffer} makes a new frame. @xref{Frame Parameters}, for more information about frame parameters. -@end defvar +@end defopt @defopt special-display-buffer-names A list of buffer names for buffers that should be displayed specially. @@ -938,16 +935,24 @@ @code{special-display-popup-frame}. @end defvar -@defun special-display-popup-frame buffer +@defun special-display-popup-frame buffer &rest args This function makes @var{buffer} visible in a frame of its own. If @var{buffer} is already displayed in a window in some frame, it makes the frame visible and raises it, to use that window. Otherwise, it creates a frame that will be dedicated to @var{buffer}. -This function uses an existing window displaying @var{buffer} whether or -not it is in a frame of its own; but if you set up the above variables -in your init file, before @var{buffer} was created, then presumably the -window was previously made by this function. +If @var{args} is an alist, it specifies frame parameters for the new +frame. + +If @var{args} is a list whose @sc{car} is a symbol, then @code{(car +@var{args})} is called as a function to actually create and set up the +frame; it is called with @var{buffer} as first argument, and @code{(cdr +@var{args})} as additional arguments. + +This function always uses an existing window displaying @var{buffer}, +whether or not it is in a frame of its own; but if you set up the above +variables in your init file, before @var{buffer} was created, then +presumably the window was previously made by this function. @end defun @defopt special-display-frame-alist @@ -1035,10 +1040,11 @@ when the user switches to another buffer, the cursor jumps to the position of point in that buffer. -@defun window-point window +@defun window-point &optional window This function returns the current position of point in @var{window}. For a nonselected window, this is the value point would have (in that -window's buffer) if that window were selected. +window's buffer) if that window were selected. If @var{window} is +@code{nil}, the selected window is used. When @var{window} is the selected window and its buffer is also the current buffer, the value returned is the same as point in that buffer. @@ -1081,10 +1087,11 @@ for the same buffer, or 1 if the buffer doesn't have any. Redisplay updates the window-start position (if you have not specified -it explicitly since the previous redisplay) so that point appears on the -screen. Nothing except redisplay automatically changes the window-start -position; if you move point, do not expect the window-start position to -change in response until after the next redisplay. +it explicitly since the previous redisplay)---for example, to make sure +point appears on the screen. Nothing except redisplay automatically +changes the window-start position; if you move point, do not expect the +window-start position to change in response until after the next +redisplay. For a realistic example of using @code{window-start}, see the description of @code{count-lines} in @ref{Text Lines}. @@ -1188,18 +1195,22 @@ The @code{pos-visible-in-window-p} function considers only vertical scrolling. If @var{position} is out of view only because @var{window} has been scrolled horizontally, @code{pos-visible-in-window-p} returns -@code{t}. @xref{Horizontal Scrolling}. +@code{t} anyway. @xref{Horizontal Scrolling}. @end defun -@node Vertical Scrolling -@section Vertical Scrolling -@cindex vertical scrolling -@cindex scrolling vertically +@node Textual Scrolling +@section Textual Scrolling +@cindex textual scrolling +@cindex scrolling textually - Vertical scrolling means moving the text up or down in a window. It -works by changing the value of the window's display-start location. It -may also change the value of @code{window-point} to keep it on the -screen. + @dfn{Textual scrolling} means moving the text up or down though a +window. It works by changing the value of the window's display-start +location. It may also change the value of @code{window-point} to keep +point on the screen. + + Textual scrolling was formerly called ``vertical scrolling,'' but we +changed its name to distinguish it from the new vertical fractional +scrolling feature (@pxref{Vertical Scrolling}). In the commands @code{scroll-up} and @code{scroll-down}, the directions ``up'' and ``down'' refer to the motion of the text in the buffer at which @@ -1218,9 +1229,10 @@ commands clearly move the text up or down on the screen. We have chosen names that fit the user's point of view. - The scrolling functions (aside from @code{scroll-other-window}) have -unpredictable results if the current buffer is different from the buffer -that is displayed in the selected window. @xref{Current Buffer}. + The textual scrolling functions (aside from +@code{scroll-other-window}) have unpredictable results if the current +buffer is different from the buffer that is displayed in the selected +window. @xref{Current Buffer}. @deffn Command scroll-up &optional count This function scrolls the text in the selected window upward @@ -1251,10 +1263,14 @@ lines. Negative values of @var{count}, or @code{nil}, are handled as in @code{scroll-up}. -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. -You can specify a different window to scroll with the variable +You can specify which buffer to scroll by setting the variable +@code{other-window-scroll-buffer} to a buffer. If that buffer isn't +already displayed, @code{scroll-other-window} displays it in some +window. + +When the selected window is the minibuffer, the next window is normally +the one at the top left corner. You can specify a different window to +scroll, when the minibuffer is selected, by setting the variable @code{minibuffer-scroll-window}. This variable has no effect when any other window is selected. @xref{Minibuffer Misc}. @@ -1353,43 +1369,122 @@ @end example @end deffn +@node Vertical Scrolling +@section Vertical Fractional Scrolling +@cindex Vertical Fractional Scrolling + + @dfn{Vertical fractional scrolling} means shifting the image in the +window up or down by a specified multiple or fraction of a line. +Starting in Emacs 21, each window has a @dfn{vertical scroll position}, +which is a number, never less than zero. It specifies how far to raise +the contents of the window. Raising the window contents generally makes +all or part of some lines disappear off the top, and all or part of some +other lines appear at the bottom. The usual value is zero. + + The vertical scroll position is measured in units of the normal line +height, which is the height of the default font. Thus, if the value is +.5, that means the window contents are scrolled up half the normal line +height. If it is 3.3, that means the window contents are scrolled up +somewhat over three times the normal line height. + + What fraction of a line the vertical scrolling covers, or how many +lines, depends on what the lines contain. A value of .5 could scroll a +line whose height is very short off the screen, while a value of 3.3 +could scroll just part of the way through a tall line or an image. + +@defun window-vscroll &optional window +This function returns the current vertical scroll position of +@var{window}, If @var{window} is @code{nil}, the selected window is +used. + +@example +@group +(window-vscroll) + @result{} 0 +@end group +@end example +@end defun + +@defun set-window-vscroll window lines +This function sets @var{window}'s vertical scroll position to +@var{lines}. The argument @var{lines} should be zero or positive; if +not, it is taken as zero. + +The actual vertical scroll position must always correspond +to an integral number of pixels, so the value you specify +is rounded accordingly. + +The return value is the result of this rounding. + +@example +@group +(set-window-vscroll (selected-window) 1.2) + @result{} 1.13 +@end group +@end example +@end defun + @node Horizontal Scrolling @section Horizontal Scrolling @cindex horizontal scrolling - Because we read English from left to right in the ``inner loop'', and -from top to bottom in the ``outer loop'', horizontal scrolling is not -like vertical scrolling. Vertical scrolling involves selection of a -contiguous portion of text to display, but horizontal scrolling causes -part of each line to go off screen. The amount of horizontal scrolling -is therefore specified as a number of columns rather than as a position -in the buffer. It has nothing to do with the display-start position -returned by @code{window-start}. + @dfn{Horizontal scrolling} means shifting the image in the window left +or right by a specified multiple of the normal character width. Each +window has a @dfn{vertical scroll position}, which is a number, never +less than zero. It specifies how far to shift the contents left. +Shifting the window contents left generally makes all or part of some +characters disappear off the left, and all or part of some other +characters appear at the right. The usual value is zero. + + The horizontal scroll position is measured in units of the normal +character width, which is the width of space in the default font. Thus, +if the value is 5, that means the window contents are scrolled left by 5 +times the the normal character width. How many characters actually +disappear off to the left depends on their width, and could vary from +line to line. + + Because we read from side to side in the ``inner loop'', and from top +to bottom in the ``outer loop'', the effect of horizontal scrolling is +not like that of textual or vertical scrolling. Textual scrolling +involves selection of a portion of text to display, and vertical +scrolling moves the window contents contiguously; but horizontal +scrolling causes part of @emph{each line} to go off screen. Usually, no horizontal scrolling is in effect; then the leftmost column is at the left edge of the window. In this state, scrolling to -the right is meaningless, since there is no data to the left of the -screen to be revealed by it; so this is not allowed. Scrolling to the -left is allowed; it scrolls the first columns of text off the edge of -the window and can reveal additional columns on the right that were -truncated before. Once a window has a nonzero amount of leftward -horizontal scrolling, you can scroll it back to the right, but only so -far as to reduce the net horizontal scroll to zero. There is no limit -to how far left you can scroll, but eventually all the text will -disappear off the left edge. +the right is meaningless, since there is no data to the left of the edge +to be revealed by it; so this is not allowed. Scrolling to the left is +allowed; it scrolls the first columns of text off the edge of the window +and can reveal additional columns on the right that were truncated +before. Once a window has a nonzero amount of leftward horizontal +scrolling, you can scroll it back to the right, but only so far as to +reduce the net horizontal scroll to zero. There is no limit to how far +left you can scroll, but eventually all the text will disappear off the +left edge. -@deffn Command scroll-left count + In Emacs 21, redisplay automatically alters the horizontal scrolling +of a window as necessary to ensure that point is always visible. +However, you can still set the horizontal scrolling value explicitly. +The value you specify will be used, provided it leaves point visible. + +@deffn Command scroll-left &optional count This function scrolls the selected window @var{count} columns to the -left (or to the right if @var{count} is negative). The return value is -the total amount of leftward horizontal scrolling in effect after the -change---just like the value returned by @code{window-hscroll} (below). +left (or to the right if @var{count} is negative). The default +for @var{count} is the window width, minus 2. + +The return value is the total amount of leftward horizontal scrolling in +effect after the change---just like the value returned by +@code{window-hscroll} (below). @end deffn -@deffn Command scroll-right count +@deffn Command scroll-right &optional count This function scrolls the selected window @var{count} columns to the -right (or to the left if @var{count} is negative). The return value is -the total amount of leftward horizontal scrolling in effect after the -change---just like the value returned by @code{window-hscroll} (below). +right (or to the left if @var{count} is negative). The default +for @var{count} is the window width, minus 2. + +The return value is the total amount of leftward horizontal scrolling in +effect after the change---just like the value returned by +@code{window-hscroll} (below). Once you scroll a window as far right as it can go, back to its normal position where the total leftward scrolling is zero, attempts to scroll @@ -1426,6 +1521,7 @@ This function sets the number of columns from the left margin that @var{window} is scrolled from the value of @var{columns}. The argument @var{columns} should be zero or positive; if not, it is taken as zero. +Fractional values of @var{columns} are not supported at present. The value returned is @var{columns}. @@ -1516,12 +1612,12 @@ rightmost column used by @var{window}, and @var{bottom} is one more than the bottommost row used by @var{window} and its mode-line. -When you have side-by-side windows, the right edge value for a window -with a neighbor on the right includes the width of the separator between -the window and that neighbor. This separator may be a column of -@samp{|} characters or it may be a scroll bar. Since the width of the -window does not include this separator, the width does not equal the -difference between the right and left edges in this case. +If a window has a scroll bar, the right edge value includes the width of +the scroll bar. Otherwise, if the window has a neighbor on the right, +its right edge value includes the width of the separator line between +the window and that neighbor. Since the width of the window does not +include this separator, the width does not usually equal the difference +between the right and left edges. Here is the result obtained on a typical 24-line terminal with just one window: @@ -1538,14 +1634,12 @@ If @var{window} is at the upper left corner of its frame, then @var{bottom} is the same as the value of @code{(window-height)}, -@var{right} is almost the same as the value of -@code{(window-width)}@footnote{They are not exactly equal because -@var{right} includes the vertical separator line or scroll bar, while -@code{(window-width)} does not.}, and @var{top} and @var{left} are zero. -For example, the edges of the following window are @w{@samp{0 0 5 8}}. -Assuming that the frame has more than 8 columns, the last column of the -window (column 7) holds a border rather than text. The last row (row 4) -holds the mode line, shown here with @samp{xxxxxxxxx}. +@var{right} is almost the same as the value of @code{(window-width)}, +and @var{top} and @var{left} are zero. For example, the edges of the +following window are @w{@samp{0 0 8 5}}. Assuming that the frame has +more than 8 columns, the last column of the window (column 7) holds a +border rather than text. The last row (row 4) holds the mode line, +shown here with @samp{xxxxxxxxx}. @example @group @@ -1561,15 +1655,9 @@ @end group @end example -When there are side-by-side windows, any window not at the right edge of -its frame has a separator in its last column or columns. The separator -counts as one or two columns in the width of the window. A window never -includes a separator on its left, since that belongs to the window to -the left. - In the following example, let's suppose that the frame is 7 columns wide. Then the edges of the left window are @w{@samp{0 0 4 3}} -and the edges of the right window are @w{@samp{4 0 7 3}}. +and the edges of the right window are @w{@samp{4 0 8 3}}. @example @group @@ -1610,6 +1698,13 @@ function makes the window occupy the entire height (or width) of the frame. +If there are various other windows from which lines or columns can be +stolen, and some of them specify fixed size (using +@code{window-size-fixed}, see below), they are left untouched while +other windows are ``robbed.'' If it would be necessary to alter the +size of a fixed-size window, @code{enlarge-window} gets an error +instead. + If @var{size} is negative, this function shrinks the window by @minus{}@var{size} lines or columns. If that makes the window smaller than the minimum size (@code{window-min-height} and @@ -1652,10 +1747,11 @@ @end example @end deffn -@deffn Command shrink-window-if-larger-than-buffer window +@deffn Command shrink-window-if-larger-than-buffer &optional window This command shrinks @var{window} to be as small as possible while still showing the full contents of its buffer---but not less than -@code{window-min-height} lines. +@code{window-min-height} lines. If @var{window} is not given, +it defaults to the selected window. However, the command does nothing if the window is already too small to display the whole text of the buffer, or if part of the contents are @@ -1663,6 +1759,35 @@ its frame, or if the window is the only window in its frame. @end deffn +@tindex window-size-fixed +@defvar window-size-fixed +If this variable is non-@code{nil}, in any given buffer, +then the size of any window displaying the buffer remains fixed +unless you explicitly change it or Emacs has no other choice. +(This feature is new in Emacs 21.) + +If the value is @code{height}, then only the window's height is fixed; +if the value is @code{width}, then only the window's width is fixed. +Any other non-@code{nil} value fixes both the width and the height. + +The usual way to use this variable is to give it a buffer-local value in +a particular buffer. That way, the windows (but usually there is only +one) displaying that buffer have fixed size. + +Explicit size-change functions such as @code{enlarge-window} +get an error if they would have to change a window size which is fixed. +Therefore, when you want to change the size of such a window, +you should bind @code{window-size-fixed} to @code{nil}, like this: + +@example +(let ((window-size-fixed nil)) + (enlarge-window 10)) +@end example + +Note that changing the frame size will change the size of a +fixed-size window, if there is no other alternative. +@end defvar + @cindex minimum window size The following two variables constrain the window-size-changing functions to a minimum height and width. @@ -1721,11 +1846,14 @@ @item mode-line The coordinates are in the mode line of @var{window}. -@item vertical-split +@item header-line +The coordinates are in the header line of @var{window}. + +@item vertical-line The coordinates are in the vertical line between @var{window} and its neighbor to the right. This value occurs only if the window doesn't have a scroll bar; positions in a scroll bar are considered outside the -window. +window for these purposes. @item nil The coordinates are not in any part of @var{window}. @@ -1750,8 +1878,8 @@ configuration instead of a window configuration. @xref{Frame Configurations}. -@defun current-window-configuration -This function returns a new object representing the selected frame's +@defun current-window-configuration &optional frame +This function returns a new object representing @var{frame}'s current window configuration, including the number of windows, their sizes and current buffers, which window is the selected window, and for each window the displayed buffer, the display-start position, and the @@ -1759,16 +1887,20 @@ @code{window-min-height}, @code{window-min-width} and @code{minibuffer-scroll-window}. An exception is made for point in the current buffer, whose value is not saved. + +If @var{frame} is omitted, the selected frame is used. @end defun @defun set-window-configuration configuration This function restores the configuration of windows and buffers as -specified by @var{configuration}. The argument @var{configuration} must -be a value that was previously returned by -@code{current-window-configuration}. This configuration is restored in -the frame from which @var{configuration} was made, whether that frame is -selected or not. This always counts as a window size change and -triggers execution of the @code{window-size-change-functions} +specified by @var{configuration}, for the frame that @var{configuration} +was created for. + +The argument @var{configuration} must be a value that was previously +returned by @code{current-window-configuration}. This configuration is +restored in the frame from which @var{configuration} was made, whether +that frame is selected or not. This always counts as a window size +change and triggers execution of the @code{window-size-change-functions} (@pxref{Window Hooks}), because @code{set-window-configuration} doesn't know how to tell whether the new configuration actually differs from the old one. @@ -1913,7 +2045,7 @@ @var{position}. @end defun -@defun window-redisplay-end-trigger window +@defun window-redisplay-end-trigger &optional window @tindex window-redisplay-end-trigger This function returns @var{window}'s current end trigger position. @end defun