diff options
| author | Karoly Lorentey <lorentey@elte.hu> | 2006-07-29 09:59:12 +0000 |
|---|---|---|
| committer | Karoly Lorentey <lorentey@elte.hu> | 2006-07-29 09:59:12 +0000 |
| commit | 251bc578cc636223d618d06cf2a2bb7d07db9cce (patch) | |
| tree | 58e1c6b0a35bb4a77e6cb77876e4bc6a9d3f2ab2 /lispref | |
| parent | 99715bbc447eb633e45ffa23b87284771ce3ac74 (diff) | |
| parent | 0ed0527cb02180a50f6744086ce3a487740c73e4 (diff) | |
| download | emacs-251bc578cc636223d618d06cf2a2bb7d07db9cce.tar.gz emacs-251bc578cc636223d618d06cf2a2bb7d07db9cce.tar.bz2 emacs-251bc578cc636223d618d06cf2a2bb7d07db9cce.zip | |
Merged from emacs@sv.gnu.org
Patches applied:
* emacs@sv.gnu.org/emacs--devo--0--patch-351
Update from CVS
* emacs@sv.gnu.org/emacs--devo--0--patch-352
Update from CVS
* emacs@sv.gnu.org/emacs--devo--0--patch-353
Merge from gnus--rel--5.10
* emacs@sv.gnu.org/emacs--devo--0--patch-354
Update from CVS
* emacs@sv.gnu.org/emacs--devo--0--patch-355
Update from CVS
* emacs@sv.gnu.org/emacs--devo--0--patch-356
Update from CVS
* emacs@sv.gnu.org/emacs--devo--0--patch-357
Merge from gnus--rel--5.10
* emacs@sv.gnu.org/emacs--devo--0--patch-358
Update from CVS
* emacs@sv.gnu.org/emacs--devo--0--patch-359
Update from CVS
* emacs@sv.gnu.org/emacs--devo--0--patch-360
Update from CVS
* emacs@sv.gnu.org/emacs--devo--0--patch-361
Update from CVS
* emacs@sv.gnu.org/emacs--devo--0--patch-362
Update from CVS
* emacs@sv.gnu.org/emacs--devo--0--patch-363
Update from CVS
* emacs@sv.gnu.org/emacs--devo--0--patch-364
Update from CVS
* emacs@sv.gnu.org/emacs--devo--0--patch-365
Update from CVS
* emacs@sv.gnu.org/emacs--devo--0--patch-366
Update from CVS
* emacs@sv.gnu.org/emacs--devo--0--patch-367
Merge from gnus--rel--5.10
* emacs@sv.gnu.org/emacs--devo--0--patch-368
Update from CVS
* emacs@sv.gnu.org/emacs--devo--0--patch-369
Update from CVS
* emacs@sv.gnu.org/emacs--devo--0--patch-370
Update from CVS
* emacs@sv.gnu.org/gnus--rel--5.10--patch-115
Update from CVS
* emacs@sv.gnu.org/gnus--rel--5.10--patch-116
Update from CVS
* emacs@sv.gnu.org/gnus--rel--5.10--patch-117
Update from CVS
* emacs@sv.gnu.org/gnus--rel--5.10--patch-118
Merge from emacs--devo--0
* emacs@sv.gnu.org/gnus--rel--5.10--patch-119
Update from CVS
* emacs@sv.gnu.org/gnus--rel--5.10--patch-120
Update from CVS
git-archimport-id: lorentey@elte.hu--2004/emacs--multi-tty--0--patch-573
Diffstat (limited to 'lispref')
40 files changed, 526 insertions, 321 deletions
diff --git a/lispref/ChangeLog b/lispref/ChangeLog index 64a38096d64..09757fca10b 100644 --- a/lispref/ChangeLog +++ b/lispref/ChangeLog @@ -1,3 +1,130 @@ +2006-07-28 Kim F. Storm <storm@cua.dk> + + * commands.texi (Reading One Event): Fix last change. + +2006-07-26 Chong Yidong <cyd@stupidchicken.com> + + * commands.texi (Reading One Event): Document SECONDS argument for + read-event, read-char, and read-char-exclusive. + +2006-07-25 Stefan Monnier <monnier@iro.umontreal.ca> + + * modes.texi (Multiline Font Lock): Can't use jit-lock-defer-multiline + to ensure correct identification. + +2006-07-24 Richard Stallman <rms@gnu.org> + + * text.texi (Clickable Text): Clarify. + + * sequences.texi (Vector Functions): Delete duplicate xref. + + * objects.texi (Function Type): Clarify. + + * modes.texi (Keymaps and Minor Modes): List punct chars for minor + modes. + + * lists.texi (List Variables): New node. + Material moved from other nodes. + + * variables.texi (Setting Variables): add-to-list and + add-to-ordered-list moved to List Variables node. + +2006-07-23 Thien-Thi Nguyen <ttn@gnu.org> + + * text.texi (Links and Mouse-1): + For mouse-on-link-p, expand on arg POS. + +2006-07-21 Kim F. Storm <storm@cua.dk> + + * display.texi (Forcing Redisplay): Don't mention systems which + don't support sub-second timers for redisplay-preemption-period. + + * os.texi (Terminal Output): Clarify text vs graphical terminal. + +2006-07-21 Eli Zaretskii <eliz@gnu.org> + + * frames.texi (Input Focus): Document that focus-follows-mouse has + no effect on MS-Windows. + +2006-07-18 Richard Stallman <rms@gnu.org> + + * display.texi (Forcing Redisplay): Cleanups in previous change. + + * processes.texi (Low-Level Network): Make menu more convenient. + +2006-07-18 Kim F. Storm <storm@cua.dk> + + * display.texi (Forcing Redisplay): redisplay-preemption-period + only used on window systems. Add xref to Terminal Output. + + * os.texi (Terminal Output): baud-rate only controls preemption on + non-window systems. Add xref to Forcing Redisplay. + + * processes.texi (Low-Level Network): Rename node "Make Network" + to "Network Processes". + +2006-07-18 Karl Berry <karl@gnu.org> + + * variables.texi, functions.texi, customize.texi, loading.texi: + * edebug.texi, minibuf.texi: Fix page breaks through chapter 20. + +2006-07-17 Chong Yidong <cyd@stupidchicken.com> + + * commands.texi (Waiting): Document batch-mode sit-for behavior. + +2006-07-17 Richard Stallman <rms@gnu.org> + + * eval.texi, elisp.texi, text.texi: Use real doublequote inside menus. + Put period and comma inside quotes. + + * loading.texi, markers.texi: Use real doublequote inside menus. + + * windows.texi: Put point and comma inside quotes. + (Textual Scrolling): Use @samp for error message. + + * variables.texi, tips.texi, syntax.texi, symbols.texi: + * strings.texi, streams.texi, processes.texi, os.texi: + * objects.texi, numbers.texi, modes.texi, minibuf.texi: + * lists.texi, keymaps.texi, intro.texi, hash.texi, internals.texi: + * gpl.texi, functions.texi, files.texi, frames.texi, doclicense.texi: + * display.texi, control.texi, commands.texi, buffers.texi, anti.texi: + Put point and comma inside quotes. + + * control.texi (Processing of Errors): Add command-error-function. + + * variables.texi (File Local Variables): Clarify that + file local variables make buffer-local bindings. + + * modes.texi (Syntactic Font Lock): Give default for + font-lock-syntax-table. + +2006-07-17 Nick Roberts <nickrob@snap.net.nz> + + * text.texi (Special Properties): Clean up previous change. + +2006-07-16 Karl Berry <karl@gnu.org> + + * objects.texi, numbers.texi, strings.texi, lists.texi, hash.texi: + * control.texi: Fix bad page breaks through chapter 10 (control). + + * anti.texi (Antinews): Reorder face-attribute fns to avoid + underfull hbox. + +2006-07-15 Nick Roberts <nickrob@snap.net.nz> + + * text.texi (Special Properties): Describe fontified text property + in relation to a character (not text). + +2006-07-15 Kim F. Storm <storm@cua.dk> + + * maps.texi (Standard Keymaps): Add xref for minibuffer maps. + Add apropos-mode-map, custom-mode-map, esc-map, global-map, + grep-mode-map, help-map, help-mode-map, kmacro-map, and tool-bar-map. + + * anti.texi (Antinews): Mention redisplay function. + The kbd macro existed, but was not documented, before 22.x. + Function pos-visible-in-window-p is not new in 22.x, just enhanced. + 2006-07-14 Nick Roberts <nickrob@snap.net.nz> * display.texi (Displaying Messages): Add anchor. diff --git a/lispref/anti.texi b/lispref/anti.texi index 78152d7ab31..8636282a7c2 100644 --- a/lispref/anti.texi +++ b/lispref/anti.texi @@ -24,6 +24,12 @@ redisplay engine, which will be even simpler.) @itemize @minus @item +The function @code{redisplay} has been removed. To update the display +without delay, call @code{(sit-for 0)}. Since it is generally +considered wasteful to update the display if there are any pending +input events, no replacement for @code{(redisplay t)} is provided. + +@item The function @code{force-window-update} has been removed. It shouldn't be needed, since changes in window contents are detected automatically. In case they aren't, call @code{redraw-display} to @@ -80,8 +86,8 @@ removed. In @code{defface} specifications, the @code{supports} predicate is no longer supported. @item -@code{face-attribute-relative-p} and @code{merge-face-attribute} have -been removed. +The functions @code{merge-face-attribute} and +@code{face-attribute-relative-p} have been removed. @item The priority of faces in a list supplied by the @code{:inherit} face @@ -91,7 +97,7 @@ in a while, to keep Emacs Lisp programmers on their toes. @item The @code{min-colors} face attribute, used for tailoring faces to limited-color displays, does not exist. If in doubt, use colors like -``white'' and ``black'', which ought to be defined everywhere. +``white'' and ``black,'' which ought to be defined everywhere. @item The @code{tty-color-mode} frame parameter does not exist. You should @@ -126,9 +132,9 @@ and key sequences: @itemize @minus @item -The @code{kbd} macro has been removed. It isn't that difficult to -write key sequences using the string and vector representations, and -we want to encourage users to learn. +The @code{kbd} macro is now obsolete and is no longer documented. +It isn't that difficult to write key sequences using the string and +vector representations, and we want to encourage users to learn. @item Emacs no longer supports key remapping. You can do pretty much the @@ -164,7 +170,7 @@ the sentinel. @item Many programming shortcuts have been deleted, to provide you with the -enjoyment of ``rolling your own''. The macros @code{while-no-input}, +enjoyment of ``rolling your own.'' The macros @code{while-no-input}, @code{with-local-quit}, and @code{with-selected-window}, along with @code{dynamic-completion-table} and @code{lazy-completion-table} no longer exist. Also, there are no built-in progress reporters; @@ -304,7 +310,7 @@ In @code{replace-match}, the replacement text now inherits properties from the surrounding text. @item -@code{mode-line-format} no longer supports the @code{:propertize}, +The variable @code{mode-line-format} no longer supports the @code{:propertize}, @code{%i}, and @code{%I} constructs. The function @code{format-mode-line} has been removed. @@ -319,8 +325,9 @@ The functions @code{window-pixel-edges} and think in terms of lines and columns, not pixel coordinates. (Sometime in the distant past, we will do away with graphical terminals entirely, in favor of text terminals.) For similar reasons, the -functions @code{posn-at-point}, @code{posn-at-x-y}, and -@code{pos-visible-in-window-p} have been removed. +functions @code{posn-at-point} and @code{posn-at-x-y} have been removed, and +@code{pos-visible-in-window-p} no longer worries about partially +visible rows. @item The macro @code{save-selected-window} only saves the selected window diff --git a/lispref/buffers.texi b/lispref/buffers.texi index 55e41e6b3e5..46a886eaea6 100644 --- a/lispref/buffers.texi +++ b/lispref/buffers.texi @@ -484,7 +484,7 @@ correspond to the new file name, unless the new name is already in use. If @var{filename} is @code{nil} or the empty string, that stands for -``no visited file''. In this case, @code{set-visited-file-name} marks +``no visited file.'' In this case, @code{set-visited-file-name} marks the buffer as having no visited file, without changing the buffer's modified flag. diff --git a/lispref/commands.texi b/lispref/commands.texi index 2aca1b19253..10cd97400f8 100644 --- a/lispref/commands.texi +++ b/lispref/commands.texi @@ -2165,7 +2165,7 @@ same symbol that would normally represent that combination of mouse button and modifier keys. The information about the window part is kept elsewhere in the event---in the coordinates. But @code{read-key-sequence} translates this information into imaginary -``prefix keys'', all of which are symbols: @code{header-line}, +``prefix keys,'' all of which are symbols: @code{header-line}, @code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line}, @code{vertical-line}, and @code{vertical-scroll-bar}. You can define meanings for mouse clicks in special window parts by defining key @@ -2199,7 +2199,7 @@ single event. None of the three functions below suppresses quitting. -@defun read-event &optional prompt inherit-input-method +@defun read-event &optional prompt inherit-input-method seconds This function reads and returns the next event of command input, waiting if necessary until an event is available. Events can come directly from the user or from a keyboard macro. @@ -2220,6 +2220,15 @@ If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event} moves the cursor temporarily to the echo area, to the end of any message displayed there. Otherwise @code{read-event} does not move the cursor. +If @var{seconds} is non-@code{nil}, it should be a number specifying +the maximum time to wait for input, in seconds. If no input arrives +within that time, @code{read-event} stops waiting and returns +@code{nil}. A floating-point value for @var{seconds} means to wait +for a fractional number of seconds. Some systems support only a whole +number of seconds; on these systems, @var{seconds} is rounded down. +If @var{seconds} is @code{nil}, @code{read-event} waits as long as +necessary for input to arrive. + If @code{read-event} gets an event that is defined as a help character, then in some cases @code{read-event} processes the event directly without returning. @xref{Help Functions}. Certain other events, called @@ -2237,7 +2246,7 @@ right-arrow function key: @end example @end defun -@defun read-char &optional prompt inherit-input-method +@defun read-char &optional prompt inherit-input-method seconds This function reads and returns a character of command input. If the user generates an event which is not a character (i.e. a mouse click or function key event), @code{read-char} signals an error. The arguments @@ -2269,7 +2278,7 @@ the echo area. @end example @end defun -@defun read-char-exclusive &optional prompt inherit-input-method +@defun read-char-exclusive &optional prompt inherit-input-method seconds This function reads and returns a character of command input. If the user generates an event which is not a character, @code{read-char-exclusive} ignores it and reads another event, until it @@ -2410,7 +2419,7 @@ individual events, which you can put in @code{unread-command-events}. @defvar unread-command-char This variable holds a character to be read as command input. -A value of -1 means ``empty''. +A value of -1 means ``empty.'' This variable is mostly obsolete now that you can use @code{unread-command-events} instead; it exists only to support programs @@ -2534,9 +2543,10 @@ screen. @defun sit-for seconds &optional nodisp This function performs redisplay (provided there is no pending input from the user), then waits @var{seconds} seconds, or until input is -available. The value is @code{t} if @code{sit-for} waited the full -time with no input arriving (see @code{input-pending-p} in @ref{Event -Input Misc}). Otherwise, the value is @code{nil}. +available. The usual purpose of @code{sit-for} is to give the user +time to read text that you display. The value is @code{t} if +@code{sit-for} waited the full time with no input arriving +(@pxref{Event Input Misc}). Otherwise, the value is @code{nil}. The argument @var{seconds} need not be an integer. If it is a floating point number, @code{sit-for} waits for a fractional number of seconds. @@ -2551,8 +2561,9 @@ 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 the timeout elapses). -The usual purpose of @code{sit-for} is to give the user time to read -text that you display. +In batch mode (@pxref{Batch Mode}), @code{sit-for} cannot be +interrupted, even by input from the standard input descriptor. It is +thus equivalent to @code{sleep-for}, which is described below. It is also possible to call @code{sit-for} with three arguments, as @code{(sit-for @var{seconds} @var{millisec} @var{nodisp})}, @@ -2898,7 +2909,7 @@ using the minibuffer. Usually it is more convenient for the user if you change the major mode of the current buffer temporarily to a special major mode, which should have a command to go back to the previous mode. (The @kbd{e} command in Rmail uses this technique.) Or, if you wish to -give the user different text to edit ``recursively'', create and select +give the user different text to edit ``recursively,'' create and select a new buffer in a special mode. In this mode, define a command to complete the processing and go back to the previous buffer. (The @kbd{m} command in Rmail does this.) diff --git a/lispref/control.texi b/lispref/control.texi index d64b03037d6..3ed0b7f90ec 100644 --- a/lispref/control.texi +++ b/lispref/control.texi @@ -221,7 +221,7 @@ non-@code{nil}, the clause ``succeeds''; then @code{cond} evaluates its @var{body-forms}, and the value of the last of @var{body-forms} becomes the value of the @code{cond}. The remaining clauses are ignored. -If the value of @var{condition} is @code{nil}, the clause ``fails'', so +If the value of @var{condition} is @code{nil}, the clause ``fails,'' so the @code{cond} moves on to the following clause, trying its @var{condition}. @@ -623,7 +623,7 @@ error is signaled with data @code{(@var{tag} @var{value})}. @subsection Examples of @code{catch} and @code{throw} One way to use @code{catch} and @code{throw} is to exit from a doubly -nested loop. (In most languages, this would be done with a ``go to''.) +nested loop. (In most languages, this would be done with a ``go to.'') Here we compute @code{(foo @var{i} @var{j})} for @var{i} and @var{j} varying from 0 to 9: @@ -783,8 +783,11 @@ undesirable results. Instead, use @code{(error "%s" @var{string})}. @end defun @defun signal error-symbol data +This @anchor{Definition of signal} -This function signals an error named by @var{error-symbol}. The +@c unfortunately, a page break is allowed if the anchor immediately +@c follows the @defun, due to hard-to-fix TeXnicalities. +function signals an error named by @var{error-symbol}. The argument @var{data} is a list of additional Lisp objects relevant to the circumstances of the error. @@ -846,11 +849,22 @@ executes in the environment of the @code{condition-case} that established it; all functions called within that @code{condition-case} have already been exited, and the handler cannot return to them. -If there is no applicable handler for the error, the current command is -terminated and control returns to the editor command loop, because the -command loop has an implicit handler for all kinds of errors. The +If there is no applicable handler for the error, it terminates the +current command and returns control to the editor command loop. (The +command loop has an implicit handler for all kinds of errors.) The command loop's handler uses the error symbol and associated data to -print an error message. +print an error message. You can use the variable +@code{command-error-function} to control how this is done: + +@defvar command-error-function +This variable, if non-@code{nil}, specifies a function to use to +handle errors that return control to the Emacs command loop. The +function should take three arguments: @var{data}, a list of the same +form that @code{condition-case} would bind to its variable; +@var{context}, a string describing the situation in which the error +occurred, or (more often) @code{nil}; and @code{caller}, the Lisp +function which called the primitive that signaled the error. +@end defvar @cindex @code{debug-on-error} use An error that has no explicit handler may call the Lisp debugger. The diff --git a/lispref/customize.texi b/lispref/customize.texi index da2b8a068f9..3aca1a90bcf 100644 --- a/lispref/customize.texi +++ b/lispref/customize.texi @@ -699,7 +699,7 @@ that you specify for it. @item (list @var{element-types}@dots{}) The value must be a list with exactly as many elements as the -@var{element-types} you have specified; and each element must fit the +@var{element-types} given; and each element must fit the corresponding @var{element-type}. For example, @code{(list integer string function)} describes a list of @@ -718,7 +718,7 @@ The value must fit at least one of @var{alternative-types}. For example, @code{(choice integer string)} allows either an integer or a string. -In the customization buffer, the user selects one of the alternatives +In the customization buffer, the user selects an alternative using a menu, and can then edit the value in the usual way for that alternative. diff --git a/lispref/display.texi b/lispref/display.texi index 5687091a31f..678ca657b5b 100644 --- a/lispref/display.texi +++ b/lispref/display.texi @@ -103,8 +103,8 @@ processes the available input before trying again to redisplay. If this variable is @code{nil}, Emacs does not check for input during redisplay, and redisplay cannot be preempted by input. -@emph{Note} that this variable is only available if Emacs is built -with support for sub-second timers. +This variable is only obeyed on graphical terminals. For +text terminals, see @ref{Terminal Output}. @end defvar @defvar redisplay-dont-pause @@ -141,7 +141,7 @@ boundary. @xref{Filling}. indicate truncated and continued lines (@pxref{Fringes}). On a text terminal, a @samp{$} in the rightmost column of the window indicates truncation; a @samp{\} on the rightmost column indicates a line that -``wraps''. (The display table can specify alternate characters to use +``wraps.'' (The display table can specify alternate characters to use for this; @pxref{Display Tables}). @defopt truncate-lines @@ -1189,7 +1189,7 @@ The return value is @var{overlay}. This is the only valid way to change the endpoints of an overlay. Do not try modifying the markers in the overlay by hand, as that fails to update other vital data structures and can cause some overlays to be -``lost''. +``lost.'' @end defun @defun remove-overlays &optional start end name value @@ -2013,7 +2013,7 @@ A non-@code{nil} value specifies a bold font. A non-@code{nil} value specifies an italic font. @end table - For compatibility, you can still set these ``attributes'', even + For compatibility, you can still set these ``attributes,'' even though they are not real face attributes. Here is what that does: @table @code @@ -3767,7 +3767,7 @@ $$\pmatrix{ 2 & -1 & 0 \cr @end ifnottex @item disabled -Specifies transforming the image so that it looks ``disabled''. +Specifies transforming the image so that it looks ``disabled.'' @end table @item :mask @var{mask} @@ -4804,7 +4804,7 @@ Any @var{args} are passed to @var{map-function}. @subsection Abstract Display Example Here is a simple example using functions of the ewoc package to -implement a ``color components display'', an area in a buffer that +implement a ``color components display,'' an area in a buffer that represents a vector of three integers (itself representing a 24-bit RGB value) in various ways. @@ -5320,7 +5320,7 @@ variable. @section Window Systems Emacs works with several window systems, most notably the X Window -System. Both Emacs and X use the term ``window'', but use it +System. Both Emacs and X use the term ``window,'' but use it differently. An Emacs frame is a single window as far as X is concerned; the individual Emacs windows are not known to X at all. diff --git a/lispref/doclicense.texi b/lispref/doclicense.texi index 9e191e0c0b8..f2f32aaa968 100644 --- a/lispref/doclicense.texi +++ b/lispref/doclicense.texi @@ -24,7 +24,7 @@ Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. -This License is a kind of ``copyleft'', which means that derivative +This License is a kind of ``copyleft,'' which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. @@ -45,9 +45,9 @@ This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that -work under the conditions stated herein. The ``Document'', below, +work under the conditions stated herein. The ``Document,'' below, refers to any such manual or work. Any member of the public is a -licensee, and is addressed as ``you''. You accept the license if you +licensee, and is addressed as ``you.'' You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law. @@ -114,8 +114,8 @@ preceding the beginning of the body of the text. A section ``Entitled XYZ'' means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a -specific section name mentioned below, such as ``Acknowledgements'', -``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' +specific section name mentioned below, such as ``Acknowledgements,'' +``Dedications,'' ``Endorsements,'' or ``History.'') To ``Preserve the Title'' of such a section when you modify the Document means that it remains a section ``Entitled XYZ'' according to this definition. @@ -211,7 +211,7 @@ F. Include, immediately after the copyright notices, a license notice G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.@* H. Include an unaltered copy of this License.@* -I. Preserve the section Entitled ``History'', Preserve its Title, and add +I. Preserve the section Entitled ``History,'' Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled ``History'' in the Document, create one @@ -225,7 +225,7 @@ J. Preserve the network location, if any, given in the Document for You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.@* -K. For any section Entitled ``Acknowledgements'' or ``Dedications'', +K. For any section Entitled ``Acknowledgements'' or ``Dedications,'' Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.@* @@ -245,7 +245,7 @@ of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. -You may add a section Entitled ``Endorsements'', provided it contains +You may add a section Entitled ``Endorsements,'' provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a @@ -286,7 +286,7 @@ Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections Entitled ``History'' in the various original documents, forming one section Entitled -``History''; likewise combine any sections Entitled ``Acknowledgements'', +``History''; likewise combine any sections Entitled ``Acknowledgements,'' and any sections Entitled ``Dedications.'' You must delete all sections Entitled ``Endorsements.'' @sp 1 @@ -340,8 +340,8 @@ of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail. -If a section in the Document is Entitled ``Acknowledgements'', -``Dedications'', or ``History'', the requirement (section 4) to Preserve +If a section in the Document is Entitled ``Acknowledgements,'' +``Dedications,'' or ``History,'' the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title. @sp 1 @@ -390,7 +390,7 @@ under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU -Free Documentation License''. +Free Documentation License.'' @end group @end smallexample diff --git a/lispref/edebug.texi b/lispref/edebug.texi index 731e04c5d1d..b2bab6030ed 100644 --- a/lispref/edebug.texi +++ b/lispref/edebug.texi @@ -1541,12 +1541,10 @@ The default value is @code{step}. @end defopt @defopt edebug-trace -Non-@code{nil} means display a trace of function entry and exit. +If this is non-@code{nil}, trace each function entry and exit. Tracing output is displayed in a buffer named @samp{*edebug-trace*}, one function entry or exit per line, indented by the recursion level. -The default value is @code{nil}. - Also see @code{edebug-tracing}, in @ref{Trace Buffer}. @end defopt diff --git a/lispref/elisp.texi b/lispref/elisp.texi index 9f029924e5e..db92bdc97ee 100644 --- a/lispref/elisp.texi +++ b/lispref/elisp.texi @@ -47,10 +47,10 @@ Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with the -Invariant Sections being ``GNU General Public License'', with the -Front-Cover texts being ``A GNU Manual'', and with the Back-Cover +Invariant Sections being ``GNU General Public License,'' with the +Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the license is included in the -section entitled ``GNU Free Documentation License''. +section entitled ``GNU Free Documentation License.'' (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free @@ -338,7 +338,7 @@ Kinds of Forms we find the real function via the symbol. * Function Forms:: Forms that call functions. * Macro Forms:: Forms that call macros. -* Special Forms:: ``Special forms'' are idiosyncratic primitives, +* Special Forms:: "Special forms" are idiosyncratic primitives, most of them extremely important. * Autoloading:: Functions set up to load files containing their real definitions. @@ -457,7 +457,7 @@ Loading * Repeated Loading:: Precautions about loading a file twice. * Named Features:: Loading a library if it isn't already loaded. * Where Defined:: Finding which file defined a certain symbol. -* Unloading:: How to ``unload'' a library that was loaded. +* Unloading:: How to "unload" a library that was loaded. * Hooks for Loading:: Providing code to be run when particular libraries are loaded. @@ -741,7 +741,7 @@ Buffers is visited. * Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. * Modification Time:: Determining whether the visited file was changed - ``behind Emacs's back''. + "behind Emacs's back". * Read Only Buffers:: Modifying text is not allowed in a read-only buffer. * The Buffer List:: How to look at all the existing buffers. @@ -830,8 +830,8 @@ Markers * Marker Insertion Types:: Two ways a marker can relocate when you insert where it points. * Moving Markers:: Moving the marker to a new buffer or position. -* The Mark:: How ``the mark'' is implemented with a marker. -* The Region:: How to access ``the region''. +* The Mark:: How "the mark" is implemented with a marker. +* The Region:: How to access "the region". Text @@ -862,8 +862,8 @@ Text * Registers:: How registers are implemented. Accessing the text or position stored in a register. * Base 64:: Conversion to or from base 64 encoding. -* MD5 Checksum:: Compute the MD5 ``message digest''/``checksum''. -* Atomic Changes:: Installing several buffer changes ``atomically''. +* MD5 Checksum:: Compute the MD5 "message digest"/"checksum". +* Atomic Changes:: Installing several buffer changes "atomically". * Change Hooks:: Supplying functions to be run when text is changed. The Kill Ring diff --git a/lispref/eval.texi b/lispref/eval.texi index 803f3d4a70d..05229c1b7c0 100644 --- a/lispref/eval.texi +++ b/lispref/eval.texi @@ -106,7 +106,7 @@ described below (@pxref{Forms}). A Lisp object that is intended to be evaluated is called a @dfn{form}. How Emacs evaluates a form depends on its data type. Emacs has three different kinds of form that are evaluated differently: symbols, lists, -and ``all other types''. This section describes all three kinds, one by +and ``all other types.'' This section describes all three kinds, one by one, starting with the ``all other types'' which are self-evaluating forms. @@ -118,7 +118,7 @@ forms. we find the real function via the symbol. * Function Forms:: Forms that call functions. * Macro Forms:: Forms that call macros. -* Special Forms:: ``Special forms'' are idiosyncratic primitives, +* Special Forms:: "Special forms" are idiosyncratic primitives, most of them extremely important. * Autoloading:: Functions set up to load files containing their real definitions. diff --git a/lispref/files.texi b/lispref/files.texi index dbcf37b5c8d..03e5db318f4 100644 --- a/lispref/files.texi +++ b/lispref/files.texi @@ -658,7 +658,7 @@ The file lock is really a file, a symbolic link with a special name, stored in the same directory as the file you are editing. When you access files using NFS, there may be a small probability that -you and another user will both lock the same file ``simultaneously''. +you and another user will both lock the same file ``simultaneously.'' If this happens, it is possible for the two users to make changes simultaneously, but Emacs will still warn the user who saves second. Also, the detection of modification of a buffer visiting a file changed @@ -1681,7 +1681,7 @@ return value, but backup version numbers are kept. @end defun @defun file-name-extension filename &optional period -This function returns @var{filename}'s final ``extension'', if any, +This function returns @var{filename}'s final ``extension,'' if any, after applying @code{file-name-sans-versions} to remove any version/backup part. The extension, in a file name, is the part that starts with the last @samp{.} in the last name component (minus @@ -2653,7 +2653,7 @@ unlocking the buffer if it is locked. possibly others to be added in the future. It need not implement all these operations itself---when it has nothing special to do for a certain operation, it can reinvoke the primitive, to handle the -operation ``in the usual way''. It should always reinvoke the primitive +operation ``in the usual way.'' It should always reinvoke the primitive for an operation it does not recognize. Here's one way to do this: @smallexample diff --git a/lispref/frames.texi b/lispref/frames.texi index 6652c0d6eb7..08b4c3be531 100644 --- a/lispref/frames.texi +++ b/lispref/frames.texi @@ -641,7 +641,7 @@ This variable specifies how to blink the cursor. Each element has the form @code{(@var{on-state} . @var{off-state})}. Whenever the cursor type equals @var{on-state} (comparing using @code{equal}), the corresponding @var{off-state} specifies what the cursor looks like -when it blinks ``off''. Both @var{on-state} and @var{off-state} +when it blinks ``off.'' Both @var{on-state} and @var{off-state} should be suitable values for the @code{cursor-type} frame parameter. There are various defaults for how to blink each type of cursor, if @@ -967,7 +967,7 @@ internals of Emacs. @defun visible-frame-list This function returns a list of just the currently visible frames. @xref{Visibility of Frames}. (Terminal frames always count as -``visible'', even though only the selected one is actually displayed.) +``visible,'' even though only the selected one is actually displayed.) @end defun @defun next-frame &optional frame minibuf @@ -1189,7 +1189,9 @@ change it. This option is how you inform Emacs whether the window manager transfers focus when the user moves the mouse. Non-@code{nil} says that it does. When this is so, the command @code{other-frame} moves the mouse to a -position consistent with the new selected frame. +position consistent with the new selected frame. (This option has no +effect on MS-Windows, where the mouse pointer is always automatically +moved by the OS to the selected frame.) @end defopt @node Visibility of Frames @@ -1251,7 +1253,7 @@ changes. @xref{Misc Events}. Most window systems use a desktop metaphor. Part of this metaphor is the idea that windows are stacked in a notional third dimension perpendicular to the screen surface, and thus ordered from ``highest'' -to ``lowest''. Where two windows overlap, the one higher up covers +to ``lowest.'' Where two windows overlap, the one higher up covers the one underneath. Even a window at the bottom of the stack can be seen if no other window overlaps it. @@ -1259,7 +1261,7 @@ seen if no other window overlaps it. @cindex lowering a frame A window's place in this ordering is not fixed; in fact, users tend to change the order frequently. @dfn{Raising} a window means moving -it ``up'', to the top of the stack. @dfn{Lowering} a window means +it ``up,'' to the top of the stack. @dfn{Lowering} a window means moving it to the bottom of the stack. This motion is in the notional third dimension only, and does not change the position of the window on the screen. @@ -1519,7 +1521,7 @@ the menu keymap as necessary. A dialog box is a variant of a pop-up menu---it looks a little different, it always appears in the center of a frame, and it has just one level and one or more buttons. The main use of dialog boxes is -for asking questions that the user can answer with ``yes'', ``no'', +for asking questions that the user can answer with ``yes,'' ``no,'' and a few other alternatives. With a single button, they can also force the user to acknowledge important information. The functions @code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the @@ -1780,7 +1782,7 @@ colors.) These functions provide a way to determine which color names are valid, and what they look like. In some cases, the value depends on the @dfn{selected frame}, as described below; see @ref{Input Focus}, for the -meaning of the term ``selected frame''. +meaning of the term ``selected frame.'' @defun color-defined-p color &optional frame This function reports whether a color name is meaningful. It returns @@ -2150,7 +2152,7 @@ software (as a string). Really this means whoever distributes the X server. When the developers of X labelled software distributors as -``vendors'', they showed their false assumption that no system could +``vendors,'' they showed their false assumption that no system could ever be developed and distributed noncommercially. @end defun diff --git a/lispref/functions.texi b/lispref/functions.texi index 7068b385ecf..a4c0b4b8fe4 100644 --- a/lispref/functions.texi +++ b/lispref/functions.texi @@ -485,7 +485,7 @@ more convenient than making the function definition point to itself practice). We often identify functions with the symbols used to name them. For -example, we often speak of ``the function @code{car}'', not +example, we often speak of ``the function @code{car},'' not distinguishing between the symbol @code{car} and the primitive subr-object that is its function definition. For most purposes, the distinction is not important. @@ -766,12 +766,10 @@ in turn, and returns a list of the results. The argument @var{sequence} can be any kind of sequence except a char-table; that is, a list, a vector, a bool-vector, or a string. The result is always a list. The length of the result is the same as the -length of @var{sequence}. +length of @var{sequence}. For example: @smallexample @group -@exdent @r{For example:} - (mapcar 'car '((a b) (c d) (e f))) @result{} (a c e) (mapcar '1+ [1 2 3]) @@ -846,7 +844,7 @@ bool-vector, or a string. In Lisp, a function is a list that starts with @code{lambda}, a byte-code function compiled from such a list, or alternatively a -primitive subr-object; names are ``extra''. Although usually functions +primitive subr-object; names are ``extra.'' Although usually functions are defined with @code{defun} and given names at the same time, it is occasionally more concise to use an explicit lambda expression---an anonymous function. Such a list is valid wherever a function name is. diff --git a/lispref/gpl.texi b/lispref/gpl.texi index d3ffb26719b..ac5c9938381 100644 --- a/lispref/gpl.texi +++ b/lispref/gpl.texi @@ -75,13 +75,13 @@ modification follow. @item This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed -under the terms of this General Public License. The ``Program'', below, +under the terms of this General Public License. The ``Program,'' below, refers to any such program or work, and a ``work based on the Program'' means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in -the term ``modification''.) Each licensee is addressed as ``you''. +the term ``modification.'') Each licensee is addressed as ``you.'' Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of @@ -274,7 +274,7 @@ address new problems or concerns. Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and ``any -later version'', you have the option of following the terms and conditions +later version,'' you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software diff --git a/lispref/hash.texi b/lispref/hash.texi index 1913905af8d..4c2c3469c86 100644 --- a/lispref/hash.texi +++ b/lispref/hash.texi @@ -79,13 +79,13 @@ alternatives: Keys which are numbers are ``the same'' if they are @code{equal}, that is, if they are equal in value and either both are integers or both are floating point numbers; otherwise, two distinct objects are never -``the same''. +``the same.'' @item eq Any two distinct Lisp objects are ``different'' as keys. @item equal -Two Lisp objects are ``the same'', as keys, if they are equal +Two Lisp objects are ``the same,'' as keys, if they are equal according to @code{equal}. @end table @@ -269,7 +269,6 @@ compared case-insensitively. @example (defun case-fold-string= (a b) (compare-strings a nil nil b nil nil t)) - (defun case-fold-string-hash (a) (sxhash (upcase a))) diff --git a/lispref/internals.texi b/lispref/internals.texi index a4ee6223b35..db7694585aa 100644 --- a/lispref/internals.texi +++ b/lispref/internals.texi @@ -1270,7 +1270,7 @@ Non-@code{nil} means current value of @code{start} was the beginning of a line when it was chosen. @item too_small_ok -Non-@code{nil} means don't delete this window for becoming ``too small''. +Non-@code{nil} means don't delete this window for becoming ``too small.'' @item height_fixed_p This field is temporarily set to 1 to fix the height of the selected diff --git a/lispref/intro.texi b/lispref/intro.texi index 7e1b6155b35..cd9b36ced85 100644 --- a/lispref/intro.texi +++ b/lispref/intro.texi @@ -160,7 +160,7 @@ printer'' refer to those routines in Lisp that convert textual representations of Lisp objects into actual Lisp objects, and vice versa. @xref{Printed Representation}, for more details. You, the person reading this manual, are thought of as ``the programmer'' and are -addressed as ``you''. ``The user'' is the person who uses Lisp +addressed as ``you.'' ``The user'' is the person who uses Lisp programs, including those you write. @cindex fonts in this manual @@ -233,7 +233,7 @@ the examples in this manual, this is indicated with @samp{@result{}}: @end example @noindent -You can read this as ``@code{(car '(1 2))} evaluates to 1''. +You can read this as ``@code{(car '(1 2))} evaluates to 1.'' When a form is a macro call, it expands into a new form for Lisp to evaluate. We show the result of the expansion with diff --git a/lispref/keymaps.texi b/lispref/keymaps.texi index 38f7fbac77c..f93c94b8dfe 100644 --- a/lispref/keymaps.texi +++ b/lispref/keymaps.texi @@ -2232,7 +2232,7 @@ Next we define the menu items: Note the symbols which the bindings are ``made for''; these appear inside square brackets, in the key sequence being defined. In some cases, this symbol is the same as the command name; sometimes it is -different. These symbols are treated as ``function keys'', but they are +different. These symbols are treated as ``function keys,'' but they are not real function keys on the keyboard. They do not affect the functioning of the menu itself, but they are ``echoed'' in the echo area when the user selects from the menu, and they appear in the output of diff --git a/lispref/lists.texi b/lispref/lists.texi index 7de4a6c6ab0..cb60baef900 100644 --- a/lispref/lists.texi +++ b/lispref/lists.texi @@ -20,6 +20,7 @@ the whole list. * List-related Predicates:: Is this object a list? Comparing two lists. * List Elements:: Extracting the pieces of a list. * Building Lists:: Creating list structure. +* List Variables:: Modifying lists stored in variables. * Modifying Lists:: Storing new pieces into an existing list. * Sets And Lists:: A list can represent a finite mathematical set. * Association Lists:: A list can represent a finite relation or mapping. @@ -431,20 +432,6 @@ used in this example and the function named @code{list} described below; any symbol can serve both purposes. @end defun -@defmac push newelt listname -This macro provides an alternative way to write -@code{(setq @var{listname} (cons @var{newelt} @var{listname}))}. - -@example -(setq l '(a b)) - @result{} (a b) -(push 'c l) - @result{} (c a b) -l - @result{} (c a b) -@end example -@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} @@ -704,6 +691,124 @@ Some examples: @end example @end defun +@node List Variables +@section Modifying List Variables + + These functions, and one macro, provide convenient ways +to modify a list which is stored in a variable. + +@defmac push newelt listname +This macro provides an alternative way to write +@code{(setq @var{listname} (cons @var{newelt} @var{listname}))}. + +@example +(setq l '(a b)) + @result{} (a b) +(push 'c l) + @result{} (c a b) +l + @result{} (c a b) +@end example +@end defmac + + Two functions modify lists that are the values of variables. + +@defun add-to-list symbol element &optional append +This function sets the variable @var{symbol} by consing @var{element} +onto the old value, if @var{element} is not already a member of that +value. It returns the resulting list, whether updated or not. The +value of @var{symbol} had better be a list already before the call. +Membership is tested using @code{equal}. + +Normally, if @var{element} is added, it is added to the front of +@var{symbol}, but if the optional argument @var{append} is +non-@code{nil}, it is added at the end. + +The argument @var{symbol} is not implicitly quoted; @code{add-to-list} +is an ordinary function, like @code{set} and unlike @code{setq}. Quote +the argument yourself if that is what you want. +@end defun + +Here's a scenario showing how to use @code{add-to-list}: + +@example +(setq foo '(a b)) + @result{} (a b) + +(add-to-list 'foo 'c) ;; @r{Add @code{c}.} + @result{} (c a b) + +(add-to-list 'foo 'b) ;; @r{No effect.} + @result{} (c a b) + +foo ;; @r{@code{foo} was changed.} + @result{} (c a b) +@end example + + An equivalent expression for @code{(add-to-list '@var{var} +@var{value})} is this: + +@example +(or (member @var{value} @var{var}) + (setq @var{var} (cons @var{value} @var{var}))) +@end example + +@defun add-to-ordered-list symbol element &optional order +This function sets the variable @var{symbol} by inserting +@var{element} into the old value, which must be a list, at the +position specified by @var{order}. If @var{element} is already a +member of the list, its position in the list is adjusted according +to @var{order}. Membership is tested using @code{eq}. +This function returns the resulting list, whether updated or not. + +The @var{order} is typically a number (integer or float), and the +elements of the list are sorted in non-decreasing numerical order. + +@var{order} may also be omitted or @code{nil}. Then the numeric order +of @var{element} stays unchanged if it already has one; otherwise, +@var{element} has no numeric order. Elements without a numeric list +order are placed at the end of the list, in no particular order. + +Any other value for @var{order} removes the numeric order of @var{element} +if it already has one; otherwise, it is equivalent to @code{nil}. + +The argument @var{symbol} is not implicitly quoted; +@code{add-to-ordered-list} is an ordinary function, like @code{set} +and unlike @code{setq}. Quote the argument yourself if that is what +you want. + +The ordering information is stored in a hash table on @var{symbol}'s +@code{list-order} property. +@end defun + +Here's a scenario showing how to use @code{add-to-ordered-list}: + +@example +(setq foo '()) + @result{} nil + +(add-to-ordered-list 'foo 'a 1) ;; @r{Add @code{a}.} + @result{} (a) + +(add-to-ordered-list 'foo 'c 3) ;; @r{Add @code{c}.} + @result{} (a c) + +(add-to-ordered-list 'foo 'b 2) ;; @r{Add @code{b}.} + @result{} (a b c) + +(add-to-ordered-list 'foo 'b 4) ;; @r{Move @code{b}.} + @result{} (a c b) + +(add-to-ordered-list 'foo 'd) ;; @r{Append @code{d}.} + @result{} (a c b d) + +(add-to-ordered-list 'foo 'e) ;; @r{Add @code{e}}. + @result{} (a c b e d) + +foo ;; @r{@code{foo} was changed.} + @result{} (a c b e d) +@end example + @node Modifying Lists @section Modifying Existing List Structure @cindex destructive list operations @@ -1412,8 +1517,8 @@ the value @code{cones}; the key @code{oak} is associated with @end group @end example - The associated values in an alist may be any Lisp objects; so may the -keys. For example, in the following alist, the symbol @code{a} is + Both the values and the keys in an alist may be any Lisp objects. +For example, in the following alist, the symbol @code{a} is associated with the number @code{1}, and the string @code{"b"} is associated with the @emph{list} @code{(2 3)}, which is the @sc{cdr} of the alist element: @@ -1439,7 +1544,7 @@ below) to find the element containing a given value. When neither of these considerations is important, the choice is a matter of taste, as long as you are consistent about it for any given alist. - Note that the same alist shown above could be regarded as having the + The same alist shown above could be regarded as having the associated value in the @sc{cdr} of the element; the value associated with @code{rose} would be the list @code{(red)}. @@ -1503,7 +1608,7 @@ a @sc{cdr} @code{equal} to @var{value}. @code{rassoc} is like @code{assoc} except that it compares the @sc{cdr} of each @var{alist} association instead of the @sc{car}. You can think of -this as ``reverse @code{assoc}'', finding the key for a given value. +this as ``reverse @code{assoc},'' finding the key for a given value. @end defun @defun assq key alist @@ -1544,7 +1649,7 @@ a @sc{cdr} @code{eq} to @var{value}. @code{rassq} is like @code{assq} except that it compares the @sc{cdr} of each @var{alist} association instead of the @sc{car}. You can think of -this as ``reverse @code{assq}'', finding the key for a given value. +this as ``reverse @code{assq},'' finding the key for a given value. For example: @@ -1557,7 +1662,7 @@ For example: @result{} nil @end smallexample -Note that @code{rassq} cannot search for a value stored in the @sc{car} +@code{rassq} cannot search for a value stored in the @sc{car} of the @sc{cdr} of an element: @smallexample diff --git a/lispref/loading.texi b/lispref/loading.texi index 81787082117..eb576f8fbbc 100644 --- a/lispref/loading.texi +++ b/lispref/loading.texi @@ -43,7 +43,7 @@ containing Lisp code. * Repeated Loading:: Precautions about loading a file twice. * Named Features:: Loading a library if it isn't already loaded. * Where Defined:: Finding which file defined a certain symbol. -* Unloading:: How to ``unload'' a library that was loaded. +* Unloading:: How to "unload" a library that was loaded. * Hooks for Loading:: Providing code to be run when particular libraries are loaded. @end menu @@ -155,8 +155,10 @@ file, and it is @code{nil} otherwise. @end defvar @defvar load-read-function +This @anchor{Definition of load-read-function} -This variable specifies an alternate expression-reading function for +@c do not allow page break at anchor; work around Texinfo deficiency. +variable specifies an alternate expression-reading function for @code{load} and @code{eval-region} to use instead of @code{read}. The function should accept one argument, just as @code{read} does. diff --git a/lispref/maps.texi b/lispref/maps.texi index 9ee1b52fa59..ec7728f7840 100644 --- a/lispref/maps.texi +++ b/lispref/maps.texi @@ -12,11 +12,17 @@ Some of these exist when Emacs is first started, others are loaded only when their respective mode is used. This is not an exhaustive list. +Several keymaps are used in the minibuffer. @xref{Completion Commands}. + Almost all of these maps are used as local maps. Indeed, of the modes that presently exist, only Vip mode and Terminal mode ever change the global keymap. @table @code +@item apropos-mode-map +@vindex apropos-mode-map +A sparse keymap for @code{apropos} buffers. + @item Buffer-menu-mode-map @vindex Buffer-menu-mode-map A full keymap used by Buffer Menu mode. @@ -38,6 +44,9 @@ A sparse keymap for subcommands of the prefix @kbd{C-x 5}. @item ctl-x-map A full keymap for @kbd{C-x} commands. +@item custom-mode-map +A full keymap for Custom mode. + @item debugger-mode-map @vindex debugger-mode-map A full keymap used by Debugger mode. @@ -66,6 +75,10 @@ A full keymap used by Electric Command History mode. @vindex emacs-lisp-mode-map A sparse keymap used by Emacs Lisp mode. +@item esc-map +@vindex esc-map +A full keymap for @kbd{ESC} (or @kbd{Meta}) commands. + @item facemenu-menu @vindex facemenu-menu The sparse keymap that displays the Text Properties menu. @@ -109,6 +122,21 @@ If there are none, then it contains an empty sparse keymap. The sparse keymap for Fundamental mode.@* It is empty and should not be changed. +@item global-map +The full keymap containing default global key bindings.@* +Modes should not modify the Global map. + +@item grep-mode-map +@vindex grep-mode-map +The keymap for @code{grep-mode} buffers. + +@item help-map +The sparse keymap for the keys that follow the help character @kbd{C-h}. + +@item help-mode-map +@vindex help-mode-map +The sparse keymap for Help mode. + @item Helper-help-map @vindex Helper-help-map A full keymap used by the help utility package.@* @@ -132,6 +160,11 @@ search. A keymap for translating keys. This one overrides ordinary key bindings, unlike @code{function-key-map}. @xref{Translating Input}. +@item kmacro-map +@vindex kmacro-map +A sparse keymap for keys that follows the @kbd{C-x C-k} prefix +search. + @item lisp-interaction-mode-map @vindex lisp-interaction-mode-map A sparse keymap used by Lisp Interaction mode. @@ -184,6 +217,9 @@ time. @vindex text-mode-map A sparse keymap used by Text mode. +@item tool-bar-map +The keymap defining the contents of the tool bar. + @item view-mode-map @vindex view-mode-map A full keymap used by View mode. diff --git a/lispref/markers.texi b/lispref/markers.texi index 514b93a2df5..c3fdddc6aab 100644 --- a/lispref/markers.texi +++ b/lispref/markers.texi @@ -21,8 +21,8 @@ deleted, so that it stays with the two characters on either side of it. * Marker Insertion Types:: Two ways a marker can relocate when you insert where it points. * Moving Markers:: Moving the marker to a new buffer or position. -* The Mark:: How ``the mark'' is implemented with a marker. -* The Region:: How to access ``the region''. +* The Mark:: How "the mark" is implemented with a marker. +* The Region:: How to access "the region". @end menu @node Overview of Markers diff --git a/lispref/minibuf.texi b/lispref/minibuf.texi index d05329eeed7..d4f94e5269b 100644 --- a/lispref/minibuf.texi +++ b/lispref/minibuf.texi @@ -208,8 +208,10 @@ properties unconditionally, regardless of the value of this variable. @end defvar @defvar minibuffer-local-map +This @anchor{Definition of minibuffer-local-map} -This is the default local keymap for reading from the minibuffer. By +@c avoid page break at anchor; work around Texinfo deficiency +is the default local keymap for reading from the minibuffer. By default, it makes the following bindings: @table @asis @@ -1509,7 +1511,7 @@ the call. This function asks the user a question, expecting input in the echo area. It returns @code{t} if the user types @kbd{y}, @code{nil} if the user types @kbd{n}. This function also accepts @key{SPC} to mean yes -and @key{DEL} to mean no. It accepts @kbd{C-]} to mean ``quit'', like +and @key{DEL} to mean no. It accepts @kbd{C-]} to mean ``quit,'' like @kbd{C-g}, because the question might look like a minibuffer and for that reason the user might try to use @kbd{C-]} to get out. The answer is a single character, with no @key{RET} needed to terminate it. Upper @@ -1699,7 +1701,7 @@ answer); @var{function} is a function of one argument (an object from When the user responds with @var{char}, @code{map-y-or-n-p} calls @var{function}. If it returns non-@code{nil}, the object is considered -``acted upon'', and @code{map-y-or-n-p} advances to the next object in +``acted upon,'' and @code{map-y-or-n-p} advances to the next object in @var{list}. If it returns @code{nil}, the prompt is repeated for the same object. diff --git a/lispref/modes.texi b/lispref/modes.texi index c98039d7ae0..b0c057ec1c9 100644 --- a/lispref/modes.texi +++ b/lispref/modes.texi @@ -145,7 +145,7 @@ If @var{function} is already present in @var{hook} (comparing using It is best to design your hook functions so that the order in which they are executed does not matter. Any dependence on the order is ``asking -for trouble''. However, the order is predictable: normally, +for trouble.'' However, the order is predictable: normally, @var{function} goes at the front of the hook list, so it will be executed first (barring another @code{add-hook} call). If the optional argument @var{append} is non-@code{nil}, the new hook function goes at @@ -1139,7 +1139,7 @@ it should not use @code{after-change-major-mode-hook} as of yet. When you defined a major mode using @code{define-derived-mode}, it automatically makes sure these conventions are followed. If you -define a major mode ``from scratch'', not using +define a major mode ``from scratch,'' not using @code{define-derived-mode}, make sure the major mode command follows these and other conventions. @xref{Major Mode Conventions}. You use these functions to do it properly. @@ -1354,9 +1354,8 @@ substituting your own definition of @code{self-insert-command} for the standard one. The editor command loop handles this function specially.) 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{:}, and @kbd{;}. (Those few punctuation -characters are reserved for major modes.) +followed by one of @kbd{.,/?`'"[]\|~!#$%^&*()-_+=}. (The other +punctuation characters are reserved for major modes.) @node Defining Minor Modes @subsection Defining Minor Modes @@ -1456,7 +1455,7 @@ See the command \\[hungry-electric-delete]." @end smallexample @noindent -This defines a minor mode named ``Hungry mode'', a command named +This defines a minor mode named ``Hungry mode,'' a command named @code{hungry-mode} to toggle it, a variable named @code{hungry-mode} which indicates whether the mode is enabled, and a variable named @code{hungry-mode-map} which holds the keymap that is active when the @@ -2918,7 +2917,8 @@ way for a mode to set this variable to @code{t} is with @defvar font-lock-syntax-table This variable holds the syntax table to use for fontification of comments and strings. Specify it using @var{syntax-alist} in -@code{font-lock-defaults}. +@code{font-lock-defaults}. If this is @code{nil}, fontification uses +the buffer's syntax table. @end defvar @defvar font-lock-beginning-of-syntax-function @@ -3049,7 +3049,7 @@ constructs: @itemize @item -Place a @code{font-lock-multiline} or @code{jit-lock-defer-multiline} +Place a @code{font-lock-multiline} property on the construct when it is added to the buffer. @item Use @code{font-lock-fontify-region-function} hook to extend the scan @@ -3076,7 +3076,6 @@ this can be an attractive solution. Place a @code{jit-lock-defer-multiline} property on the construct. This works only if @code{jit-lock-contextually} is used, but it can handle the case where highlighting depends on subsequent lines. -@item @end itemize @menu diff --git a/lispref/numbers.texi b/lispref/numbers.texi index bac3b0e114c..fd730420cc6 100644 --- a/lispref/numbers.texi +++ b/lispref/numbers.texi @@ -606,12 +606,11 @@ otherwise, it signals an @code{arith-error} error. @result{} 2.5 (/ 25 3 2) @result{} 4 +@group (/ -17 6) - @result{} -2 + @result{} -2 @r{(could in theory be @minus{}3 on some machines)} +@end group @end example - -The result of @code{(/ -17 6)} could in principle be -3 on some -machines. @end defun @defun % dividend divisor @@ -738,7 +737,7 @@ and returns that value as a floating point number. sequence of @dfn{bits} (digits which are either zero or one). A bitwise operation acts on the individual bits of such a sequence. For example, @dfn{shifting} moves the whole sequence left or right one or more places, -reproducing the same pattern ``moved over''. +reproducing the same pattern ``moved over.'' The bitwise operations in Emacs Lisp apply only to integers. diff --git a/lispref/objects.texi b/lispref/objects.texi index 3b51b96c780..cfb3864e9c9 100644 --- a/lispref/objects.texi +++ b/lispref/objects.texi @@ -632,7 +632,7 @@ come to refer to any structure made out of cons cells. @cindex atom Because cons cells are so central to Lisp, we also have a word for -``an object which is not a cons cell''. These objects are called +``an object which is not a cons cell.'' These objects are called @dfn{atoms}. @cindex parenthesis @@ -1195,18 +1195,19 @@ Hash tables have no read syntax, and print using hash notation. @node Function Type @subsection Function Type - Just as functions in other programming languages are executable, -@dfn{Lisp function} objects are pieces of executable code. However, -functions in Lisp are primarily Lisp objects, and only secondarily the -text which represents them. These Lisp objects are lambda expressions: -lists whose first element is the symbol @code{lambda} (@pxref{Lambda -Expressions}). + Lisp functions are executable code, just like functions in other +programming languages. In Lisp, unlike most languages, functions are +also Lisp objects. A non-compiled function in Lisp is a lambda +expression: that is, a list whose first element is the symbol +@code{lambda} (@pxref{Lambda Expressions}). In most programming languages, it is impossible to have a function without a name. In Lisp, a function has no intrinsic name. A lambda -expression is also called an @dfn{anonymous function} (@pxref{Anonymous -Functions}). A named function in Lisp is actually a symbol with a valid -function in its function cell (@pxref{Defining Functions}). +expression can be called as a function even though it has no name; to +emphasize this, we also call it an @dfn{anonymous function} +(@pxref{Anonymous Functions}). A named function in Lisp is just a +symbol with a valid function in its function cell (@pxref{Defining +Functions}). Most of the time, functions are called when their names are written in Lisp expressions in Lisp programs. However, you can construct or obtain @@ -1238,7 +1239,7 @@ without qualification, we mean a Lisp macro, not a keyboard macro. A @dfn{primitive function} is a function callable from Lisp but written in the C programming language. Primitive functions are also called @dfn{subrs} or @dfn{built-in functions}. (The word ``subr'' is -derived from ``subroutine''.) Most primitive functions evaluate all +derived from ``subroutine.'') Most primitive functions evaluate all their arguments when they are called. A primitive function that does not evaluate all its arguments is called a @dfn{special form} (@pxref{Special Forms}).@refill @@ -1822,12 +1823,14 @@ This function returns a symbol naming the primitive type of @example (type-of 1) @result{} integer +@group (type-of 'nil) @result{} symbol (type-of '()) ; @r{@code{()} is @code{nil}.} @result{} symbol (type-of '(x)) @result{} cons +@end group @end example @end defun diff --git a/lispref/os.texi b/lispref/os.texi index 5451ec8ecfd..e3634746988 100644 --- a/lispref/os.texi +++ b/lispref/os.texi @@ -1836,10 +1836,11 @@ tells you what Emacs thinks is the output speed of the terminal. This variable's value is the output speed of the terminal, as far as Emacs knows. Setting this variable does not change the speed of actual data transmission, but the value is used for calculations such as -padding. It also affects decisions about whether to scroll part of the -screen or repaint---even when using a window system. (We designed it -this way despite the fact that a window system has no true ``output -speed'', to give you a way to tune these decisions.) +padding. + + It also affects decisions about whether to scroll part of the +screen or repaint on text terminals. @xref{Forcing Redisplay}, +for the corresponding functionality on graphical terminals. The value is measured in baud. @end defvar diff --git a/lispref/processes.texi b/lispref/processes.texi index a97690c698b..a6f43cfa95d 100644 --- a/lispref/processes.texi +++ b/lispref/processes.texi @@ -23,7 +23,7 @@ subprocess, the Lisp program waits for the subprocess to terminate before continuing execution. When you create an asynchronous subprocess, it can run in parallel with the Lisp program. This kind of subprocess is represented within Emacs by a Lisp object which is also -called a ``process''. Lisp programs can use this object to communicate +called a ``process.'' Lisp programs can use this object to communicate with the subprocess or to control it. For example, you can send signals, obtain status information, receive output from the process, or send input to it. @@ -1724,13 +1724,14 @@ level that that of @code{open-network-stream}, using @code{make-network-process}. @menu -* Make Network:: Using @code{make-network-process}. -* Network Options:: Further control over network connections. -* Network Feature Testing:: Determining which network features work on +* Proc: Network Processes. Using @code{make-network-process}. +* Options: Network Options. Further control over network connections. +* Features: Network Feature Testing. + Determining which network features work on the machine you are using. @end menu -@node Make Network +@node Network Processes @subsection @code{make-network-process} The basic function for creating network connections and network @@ -2106,7 +2107,7 @@ processed, and how to pack or unpack it. that the field represents and, in the case of multibyte fields, how the bytes are ordered within the field. The two possible orderings are ``big endian'' (also known as ``network byte ordering'') and -``little endian''. For instance, the number @code{#x23cd} (decimal +``little endian.'' For instance, the number @code{#x23cd} (decimal 9165) in big endian would be the two bytes @code{#x23} @code{#xcd}; and in little endian, @code{#xcd} @code{#x23}. Here are the possible type values: diff --git a/lispref/sequences.texi b/lispref/sequences.texi index 9efd38e3abe..35cff43739d 100644 --- a/lispref/sequences.texi +++ b/lispref/sequences.texi @@ -513,8 +513,8 @@ Functions}, @code{concat} in @ref{Creating Strings}, and @code{append} in @ref{Building Lists}. @end defun - The @code{append} function provides a way to convert a vector into a -list with the same elements (@pxref{Building Lists}): + The @code{append} function also provides a way to convert a vector into a +list with the same elements: @example @group diff --git a/lispref/streams.texi b/lispref/streams.texi index 8b28f06ac70..4fad9a2a3cd 100644 --- a/lispref/streams.texi +++ b/lispref/streams.texi @@ -116,7 +116,7 @@ When it is called with one argument (always a character), @var{function} should save the argument and arrange to return it on the next call. This is called @dfn{unreading} the character; it happens when the Lisp reader reads one character too many and wants to ``put it back where it -came from''. In this case, it makes no difference what value +came from.'' In this case, it makes no difference what value @var{function} returns. @end itemize @@ -620,7 +620,7 @@ spacing between calls. @defun terpri &optional stream @cindex newline in print This function outputs a newline to @var{stream}. The name stands -for ``terminate print''. +for ``terminate print.'' @end defun @defun write-char character &optional stream diff --git a/lispref/strings.texi b/lispref/strings.texi index 796090bb80c..46c01982f32 100644 --- a/lispref/strings.texi +++ b/lispref/strings.texi @@ -285,7 +285,7 @@ If @var{omit-nulls} is @code{nil}, the result contains null strings whenever there are two consecutive matches for @var{separators}, or a match is adjacent to the beginning or end of @var{string}. If @var{omit-nulls} is @code{t}, these null strings are omitted from the -result list. +result. If @var{separators} is @code{nil} (or omitted), the default is the value of @code{split-string-default-separators}. @@ -544,10 +544,11 @@ be a list of strings rather than an actual alist. @xref{Association Lists}. @end defun - See also @code{compare-buffer-substrings} in @ref{Comparing Text}, for -a way to compare text in buffers. The function @code{string-match}, -which matches a regular expression against a string, can be used -for a kind of string comparison; see @ref{Regexp Search}. + See also the @code{compare-buffer-substrings} function in +@ref{Comparing Text}, for a way to compare text in buffers. The +function @code{string-match}, which matches a regular expression +against a string, can be used for a kind of string comparison; see +@ref{Regexp Search}. @node String Conversion @comment node-name, next, previous, up @@ -566,7 +567,7 @@ text representation of a string (@pxref{Converting Representations}). @xref{Documentation}, for functions that produce textual descriptions of text characters and general input events (@code{single-key-description} and @code{text-char-description}). These -functions are used primarily for making help messages. +are used primarily for making help messages. @defun char-to-string character @cindex character to string @@ -809,7 +810,7 @@ operation} error. @cindex field width @cindex padding - All the specification characters allow an optional ``width'', which + All the specification characters allow an optional ``width,'' which is a digit-string between the @samp{%} and the character. If the printed representation of the object contains fewer characters than this width, then it is padded. The padding is on the left if the @@ -880,7 +881,7 @@ A space character inserts a space for positive numbers (otherwise nothing is inserted for positive numbers). This flag is ignored except for @samp{%d}, @samp{%e}, @samp{%f}, @samp{%g}. -The flag @samp{#} indicates ``alternate form''. For @samp{%o} it +The flag @samp{#} indicates ``alternate form.'' For @samp{%o} it ensures that the result begins with a 0. For @samp{%x} and @samp{%X} the result is prefixed with @samp{0x} or @samp{0X}. For @samp{%e}, @samp{%f}, and @samp{%g} a decimal point is always shown even if the diff --git a/lispref/symbols.texi b/lispref/symbols.texi index f484b0da067..a1b2b8855be 100644 --- a/lispref/symbols.texi +++ b/lispref/symbols.texi @@ -160,7 +160,7 @@ be customized, use @code{defcustom} (@pxref{Customization}). @code{defun} defines a symbol as a function, creating a lambda expression and storing it in the function cell of the symbol. This lambda expression thus becomes the function definition of the symbol. -(The term ``function definition'', meaning the contents of the function +(The term ``function definition,'' meaning the contents of the function cell, is derived from the idea that @code{defun} gives the symbol its definition as a function.) @code{defsubst} and @code{defalias} are two other ways of defining a function. @xref{Functions}. diff --git a/lispref/syntax.texi b/lispref/syntax.texi index 305f347c9f6..54b0d4a0bc0 100644 --- a/lispref/syntax.texi +++ b/lispref/syntax.texi @@ -332,8 +332,8 @@ Emacs supports two comment styles simultaneously in any one syntax table. This is for the sake of C++. Each style of comment syntax has its own comment-start sequence and its own comment-end sequence. Each comment must stick to one style or the other; thus, if it starts with -the comment-start sequence of style ``b'', it must also end with the -comment-end sequence of style ``b''. +the comment-start sequence of style ``b,'' it must also end with the +comment-end sequence of style ``b.'' The two comment-start sequences must begin with the same character; only the second character may differ. Mark the second character of the @@ -706,7 +706,7 @@ The minimum parenthesis depth encountered during this scan. @item What kind of comment is active: @code{nil} for a comment of style ``a'' or when not inside a comment, @code{t} for a comment of style -``b'', and @code{syntax-table} for a comment that should be ended by a +``b,'' and @code{syntax-table} for a comment that should be ended by a generic comment delimiter character. @item diff --git a/lispref/text.texi b/lispref/text.texi index c598a4c2010..898f33443b5 100644 --- a/lispref/text.texi +++ b/lispref/text.texi @@ -57,8 +57,8 @@ the character after point. * Registers:: How registers are implemented. Accessing the text or position stored in a register. * Base 64:: Conversion to or from base 64 encoding. -* MD5 Checksum:: Compute the MD5 ``message digest''/``checksum''. -* Atomic Changes:: Installing several buffer changes ``atomically''. +* MD5 Checksum:: Compute the MD5 "message digest"/"checksum". +* Atomic Changes:: Installing several buffer changes "atomically". * Change Hooks:: Supplying functions to be run when text is changed. @end menu @@ -566,7 +566,7 @@ error; if some of the text in it is read-only, it signals a asking for any confirmation. It returns @code{nil}. Normally, deleting a large amount of text from a buffer inhibits further -auto-saving of that buffer ``because it has shrunk''. However, +auto-saving of that buffer ``because it has shrunk.'' However, @code{erase-buffer} does not do this, the idea being that the future text is not really related to the former text, and its size should not be compared with that of the former text. @@ -817,7 +817,7 @@ that treat it as a ring. Some people think this use of the word ``kill'' is unfortunate, since it refers to operations that specifically @emph{do not} destroy the -entities ``killed''. This is in sharp contrast to ordinary life, in +entities ``killed.'' This is in sharp contrast to ordinary life, in which death is permanent and ``killed'' entities do not come back to life. Therefore, other metaphors have been proposed. For example, the term ``cut ring'' makes sense to people who, in pre-computer days, used @@ -1106,8 +1106,8 @@ programs, when you are using a window system. Its value should be @code{nil} or a function of no arguments. If the value is a function, @code{current-kill} calls it to get the -``most recent kill''. If the function returns a non-@code{nil} value, -then that value is used as the ``most recent kill''. If it returns +``most recent kill.'' If the function returns a non-@code{nil} value, +then that value is used as the ``most recent kill.'' If it returns @code{nil}, then the front of the kill ring is used. The normal use of this hook is to get the window system's primary @@ -3012,24 +3012,23 @@ that all text between the character and where the mouse is have the same @item fontified @kindex fontified @r{(text property)} -This property says whether the text has had faces assigned to it by -font locking. The display engine tests it to decide whether a buffer +This property says whether the character has a face assigned to it by font +locking. The display engine tests it to decide whether a buffer portion needs refontifying before display. @xref{Auto Faces}. It -takes one of these three values---other values are invalid: +takes one of three values: @table @asis @item @code{nil} -Font locking is disabled, or the @code{face} properties on the text, -if any, are invalid. +Font locking is disabled, or the character's @code{face} property, if +any, is invalid. -@item The symbol @code{defer} -This value states that the text's @code{face} properties are invalid -and marks it for deferred fontification. It is used only when ``just -in time'' font locking is enabled. +@item @code{defer} +This value is only used when ``just in time'' font locking is enabled +and it means that the character's @code{face} property is invalid and +needs deferred fontification. @item @code{t} -The @code{face} properties, or lack of them, on the text are currently -valid. +The character's @code{face} property, or absence of one, is valid. @end table @item display @@ -3058,16 +3057,14 @@ argument is as follows: @itemize @bullet{} @item -If @var{object} is a buffer, @var{pos} is the position in the buffer -where the @code{help-echo} text property was found. +If @var{object} is a buffer, @var{pos} is the position in the buffer. @item If @var{object} is an overlay, that overlay has a @code{help-echo} -property, and @var{pos} is the position in the overlay's buffer under -the mouse. +property, and @var{pos} is the position in the overlay's buffer. @item If @var{object} is a string (an overlay string or a string displayed with the @code{display} property), @var{pos} is the position in that -string under the mouse. +string. @end itemize If the value of the @code{help-echo} property is neither a function nor @@ -3482,13 +3479,12 @@ being called over and over for the same text. @subsection Defining Clickable Text @cindex clickable text - There are two ways to set up @dfn{clickable text} in a buffer. -There are typically two parts of this: to make the text highlight -when the mouse is over it, and to make a mouse button do something -when you click it on that part of the text. + There are two parts of setting up @dfn{clickable text} in a buffer: +(1) to make that text highlight when the mouse moves over it, and (2) +to make a mouse button do something when you click on that text. - Highlighting is done with the @code{mouse-face} text property. -Here is an example of how Dired does it: + For highlighting, use the @code{mouse-face} text property. Here is +an example of how Dired does it: @smallexample (condition-case nil @@ -3666,7 +3662,8 @@ a @key{Mouse-1} click shall be translated to @key{RET}: @defun mouse-on-link-p pos This function returns non-@code{nil} if position @var{pos} in the -current buffer is on a link. +current buffer is on a link. @var{pos} can also be a mouse event +location, as returned by @code{event-start} (@pxref{Accessing Events}). @end defun @node Fields diff --git a/lispref/tips.texi b/lispref/tips.texi index 4dc24196272..3a74aa62716 100644 --- a/lispref/tips.texi +++ b/lispref/tips.texi @@ -702,15 +702,15 @@ use @code{defvar} instead, start the doc string with a @samp{*}. @item The documentation string for a variable that is a yes-or-no flag should -start with words such as ``Non-nil means@dots{}'', to make it clear that +start with words such as ``Non-nil means,'' to make it clear that all non-@code{nil} values are equivalent and indicate explicitly what @code{nil} and non-@code{nil} mean. @item The documentation string for a function that is a yes-or-no predicate -should start with words such as ``Return t if @dots{}'', to indicate -explicitly what constitutes ``truth''. The word ``return'' avoids -starting the sentence with lower-case ``t'', which is somewhat +should start with words such as ``Return t if,'' to indicate +explicitly what constitutes ``truth.'' The word ``return'' avoids +starting the sentence with lower-case ``t,'' which could be somewhat distracting. @item @@ -736,7 +736,7 @@ have the form (KEY . VALUE). Here, KEY is ... @item Never change the case of a Lisp symbol when you mention it in a doc -string. If the symbol's name is @code{foo}, write ``foo'', not +string. If the symbol's name is @code{foo}, write ``foo,'' not ``Foo'' (which is a different symbol). This might appear to contradict the policy of writing function diff --git a/lispref/variables.texi b/lispref/variables.texi index 656224367ac..5c54701cdd4 100644 --- a/lispref/variables.texi +++ b/lispref/variables.texi @@ -726,7 +726,7 @@ has no local bindings. @end group @group -;; @r{Here the value of @code{abracadabra},} +;; @r{Here, the value of @code{abracadabra},} ;; @r{which is @code{foo},} ;; @r{is the symbol whose value is examined.} (let ((abracadabra 'foo)) @@ -858,105 +858,6 @@ always affects the most local existing binding. @end quotation @end defun - One other function for setting a variable is designed to add -an element to a list if it is not already present in the list. - -@defun add-to-list symbol element &optional append -This function sets the variable @var{symbol} by consing @var{element} -onto the old value, if @var{element} is not already a member of that -value. It returns the resulting list, whether updated or not. The -value of @var{symbol} had better be a list already before the call. -Membership is tested using @code{equal}. - -Normally, if @var{element} is added, it is added to the front of -@var{symbol}, but if the optional argument @var{append} is -non-@code{nil}, it is added at the end. - -The argument @var{symbol} is not implicitly quoted; @code{add-to-list} -is an ordinary function, like @code{set} and unlike @code{setq}. Quote -the argument yourself if that is what you want. -@end defun - -Here's a scenario showing how to use @code{add-to-list}: - -@example -(setq foo '(a b)) - @result{} (a b) - -(add-to-list 'foo 'c) ;; @r{Add @code{c}.} - @result{} (c a b) - -(add-to-list 'foo 'b) ;; @r{No effect.} - @result{} (c a b) - -foo ;; @r{@code{foo} was changed.} - @result{} (c a b) -@end example - - An equivalent expression for @code{(add-to-list '@var{var} -@var{value})} is this: - -@example -(or (member @var{value} @var{var}) - (setq @var{var} (cons @var{value} @var{var}))) -@end example - -@defun add-to-ordered-list symbol element &optional order -This function sets the variable @var{symbol} by inserting -@var{element} into the old value, which must be a list, at the -position specified by @var{order}. If @var{element} is already a -member of the list, its position in the list is adjusted according -to @var{order}. Membership is tested using @code{eq}. -This function returns the resulting list, whether updated or not. - -The @var{order} is typically a number (integer or float), and the -elements of the list are sorted in non-decreasing numerical order. - -@var{order} may also be omitted or @code{nil}. Then the numeric order -of @var{element} stays unchanged if it already has one; otherwise, -@var{element} has no numeric order. Elements without a numeric list -order are placed at the end of the list, in no particular order. - -Any other value for @var{order} removes the numeric order of @var{element} -if it already has one; otherwise, it is equivalent to @code{nil}. - -The argument @var{symbol} is not implicitly quoted; -@code{add-to-ordered-list} is an ordinary function, like @code{set} -and unlike @code{setq}. Quote the argument yourself if that is what -you want. - -The ordering information is stored in a hash table on @var{symbol}'s -@code{list-order} property. -@end defun - -Here's a scenario showing how to use @code{add-to-ordered-list}: - -@example -(setq foo '()) - @result{} nil - -(add-to-ordered-list 'foo 'a 1) ;; @r{Add @code{a}.} - @result{} (a) - -(add-to-ordered-list 'foo 'c 3) ;; @r{Add @code{c}.} - @result{} (a c) - -(add-to-ordered-list 'foo 'b 2) ;; @r{Add @code{b}.} - @result{} (a b c) - -(add-to-ordered-list 'foo 'b 4) ;; @r{Move @code{b}.} - @result{} (a c b) - -(add-to-ordered-list 'foo 'd) ;; @r{Append @code{d}.} - @result{} (a c b d) - -(add-to-ordered-list 'foo 'e) ;; @r{Add @code{e}}. - @result{} (a c b e d) - -foo ;; @r{@code{foo} was changed.} - @result{} (a c b e d) -@end example - @node Variable Scoping @section Scoping Rules for Variable Bindings @@ -1096,7 +997,7 @@ is no longer bound to the actual argument 2. @end example @cindex closures not available - Some Lisp dialects have ``closures'', objects that are like functions + Some Lisp dialects have ``closures,'' objects that are like functions but record additional variable bindings. Emacs Lisp does not have closures. @@ -1459,7 +1360,7 @@ buffer-local variables interactively. @defun kill-all-local-variables This function eliminates all the buffer-local variable bindings of the -current buffer except for variables marked as ``permanent''. As a +current buffer except for variables marked as ``permanent.'' As a result, the buffer will see the default values of most variables. This function also resets certain other information pertaining to the @@ -1744,10 +1645,12 @@ local bindings, we will provide it in a subsequent Emacs version. @node File Local Variables @section File Local Variables - This section describes the functions and variables that affect -processing of file local variables. @xref{File variables, , -Local Variables in Files, emacs, The GNU Emacs Manual}, for basic -information about file local variables. + A file can specify local variable values; Emacs uses these to create +buffer-local bindings for those variables in the buffer visiting that +file. @xref{File variables, , Local Variables in Files, emacs, The +GNU Emacs Manual}, for basic information about file local variables. +This section describes the functions and variables that affect +processing of file local variables. @defopt enable-local-variables This variable controls whether to process file local variables. A diff --git a/lispref/vol1.texi b/lispref/vol1.texi index b6b071bf444..ac2958e9b09 100644 --- a/lispref/vol1.texi +++ b/lispref/vol1.texi @@ -416,7 +416,7 @@ Kinds of Forms * Classifying Lists:: How to distinguish various sorts of list forms. * Function Forms:: Forms that call functions. * Macro Forms:: Forms that call macros. -* Special Forms:: ``Special forms'' are idiosyncratic primitives, +* Special Forms:: "Special forms" are idiosyncratic primitives, most of them extremely important. * Autoloading:: Functions set up to load files containing their real definitions. @@ -709,7 +709,7 @@ Buffers is visited. * Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. * Modification Time:: Determining whether the visited file was changed - ``behind Emacs's back''. + "behind Emacs's back". * Read Only Buffers:: Modifying text is not allowed in a read-only buffer. * The Buffer List:: How to look at all the existing buffers. @@ -788,8 +788,8 @@ Markers * Information from Markers:: Finding the marker's buffer or character position. * Changing Markers:: Moving the marker to a new buffer or position. -* The Mark:: How ``the mark'' is implemented with a marker. -* The Region:: How to access ``the region''. +* The Mark:: How "the mark" is implemented with a marker. +* The Region:: How to access "the region". Text diff --git a/lispref/vol2.texi b/lispref/vol2.texi index e5da029db1a..c59449d4eee 100644 --- a/lispref/vol2.texi +++ b/lispref/vol2.texi @@ -417,7 +417,7 @@ Kinds of Forms * Classifying Lists:: How to distinguish various sorts of list forms. * Function Forms:: Forms that call functions. * Macro Forms:: Forms that call macros. -* Special Forms:: ``Special forms'' are idiosyncratic primitives, +* Special Forms:: "Special forms" are idiosyncratic primitives, most of them extremely important. * Autoloading:: Functions set up to load files containing their real definitions. @@ -710,7 +710,7 @@ Buffers is visited. * Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. * Modification Time:: Determining whether the visited file was changed - ``behind Emacs's back''. + "behind Emacs's back". * Read Only Buffers:: Modifying text is not allowed in a read-only buffer. * The Buffer List:: How to look at all the existing buffers. @@ -789,8 +789,8 @@ Markers * Information from Markers:: Finding the marker's buffer or character position. * Changing Markers:: Moving the marker to a new buffer or position. -* The Mark:: How ``the mark'' is implemented with a marker. -* The Region:: How to access ``the region''. +* The Mark:: How "the mark" is implemented with a marker. +* The Region:: How to access "the region". Text diff --git a/lispref/windows.texi b/lispref/windows.texi index 973b429a04e..a86dd6ec812 100644 --- a/lispref/windows.texi +++ b/lispref/windows.texi @@ -1474,7 +1474,7 @@ window is the one at the bottom right corner. In this case, @code{scroll-other-window} attempts to scroll the minibuffer. If the minibuffer contains just one line, it has nowhere to scroll to, so the line reappears after the echo area momentarily displays the message -``Beginning of buffer''. +@samp{Beginning of buffer}. @end deffn @c Emacs 19 feature @@ -1676,8 +1676,8 @@ times 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 + 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 |