diff options
Diffstat (limited to 'lispref')
54 files changed, 986 insertions, 767 deletions
diff --git a/lispref/ChangeLog b/lispref/ChangeLog index 98d38b57ce0..2a094262bb1 100644 --- a/lispref/ChangeLog +++ b/lispref/ChangeLog @@ -1,3 +1,106 @@ +2005-08-25 Richard M. Stallman <rms@gnu.org> + + * searching.texi (Search and Replace): Add replace-regexp-in-string. + +2005-08-25 Emilio C. Lopes <eclig@gmx.net> + + * display.texi (Finding Overlays): Fix `find-overlay-prop' in + `next-overlay-change' example. + +2005-08-22 Juri Linkov <juri@jurta.org> + + * display.texi (Attribute Functions): Add set-face-inverse-video-p. + Fix invert-face. Fix args of face-background. + + * display.texi (Standard Faces): Delete node. + (Faces): Add xref to `(emacs)Standard Faces'. + (Displaying Faces): Fix xref to `Standard Faces'. + + * modes.texi (Mode Line Data): Fix xref to Standard Faces. + +2005-08-20 Alan Mackenzie <acm@muc.de> + + * buffers.texi (The Buffer List): Clarify the manipulation of the + buffer list. + +2005-08-14 Richard M. Stallman <rms@gnu.org> + + * modes.texi (Auto Major Mode): interpreter-mode-alist key is not + a regexp. + +2005-08-11 Richard M. Stallman <rms@gnu.org> + + * elisp.texi (Top): Update subnode lists. + + * display.texi (Inverse Video): Node deleted. + + * tips.texi (Key Binding Conventions, Programming Tips, Warning Tips): + New nodes split out of Coding Conventions. + + * searching.texi (Regular Expressions): Document re-builder. + + * os.texi (Time Parsing): New node split out of Time Conversion. + + * processes.texi (Misc Network, Network Feature Testing) + (Network Options, Make Network): New nodes split out of + Low-Level Network. + +2005-08-09 Richard M. Stallman <rms@gnu.org> + + * frames.texi (Geometry): New node, split from Size and Position. + (Frame Parameters): Refer to Geometry. + + * buffers.texi (The Buffer List): Fix xrefs. + + * windows.texi (Splitting Windows): Fix xref. + + * frames.texi (Layout Parameters): Add xref. + + * display.texi (Line Height, Scroll Bars): Fix xrefs. + + * keymaps.texi (Menu Bar): Fix xref. + + * locals.texi (Standard Buffer-Local Variables): Fix xref. + + * modes.texi (%-Constructs): Fix xref. + + * frames.texi (Window Frame Parameters): Node split up. + (Basic Parameters, Position Parameters, Size Parameters) + (Layout Parameters, Buffer Parameters, Management Parameters) + (Cursor Parameters, Color Parameters): New subnodes. + +2005-08-09 Luc Teirlinck <teirllm@auburn.edu> + + * positions.texi (Screen Lines): Update xref for previous change + in minibuf.texi. + + * minibuf.texi (Intro to Minibuffers): Update pxref for previous + change in minibuf.texi. + +2005-08-09 Richard M. Stallman <rms@gnu.org> + + * tips.texi (Coding Conventions): Minor cleanup. + + * modes.texi (Defining Minor Modes): Explain when init-value + can be non-nil. + + * elisp.texi (Top): Update submenu for Minibuffer. + + * minibuf.texi (Minibuffer Misc): Node split up. + (Minibuffer Commands, Minibuffer Windows, Minibuffer Contents) + (Recursive Mini): New nodes split out from Minibuffer Misc. + (Minibuffer Misc): Document max-mini-window-height. + + * hash.texi (Defining Hash): Delete stray paren in example. + + * display.texi (Echo Area Customization): Don't define + max-mini-window-height here; xref instead. + + * commands.texi (Event Input Misc): Update while-no-input. + + * advice.texi (Advising Functions): Explain when to use advice + and when to use a hook. + 2005-07-30 Eli Zaretskii <eliz@gnu.org> * makefile.w32-in (info): Don't run install-info. @@ -3685,7 +3788,8 @@ Tue Apr 11 12:23:28 1989 Robert J. Chassell (bob@rice-chex.ai.mit.edu) ;; coding: iso-2022-7bit ;; End: - Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc. + Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, + 2005 Free Software Foundation, Inc. Copying and distribution of this file, with or without modification, are permitted provided the copyright notice and this notice are preserved. diff --git a/lispref/Makefile.in b/lispref/Makefile.in index 4fac4c025b0..7d5ce02714d 100644 --- a/lispref/Makefile.in +++ b/lispref/Makefile.in @@ -1,7 +1,7 @@ # Makefile for the GNU Emacs Lisp Reference Manual. -# Copyright (C) 1990,1991,1992,1993,1994,1995,1996,1998,1999,2000,2001,2003,2004 -# Free Software Foundation, Inc. +# Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, +# 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc. # This file is part of GNU Emacs. diff --git a/lispref/abbrevs.texi b/lispref/abbrevs.texi index a58064ab387..38c5854adc6 100644 --- a/lispref/abbrevs.texi +++ b/lispref/abbrevs.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1999, 2004 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1999, 2002, 2003, 2004, +@c 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/abbrevs @node Abbrevs, Processes, Syntax Tables, Top diff --git a/lispref/advice.texi b/lispref/advice.texi index 2006474fc61..8299e13ac10 100644 --- a/lispref/advice.texi +++ b/lispref/advice.texi @@ -1,6 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1998, 1999 Free Software Foundation, Inc. +@c Copyright (C) 1998, 1999, 2002, 2003, 2004, +@c 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/advising @node Advising Functions, Debugging, Byte Compilation, Top @@ -8,7 +9,7 @@ @cindex advising functions The @dfn{advice} feature lets you add to the existing definition of -a function, by @dfn{advising the function}. This is a clean method +a function, by @dfn{advising the function}. This is a cleaner method for a library to customize functions defined within Emacs---cleaner than redefining the whole function. @@ -23,8 +24,20 @@ are not the same thing. @strong{Usage Note:} Advice is useful for altering the behavior of existing calls to an existing function. If you want the new behavior -for new calls, or for key bindings, it is cleaner to define a new -function (or a new command) which uses the existing function. +for new calls, or for key bindings, you should define a new function +(or a new command) which uses the existing function. + + @strong{Usage note:} Advising a function can cause confusion in +debugging, since people who debug calls to the original function may +not notice that it has been modified with advice. Therefore, if you +have the possibility to change the code of that function (or ask +someone to do so) to run a hook, please solve the problem that way. +Advice should be reserved for the cases where you cannot get the +function changed. + + In particular, this means that a file in Emacs should not put advice +on a function in Emacs. There are currently a few exceptions to this +convention, but we aim to correct them. @menu * Simple Advice:: A simple example to explain the basics of advice. diff --git a/lispref/anti.texi b/lispref/anti.texi index 2c3d6414c1c..d6ae30f2106 100644 --- a/lispref/anti.texi +++ b/lispref/anti.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1999, 2005 Free Software Foundation, Inc. +@c Copyright (C) 1999, 2002, 2003, 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @c This node must have no pointers. diff --git a/lispref/backups.texi b/lispref/backups.texi index 24c617510bf..3b5363f64a3 100644 --- a/lispref/backups.texi +++ b/lispref/backups.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1999, 2004 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1999, 2002, 2003, 2004, +@c 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/backups @node Backups and Auto-Saving, Buffers, Files, Top diff --git a/lispref/buffers.texi b/lispref/buffers.texi index a0769be23dd..6204dfce339 100644 --- a/lispref/buffers.texi +++ b/lispref/buffers.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2004 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, +@c 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/buffers @node Buffers, Windows, Backups and Auto-Saving, Top @@ -757,21 +757,24 @@ signal an error if the current buffer is read-only. @section The Buffer List @cindex buffer list - The @dfn{buffer list} is a list of all live buffers. Creating a -buffer adds it to this list, and killing a buffer removes it. The -order of the buffers in the list is based primarily on how recently -each buffer has been displayed in the selected window. Buffers move -to the front of the list when they are selected (selecting a window -that already displays the buffer counts as selecting the buffer), and -to the end when they are buried (see @code{bury-buffer}, below). -Several functions, notably @code{other-buffer}, use this ordering. A -buffer list displayed for the user also follows this order. + The @dfn{buffer list} is a list of all live buffers. The order of +the buffers in the list is based primarily on how recently each buffer +has been displayed in a window. Several functions, notably +@code{other-buffer}, use this ordering. A buffer list displayed for +the user also follows this order. + Creating a buffer adds it to the end of the buffer list, and killing +a buffer removes it. Buffers move to the front of the list when they +are selected for display in a window (@pxref{Displaying Buffers}), and +to the end when they are buried (see @code{bury-buffer}, below). +There are no functions available to the Lisp programmer which directly +manipulate the buffer list. + In addition to the fundamental Emacs buffer list, each frame has its own version of the buffer list, in which the buffers that have been selected in that frame come first, starting with the buffers most recently selected @emph{in that frame}. (This order is recorded in -@var{frame}'s @code{buffer-list} frame parameter; see @ref{Window Frame +@var{frame}'s @code{buffer-list} frame parameter; see @ref{Buffer Parameters}.) The buffers that were never selected in @var{frame} come afterward, ordered according to the fundamental Emacs buffer list. @@ -838,7 +841,7 @@ buffer list that is not now visible in any window in a visible frame. If @var{frame} has a non-@code{nil} @code{buffer-predicate} parameter, then @code{other-buffer} uses that predicate to decide which buffers to consider. It calls the predicate once for each buffer, and if the value -is @code{nil}, that buffer is ignored. @xref{Window Frame Parameters}. +is @code{nil}, that buffer is ignored. @xref{Buffer Parameters}. @c Emacs 19 feature If @var{visible-ok} is @code{nil}, @code{other-buffer} avoids returning diff --git a/lispref/commands.texi b/lispref/commands.texi index 5ded722155c..353a7436c28 100644 --- a/lispref/commands.texi +++ b/lispref/commands.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2004 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, +@c 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/commands @node Command Loop, Keymaps, Minibuffers, Top @@ -2435,15 +2435,26 @@ Emacs version 18. @end defvar @defmac while-no-input body... -This construct runs the @var{body} forms and returns the value -of the last one---but only if no input arrives. If any input -arrives during the execution of the @var{body} forms, it aborts -them (working much like a quit), and the @code{while-no-input} -form returns @code{nil}. +This construct runs the @var{body} forms and returns the value of the +last one---but only if no input arrives. If any input arrives during +the execution of the @var{body} forms, it aborts them (working much +like a quit). The @code{while-no-input} form returns @code{nil} if +aborted by a real quit, and returns @code{t} if aborted by arrival of +other input. If a part of @var{body} binds @code{inhibit-quit} to non-@code{nil}, arrival of input during those parts won't cause an abort until the end of that part. + +If you want to be able to distingish all possible values computed +by @var{body} from both kinds of abort conditions, write the code +like this: + +@example +(while-no-input + (list + (progn . @var{body}))) +@end example @end defmac @defun discard-input diff --git a/lispref/compile.texi b/lispref/compile.texi index 951a090e0da..79ac366c27d 100644 --- a/lispref/compile.texi +++ b/lispref/compile.texi @@ -1,6 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 2002, 2003, 2004, +@c 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/compile @node Byte Compilation, Advising Functions, Loading, Top diff --git a/lispref/control.texi b/lispref/control.texi index 573a32b1cde..8dae3d46484 100644 --- a/lispref/control.texi +++ b/lispref/control.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, +@c 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/control @node Control Structures, Variables, Evaluation, Top diff --git a/lispref/customize.texi b/lispref/customize.texi index 8ee82f088a8..b573ab942a6 100644 --- a/lispref/customize.texi +++ b/lispref/customize.texi @@ -1,6 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1997, 1998, 1999, 2000, 2002, 2003, 2005 Free Software Foundation, Inc. +@c Copyright (C) 1997, 1998, 1999, 2000, 2002, 2003, 2004, +@c 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/customize @node Customization, Loading, Macros, Top diff --git a/lispref/debugging.texi b/lispref/debugging.texi index 66663aad131..9c0fa9bc865 100644 --- a/lispref/debugging.texi +++ b/lispref/debugging.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2005 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2002, 2003, 2004, +@c 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/debugging @node Debugging, Read and Print, Advising Functions, Top diff --git a/lispref/display.texi b/lispref/display.texi index de024a71b32..8addb3b67ec 100644 --- a/lispref/display.texi +++ b/lispref/display.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001, -@c 2002, 2005 Free Software Foundation, Inc. +@c 2002, 2003, 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/display @node Display, System Interface, Processes, Top @@ -31,7 +31,6 @@ that Emacs presents to the user. * Images:: Displaying images in Emacs buffers. * Buttons:: Adding clickable buttons to 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. * Display Tables:: How to specify other conventions. * Beeping:: Audible signal to the user. @@ -495,12 +494,6 @@ sequence are echoed immediately.) If the value is zero, then command input is not echoed. @end defvar -@defopt max-mini-window-height -This variable specifies the maximum height for resizing minibuffer -windows. If a float, it specifies a fraction of the height of the -frame. If an integer, it specifies a number of lines. -@end defopt - @defvar message-truncate-lines Normally, displaying a long message resizes the echo area to display the entire message. But if the variable @code{message-truncate-lines} @@ -508,6 +501,11 @@ is non-@code{nil}, the echo area does not resize, and the message is truncated to fit it, as in Emacs 20 and before. @end defvar + The variable @code{max-mini-window-height}, which specifies the +maximum height for resizing minibuffer windows, also applies to the +echo area (which is really a special use of the minibuffer window. +@xref{Minibuffer Misc}. + @node Warnings @section Reporting Warnings @cindex warnings @@ -1503,20 +1501,26 @@ end of an overlay, before @var{pos}. If there is none, it returns @code{(point-min)}. @end defun - Here's an easy way to use @code{next-overlay-change} to search for the -next character which gets a non-@code{nil} @code{happy} property from + Here's a function which uses @code{next-overlay-change} to search +for the next character which gets a given property @code{prop} from either its overlays or its text properties (@pxref{Property Search}): @smallexample (defun find-overlay-prop (prop) (save-excursion (while (and (not (eobp)) - (not (get-char-property (point) 'happy))) + (not (get-char-property (point) prop))) (goto-char (min (next-overlay-change (point)) - (next-single-property-change (point) 'happy)))) + (next-single-property-change (point) prop)))) (point))) @end smallexample + Now you can search for a @code{happy} property like this: + +@smallexample +(find-overlay-prop 'happy) +@end smallexample + @node Width @section Width @@ -1642,7 +1646,7 @@ parts of Emacs text. @vindex default-line-spacing You can specify the line spacing for all lines in a frame with the -@code{line-spacing} frame parameter, @xref{Window Frame Parameters}. +@code{line-spacing} frame parameter (@pxref{Layout Parameters}). However, if the variable @code{default-line-spacing} is non-@code{nil}, it overrides the frame's @code{line-spacing} parameter. An integer value specifies the number of pixels put below @@ -1675,7 +1679,9 @@ height. 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. +particular parts of the text or the frame. @xref{Standard Faces,,, +emacs, The GNU Emacs Manual}, for the list of faces Emacs normally +comes with. @cindex face id Each face has its own @dfn{face number}, which distinguishes faces at @@ -1693,7 +1699,6 @@ same meaning in all frames. But you can arrange to give a particular face name a special meaning in one frame if you wish. @menu -* Standard Faces:: The faces Emacs normally comes with. * Defining Faces:: How to define a face with @code{defface}. * Face Attributes:: What is in a face? * Attribute Functions:: Functions to examine and set face attributes. @@ -1707,139 +1712,6 @@ face name a special meaning in one frame if you wish. 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. 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 the mode line of the selected window, and for -menu bars when toolkit menus are not used. - -@item modeline -@kindex modeline @r{(face name)} -This is an alias for the @code{mode-line} face, for compatibility with -old Emacs versions. - -@item mode-line-inactive -@kindex mode-line-inactive @r{(face name)} -This face is used for mode lines of non-selected windows. -This face inherits from @code{mode-line}, so changes -in that face affect all windows. - -@item header-line -@kindex header-line @r{(face name)} -This face is used for the header lines of windows that have them. - -@item menu -This face controls the display of menus, both their colors and their -font. (This works only on certain systems.) - -@item fringe -@kindex fringe @r{(face name)} -This face controls the default colors of window fringes, the thin -areas on either side that are used to display continuation and -truncation glyphs. Other faces used to display bitmaps in the fringe -are implicitly merged with this face. - -@item minibuffer-prompt -@kindex minibuffer-prompt @r{(face name)} -@vindex minibuffer-prompt-properties -This face is used for the text of minibuffer prompts. By default, -Emacs automatically adds this face to the value of -@code{minibuffer-prompt-properties}, which is a list of text -properties used to display the prompt text. - -@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)} -This face is used for highlighting the region in Transient Mark mode. - -@item secondary-selection -@kindex secondary-selection @r{(face name)} -This face is used to show any secondary selection you have made. - -@item highlight -@kindex highlight @r{(face name)} -This face is meant to be used for highlighting for various purposes. - -@item mode-line-highlight -@kindex mode-line-highlight @r{(face name)} -This face is used for highlighting something on @code{mode-line} or -@code{header-line} for various purposes. - -@item trailing-whitespace -@kindex trailing-whitespace @r{(face name)} -This face is used to display excess whitespace at the end of a line, -if @code{show-trailing-whitespace} is non-@code{nil}. - -@item escape-glyph -@kindex escape-glyph @r{(face name)} -This face is used to display control characters and escape glyphs. -@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 -the frame's font, if it has one. It's up to you to choose a default -font that has a bold variant, if you want to use one. - -@item italic -@kindex italic @r{(face name)} -This face uses the italic variant of the frame's font, if it has one. - -@item bold-italic -@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-pitch -@kindex fixed-pitch @r{(face name)} -This face forces use of a particular fixed-width font. - -@item variable-pitch -@kindex variable-pitch @r{(face name)} -This face forces use of a particular variable-width font. It's -reasonable to customize this to use a different variable-width font, if -you like, but you should not make it a fixed-width font. - -@item shadow -@kindex shadow @r{(face name)} -This face is used for making the text less noticeable than the -surrounding ordinary text. -@end table - -@defvar show-trailing-whitespace -@tindex show-trailing-whitespace -If this variable is non-@code{nil}, Emacs uses the -@code{trailing-whitespace} face to display any spaces and tabs at the -end of a line. -@end defvar - @node Defining Faces @subsection Defining Faces @@ -2290,10 +2162,14 @@ This function sets the underline attribute of face @var{face}. Non-@code{nil} means do underline; @code{nil} means don't. @end defun +@defun set-face-inverse-video-p face inverse-video-p &optional frame +This function sets the @code{:inverse-video} attribute of face +@var{face}. +@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. +This function swaps the foreground and background colors of face +@var{face}. @end defun These functions examine the attributes of a face. If you don't @@ -2302,7 +2178,7 @@ They return the symbol @code{unspecified} if the face doesn't define any value for that attribute. @defun face-foreground face &optional frame inherit -@defunx face-background face &optional frame +@defunx face-background face &optional frame inherit These functions return the foreground color (or background color, respectively) of face @var{face}, as a string. @@ -2380,7 +2256,8 @@ 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 the face @code{region} (@pxref{Standard Faces}). +highlighted with the face @code{region} (@pxref{Standard Faces,,, +emacs, The GNU Emacs Manual}). @item With special glyphs. Each glyph can specify a particular face @@ -3078,7 +2955,7 @@ Normally the frame parameter @code{vertical-scroll-bars} controls whether the windows in the frame have vertical scroll bars, and whether they are on the left or right. The frame parameter @code{scroll-bar-width} specifies how wide they are (@code{nil} -meaning the default). @xref{Window Frame Parameters}. +meaning the default). @xref{Layout Parameters}. @defun frame-current-scroll-bars &optional frame This function reports the scroll bar type settings for frame @@ -4592,17 +4469,6 @@ Here is an example of calling this function explicitly. @end smallexample @end deffn -@node Inverse Video -@section Inverse Video -@cindex Inverse Video - -@defopt inverse-video -@cindex highlighting -This variable controls whether Emacs uses inverse video for all text -on the screen. Non-@code{nil} means yes, @code{nil} means no. The -default is @code{nil}. -@end defopt - @node Usual Display @section Usual Display Conventions diff --git a/lispref/edebug.texi b/lispref/edebug.texi index f074cf3dbd5..a32c5e9189c 100644 --- a/lispref/edebug.texi +++ b/lispref/edebug.texi @@ -1,6 +1,7 @@ @comment -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1992, 1993, 1994, 1998, 1999, 2005 Free Software Foundation, Inc. +@c Copyright (C) 1992, 1993, 1994, 1998, 1999, 2002, 2003, 2004, +@c 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @c This file can also be used by an independent Edebug User diff --git a/lispref/elisp.texi b/lispref/elisp.texi index 64b4ee90292..8c99ee6acaa 100644 --- a/lispref/elisp.texi +++ b/lispref/elisp.texi @@ -31,7 +31,7 @@ This is edition @value{VERSION} of the GNU Emacs Lisp Reference Manual, corresponding to Emacs version @value{EMACSVER}. Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, - 2000, 2002, 2003, 2004, 2005, Free Software Foundation, Inc. + 2000, 2002, 2003, 2004, 2005 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -543,6 +543,10 @@ Minibuffers * Yes-or-No Queries:: Asking a question with a simple answer. * Multiple Queries:: Asking a series of similar questions. * Reading a Password:: Reading a password from the terminal. +* Minibuffer Commands:: Commands used as key bindings in minibuffers. +* Minibuffer Contents:: How such commands access the minibuffer text. +* Minibuffer Windows:: Operating on the special minibuffer windows. +* Recursive Mini:: Whether recursive entry to minibuffer is allowed. * Minibuffer Misc:: Various customization hooks and variables. Completion @@ -970,7 +974,8 @@ Processes * Datagrams:: UDP network connections. * Low-Level Network:: Lower-level but more general function to create connections and servers. -* Byte Packing:: Using bindat to pack and unpack binary data. +* Misc Network:: Additional relevant functions for network connections. +* Byte Packing:: Using bindat to pack and unpack binary data. Receiving Output from Processes @@ -1001,7 +1006,6 @@ Emacs Display * Images:: Displaying images in Emacs buffers. * Buttons:: Adding clickable buttons to 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. * Display Tables:: How to specify other conventions. * Beeping:: Audible signal to the user. @@ -1016,6 +1020,8 @@ Operating System Interface * Time of Day:: Getting the current time. * Time Conversion:: Converting a time from numeric form to a string, or to calendrical data (or vice versa). +* Time Parsing:: Converting a time from numeric form to text + and vice versa. * Processor Run Time:: Getting the run time used by Emacs. * Time Calculations:: Adding, subtracting, comparing times, etc. * Timers:: Setting a timer to call a function at a certain time. @@ -1042,7 +1048,10 @@ Getting out of Emacs Tips and Conventions * Coding Conventions:: Conventions for clean and robust programs. -* Compilation Tips:: Making compiled code run fast. +* Key Binding Conventions:: Which keys should be bound by which programs. +* Programming Tips:: Making Emacs code fit smoothly in Emacs. +* Compilation Tips:: Making compiled code run fast. +* Warning Tips:: Turning off compiler warnings. * Documentation Tips:: Writing readable documentation strings. * Comment Tips:: Conventions for writing comments. * Library Headers:: Standard headers for library packages. diff --git a/lispref/errors.texi b/lispref/errors.texi index a246539b8fd..ce48c3cf549 100644 --- a/lispref/errors.texi +++ b/lispref/errors.texi @@ -1,6 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1999 Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1999, 2002, 2003, 2004, +@c 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/errors @node Standard Errors, Standard Buffer-Local Variables, GNU Emacs Internals, Top diff --git a/lispref/eval.texi b/lispref/eval.texi index 6a43466af67..36bc941f26b 100644 --- a/lispref/eval.texi +++ b/lispref/eval.texi @@ -1,6 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 2003, 2004 Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 2002, 2003, 2004, +@c 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/eval @node Evaluation, Control Structures, Symbols, Top diff --git a/lispref/files.texi b/lispref/files.texi index 93c104e6ccd..d8d47964cdf 100644 --- a/lispref/files.texi +++ b/lispref/files.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2004 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, +@c 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/files @node Files, Backups and Auto-Saving, Documentation, Top diff --git a/lispref/frames.texi b/lispref/frames.texi index 827f98d24c2..3cb5e49dbac 100644 --- a/lispref/frames.texi +++ b/lispref/frames.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2004 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, +@c 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/frames @node Frames, Positions, Windows, Top @@ -205,6 +205,7 @@ parameters @code{foreground-color}, @code{background-color}, * Initial Parameters:: Specifying frame parameters when you make a frame. * Window Frame Parameters:: List of frame parameters for window systems. * Size and Position:: Changing the size and position of a frame. +* Geometry:: Parsing geometry specifications. @end menu @node Parameter Access @@ -310,14 +311,31 @@ Line Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}. @node Window Frame Parameters @subsection Window Frame Parameters - Just what parameters a frame has depends on what display mechanism it -uses. Here is a table of the parameters that have special meanings in a -window frame; of these, @code{name}, @code{title}, @code{height}, -@code{width}, @code{buffer-list} and @code{buffer-predicate} provide -meaningful information in terminal frames, and @code{tty-color-mode} -is meaningful @emph{only} in terminal frames. Frame parameter whose -values measured in pixels, when used on text-only terminals, count -characters or lines instead. + Just what parameters a frame has depends on what display mechanism +it uses. This section describes the parameters that have special +meanings on some or all kinds of terminals. Of these, @code{name}, +@code{title}, @code{height}, @code{width}, @code{buffer-list} and +@code{buffer-predicate} provide meaningful information in terminal +frames, and @code{tty-color-mode} is meaningful @emph{only} in +terminal frames. + +@menu +* Basic Parameters:: Parameters that are fundamental. +* Position Parameters:: The position of the frame on the screen. +* Size Parameters:: Frame's size. +* Layout Parameters:: Size of parts of the frame, and + enabling or disabling some parts. +* Buffer Parameters:: Which buffers have been or should be shown. +* Management Parameters:: Communicating with the window manager. +* Cursor Parameters:: Controlling the cursor appearance. +* Color Parameters:: Colors of various parts of the frame. +@end menu + +@node Basic Parameters +@subsubsection Basic Parameters + + These frame parameters give the most basic information about the +frame. @code{title} and @code{name} are meaningful on all terminals. @table @code @item display @@ -325,6 +343,11 @@ The display on which to open this frame. It should be a string of the form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the @code{DISPLAY} environment variable. +@item display-type +This parameter describes the range of possible colors that can be used +in this frame. Its value is @code{color}, @code{grayscale} or +@code{mono}. + @item title If a frame has a non-@code{nil} title, it appears in the window system's border for the frame, and also in the mode line of windows in that frame @@ -342,7 +365,15 @@ you don't specify a name, Emacs sets the frame name automatically If you specify the frame name explicitly when you create the frame, the name is also used (instead of the name of the Emacs executable) when looking up X resources for the frame. +@end table +@node Position Parameters +@subsubsection Position Parameters + + Position parameters' values are normally measured in pixels, but on +text-only terminals they count characters or lines instead. + +@table @code @item left The screen position of the left edge, in pixels, with respect to the left edge of the screen. The value may be a positive number @var{pos}, @@ -397,7 +428,15 @@ When you call @code{make-frame}, you should specify a non-@code{nil} value for this parameter if the values of the @code{left} and @code{top} parameters represent the user's stated preference; otherwise, use @code{nil}. +@end table + +@node Size Parameters +@subsubsection Size Parameters + Size parameters' values are normally measured in pixels, but on +text-only terminals they count characters or lines instead. + +@table @code @item height The height of the frame contents, in characters. (To get the height in pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.) @@ -417,14 +456,76 @@ The value @code{fullwidth} specifies that width shall be the size of the screen. The value @code{fullheight} specifies that height shall be the size of the screen. The value @code{fullboth} specifies that both the width and the height shall be set to the size of the screen. +@end table -@item window-id -The number of the window-system window used by the frame -to contain the actual Emacs windows. +@node Layout Parameters +@subsubsection Layout Parameters -@item outer-window-id -The number of the outermost window-system window used for the whole frame. + These frame parameters enable or disable various parts of the +frame, or control their sizes. +@table @code +@item border-width +The width in pixels of the window border. + +@item internal-border-width +The distance in pixels between text and border. + +@item vertical-scroll-bars +Whether the frame has scroll bars for vertical scrolling, and which side +of the frame they should be on. The possible values are @code{left}, +@code{right}, and @code{nil} for no scroll bars. + +@ignore +@item horizontal-scroll-bars +Whether the frame has scroll bars for horizontal scrolling +(non-@code{nil} means yes). Horizontal scroll bars are not currently +implemented. +@end ignore + +@item scroll-bar-width +The width of vertical scroll bars, in pixels, or @code{nil} meaning to +use the default width. + +@item left-fringe +@itemx right-fringe +The default width of the left and right fringes of windows in this +frame (@pxref{Fringes}). If either of these is zero, that effectively +removes the corresponding fringe. A value of @code{nil} stands for +the standard fringe width, which is the width needed to display the +fringe bitmaps. + +The combined fringe widths must add up to an integral number of +columns, so the actual default fringe widths for the frame may be +larger than the specified values. The extra width needed to reach an +acceptable total is distributed evenly between the left and right +fringe. However, you can force one fringe or the other to a precise +width by specifying that width as a negative integer. If both widths are +negative, only the left fringe gets the specified width. + +@item menu-bar-lines +The number of lines to allocate at the top of the frame for a menu +bar. The default is 1. A value of @code{nil} means don't display a +menu bar. @xref{Menu Bar}. (The X toolkit and GTK allow at most one +menu bar line; they treat larger values as 1.) + +@item tool-bar-lines +The number of lines to use for the tool bar. A value of @code{nil} +means don't display a tool bar. (GTK allows at most one tool bar line; +it treats larger values as 1.) + +@item line-spacing +Additional space to leave below each text line, in pixels (a positive +integer). @xref{Line Height}, for more information. +@end table + +@node Buffer Parameters +@subsubsection Buffer Parameters + + These frame parameters, meaningful on all kinds of terminals, deal +with which buffers have been, or should, be displayed in the frame. + +@table @code @item minibuffer Whether this frame has its own minibuffer. The value @code{t} means yes, @code{nil} means no, @code{only} means this frame is just a @@ -443,26 +544,28 @@ considers that buffer. A list of buffers that have been selected in this frame, ordered most-recently-selected first. +@item unsplittable +If non-@code{nil}, this frame's window is never split automatically. +@end table + +@node Management Parameters +@subsubsection Window Management Parameters + + These frame parameters, meaningful only on window system displays, +interact with the window manager. + +@table @code +@item visibility +The state of visibility of the frame. There are three possibilities: +@code{nil} for invisible, @code{t} for visible, and @code{icon} for +iconified. @xref{Visibility of Frames}. + @item auto-raise Whether selecting the frame raises it (non-@code{nil} means yes). @item auto-lower Whether deselecting the frame lowers it (non-@code{nil} means yes). -@item vertical-scroll-bars -Whether the frame has scroll bars for vertical scrolling, and which side -of the frame they should be on. The possible values are @code{left}, -@code{right}, and @code{nil} for no scroll bars. - -@item horizontal-scroll-bars -Whether the frame has scroll bars for horizontal scrolling -(non-@code{nil} means yes). (Horizontal scroll bars are not currently -implemented.) - -@item scroll-bar-width -The width of the vertical scroll bar, in pixels, -or @code{nil} meaning to use the default width. - @item icon-type The type of icon to use for this frame when it is iconified. If the value is a string, that specifies a file containing a bitmap to use. @@ -473,29 +576,35 @@ picture of a gnu); @code{nil} specifies a text icon. The name to use in the icon for this frame, when and if the icon appears. If this is @code{nil}, the frame's title is used. -@item 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 window-id +The number of the window-system window used by the frame +to contain the actual Emacs windows. -@item tty-color-mode -@cindex standard colors for character terminals -This parameter overrides the terminal's color support as given by the -system's terminal capabilities database in that this parameter's value -specifies the color mode to use in terminal frames. The value can be -either a symbol or a number. A number specifies the number of colors -to use (and, indirectly, what commands to issue to produce each -color). For example, @code{(tty-color-mode . 8)} forces Emacs to use -the ANSI escape sequences for 8 standard text colors; and a value of --1 means Emacs should turn off color support. If the parameter's -value is a symbol, that symbol is looked up in the alist -@code{tty-color-mode-alist}, and if found, the associated number is -used as the color support mode. +@item outer-window-id +The number of the outermost window-system window used for the whole frame. -@item display-type -This parameter describes the range of possible colors that can be used -in this frame. Its value is @code{color}, @code{grayscale} or -@code{mono}. +@item wait-for-wm +If non-@code{nil}, tell Xt to wait for the window manager to confirm +geometry changes. Some window managers, including versions of Fvwm2 +and KDE, fail to confirm, so Xt hangs. Set this to @code{nil} to +prevent hanging with those window managers. + +@ignore +@item parent-id +@c ??? Not yet working. +The X window number of the window that should be the parent of this one. +Specifying this lets you create an Emacs window inside some other +application's window. (It is not certain this will be implemented; try +it and see if it works.) +@end ignore +@end table +@node Cursor Parameters +@subsubsection Cursor Parameters + + This frame parameter controls the way the cursor looks. + +@table @code @item cursor-type How to display the cursor. Legitimate values are: @@ -515,52 +624,51 @@ Display a horizontal bar. @item (hbar . @var{height}) Display a horizontal bar @var{height} pixels high. @end table +@end table @vindex cursor-type The buffer-local variable @code{cursor-type} overrides the value of the @code{cursor-type} frame parameter, but if it is @code{t}, that means to use the cursor specified for the frame. -@item border-width -The width in pixels of the window border. - -@item internal-border-width -The distance in pixels between text and border. - -@item left-fringe -@itemx right-fringe -The default width of the left and right fringes of windows in this -frame (@pxref{Fringes}). If either of these is zero, that effectively -removes the corresponding fringe. A value of @code{nil} stands for -the standard fringe width, which is the width needed to display the -fringe bitmaps. +@defvar blink-cursor-alist +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} +should be suitable values for the @code{cursor-type} frame parameter. + +There are various defaults for how to blink each type of cursor, if +the type is not mentioned as an @var{on-state} here. Changes in this +variable do not take effect immediately, because the variable is +examined only when you specify the @code{cursor-type} parameter. +@end defvar -The combined fringe widths must add up to an integral number of -columns, so the actual default fringe widths for the frame may be -larger than the specified values. The extra width needed to reach an -acceptable total is distributed evenly between the left and right -fringe. However, you can force one fringe or the other to a precise -width by specifying that width as a negative integer. If both widths are -negative, only the left fringe gets the specified width. +@node Color Parameters +@subsubsection Color Parameters -@item unsplittable -If non-@code{nil}, this frame's window is never split automatically. + These frame parameters control the use of colors. -@item visibility -The state of visibility of the frame. There are three possibilities: -@code{nil} for invisible, @code{t} for visible, and @code{icon} for -iconified. @xref{Visibility of Frames}. +@table @code +@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 menu-bar-lines -The number of lines to allocate at the top of the frame for a menu -bar. The default is 1. A value of @code{nil} means don't display a -menu bar. @xref{Menu Bar}. (The X toolkit and GTK allow at most one -menu bar line; they treat larger values as 1.) +@item tty-color-mode +@cindex standard colors for character terminals +This parameter overrides the terminal's color support as given by the +system's terminal capabilities database in that this parameter's value +specifies the color mode to use in terminal frames. The value can be +either a symbol or a number. A number specifies the number of colors +to use (and, indirectly, what commands to issue to produce each +color). For example, @code{(tty-color-mode . 8)} specifies use of the +ANSI escape sequences for 8 standard text colors. A value of -1 turns +off color support. -@item tool-bar-lines -The number of lines to use for the tool bar. A value of @code{nil} -means don't display a tool bar. (GTK allows at most one tool bar line; -it treats larger values as 1.) +If the parameter's value is a symbol, it specifies a number through +the value of @code{tty-color-mode-alist}, and the associated number is +used instead. @item screen-gamma @cindex gamma correction @@ -580,40 +688,8 @@ If your monitor displays colors too light, you should specify a @code{screen-gamma} value smaller than 2.2. This requests correction that makes colors darker. A screen gamma value of 1.5 may give good results for LCD color displays. - -@item line-spacing -Additional space put below text lines, in pixels (a positive integer) - -@item wait-for-wm -If non-@code{nil}, tell Xt to wait for the window manager to confirm -geometry changes. Some window managers, including versions of Fvwm2 -and KDE, fail to confirm, so Xt hangs. Set this to @code{nil} to -prevent hanging with those window managers. - -@ignore -@item parent-id -@c ??? Not yet working. -The X window number of the window that should be the parent of this one. -Specifying this lets you create an Emacs window inside some other -application's window. (It is not certain this will be implemented; try -it and see if it works.) -@end ignore @end table -@defvar blink-cursor-alist -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}), Emacs uses -@var{off-state} to specify what the cursor looks like 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 the type is not mentioned as an @var{on-state} here. Changes -in this variable do not take effect immediately, because the variable -is examined only when you specify a cursor type for a frame. -@end defvar - These frame parameters are semi-obsolete in that they are automatically equivalent to particular face attributes of particular faces. @@ -750,6 +826,12 @@ The argument @var{pretend} has the same meaning as in screen, in Emacs versions that did not support multiple frames. They are semi-obsolete, but still work; they apply to the selected frame. +@node Geometry +@subsection Geometry + + Here's how to examine the data in an X-style window geometry +specification: + @defun x-parse-geometry geom @cindex geometry specification The function @code{x-parse-geometry} converts a standard X window @@ -1150,7 +1232,7 @@ they are currently being displayed or not, and this function returns @end defun The visibility status of a frame is also available as a frame -parameter. You can read or change it as such. @xref{Window Frame +parameter. You can read or change it as such. @xref{Management Parameters}. The user can iconify and deiconify frames with the window manager. @@ -1195,7 +1277,7 @@ that the minibuffer window is in. You can also enable auto-raise (raising automatically when a frame is selected) or auto-lower (lowering automatically when it is deselected) -for any frame using frame parameters. @xref{Window Frame Parameters}. +for any frame using frame parameters. @xref{Management Parameters}. @node Frame Configurations @section Frame Configurations @@ -1504,7 +1586,7 @@ is over mouse-sensitive text. These variables affect newly created frames. They do not normally affect existing frames; however, if you set the mouse color of a frame, that also updates its pointer shapes based on the current values of -these variables. @xref{Window Frame Parameters}. +these variables. @xref{Color Parameters}. The values you can use, to specify either of these pointer shapes, are defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos diff --git a/lispref/functions.texi b/lispref/functions.texi index f58cad69bb7..17a96734b10 100644 --- a/lispref/functions.texi +++ b/lispref/functions.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2004 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, +@c 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/functions @node Functions, Macros, Variables, Top diff --git a/lispref/hash.texi b/lispref/hash.texi index b8ddd0ee6a4..7b4c8c67711 100644 --- a/lispref/hash.texi +++ b/lispref/hash.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1999, 2003 Free Software Foundation, Inc. +@c Copyright (C) 1999, 2002, 2003, 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/hash @node Hash Tables, Symbols, Sequences Arrays Vectors, Top @@ -281,8 +281,8 @@ compared case-insensitively. (defun case-fold-string-hash (a) (sxhash (upcase a))) -(define-hash-table-test 'case-fold 'case-fold-string= - 'case-fold-string-hash)) +(define-hash-table-test 'case-fold + 'case-fold-string= 'case-fold-string-hash) (make-hash-table :test 'case-fold) @end example diff --git a/lispref/help.texi b/lispref/help.texi index 2dbea2038cc..c7c99fa8987 100644 --- a/lispref/help.texi +++ b/lispref/help.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2004 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, +@c 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/help @node Documentation, Files, Modes, Top diff --git a/lispref/hooks.texi b/lispref/hooks.texi index 1278589de53..11b2233dc0e 100644 --- a/lispref/hooks.texi +++ b/lispref/hooks.texi @@ -1,6 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1998, 2004, 2005 Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1998, 2002, 2003, 2004, +@c 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/hooks @node Standard Hooks, Index, Standard Keymaps, Top diff --git a/lispref/internals.texi b/lispref/internals.texi index 5cc0fe6e497..e032f5a7ddf 100644 --- a/lispref/internals.texi +++ b/lispref/internals.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1998, 1999, 2005 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1998, 1999, 2002, 2003, 2004, +@c 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/internals @node GNU Emacs Internals, Standard Errors, Tips, Top diff --git a/lispref/intro.texi b/lispref/intro.texi index bb264c81c46..01ffeb3321c 100644 --- a/lispref/intro.texi +++ b/lispref/intro.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 2002 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 2002, 2003, 2004, +@c 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/intro diff --git a/lispref/keymaps.texi b/lispref/keymaps.texi index 895ca48109b..5509b35b799 100644 --- a/lispref/keymaps.texi +++ b/lispref/keymaps.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000, 2004 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000, 2002, 2003, +@c 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/keymaps @node Keymaps, Modes, Command Loop, Top @@ -2199,7 +2199,7 @@ were @code{nil}. @xref{Active Keymaps}. parameter must be greater than zero. Emacs uses just one line for the menu bar itself; if you specify more than one line, the other lines serve to separate the menu bar from the windows in the frame. We -recommend 1 or 2 as the value of @code{menu-bar-lines}. @xref{Window Frame +recommend 1 or 2 as the value of @code{menu-bar-lines}. @xref{Layout Parameters}. Here's an example of setting up a menu bar item: diff --git a/lispref/lists.texi b/lispref/lists.texi index 22edec42db2..422c977184c 100644 --- a/lispref/lists.texi +++ b/lispref/lists.texi @@ -1,8 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, -@c 2003, 2004, 2005 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, +@c 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/lists @node Lists, Sequences Arrays Vectors, Strings and Characters, Top diff --git a/lispref/loading.texi b/lispref/loading.texi index b64a0ce6736..afef0e787a5 100644 --- a/lispref/loading.texi +++ b/lispref/loading.texi @@ -1,8 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, -@c 2003, 2004, 2005 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003, +@c 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/loading @node Loading, Byte Compilation, Customization, Top diff --git a/lispref/locals.texi b/lispref/locals.texi index 942baa9dd1b..57b17d3d41b 100644 --- a/lispref/locals.texi +++ b/lispref/locals.texi @@ -1,6 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1999 Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1999, 2002, 2003, 2004, +@c 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/locals @node Standard Buffer-Local Variables, Standard Keymaps, Standard Errors, Top @@ -82,7 +83,7 @@ use, but we don't try to list them all here. @xref{Usual Display}. @item cursor-type -@xref{Window Frame Parameters}. +@xref{Cursor Parameters}. @item comment-column @xref{Comments,,, emacs, The GNU Emacs Manual}. diff --git a/lispref/macros.texi b/lispref/macros.texi index 0a1bf942c29..dc822352ab3 100644 --- a/lispref/macros.texi +++ b/lispref/macros.texi @@ -1,6 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 2004 Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 2002, 2003, +@c 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/macros @node Macros, Customization, Functions, Top diff --git a/lispref/makefile.w32-in b/lispref/makefile.w32-in index 10b1e168805..038c05db7c3 100644 --- a/lispref/makefile.w32-in +++ b/lispref/makefile.w32-in @@ -1,7 +1,6 @@ # -*- Makefile -*- for the GNU Emacs Lisp Reference Manual. -# Copyright (C) 2003, 2004 -# Free Software Foundation, Inc. +# Copyright (C) 2003, 2004, 2005 Free Software Foundation, Inc. # This file is part of GNU Emacs. diff --git a/lispref/maps.texi b/lispref/maps.texi index 16c1f0bab9b..ef5984cc32f 100644 --- a/lispref/maps.texi +++ b/lispref/maps.texi @@ -1,6 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1999 Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1999, 2002, 2003, 2004, +@c 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/maps @node Standard Keymaps, Standard Hooks, Standard Buffer-Local Variables, Top diff --git a/lispref/markers.texi b/lispref/markers.texi index 60b2aae6a98..d9f6d19a4b0 100644 --- a/lispref/markers.texi +++ b/lispref/markers.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, +@c 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/markers @node Markers, Text, Positions, Top diff --git a/lispref/minibuf.texi b/lispref/minibuf.texi index a6153fdaca2..04443c493f3 100644 --- a/lispref/minibuf.texi +++ b/lispref/minibuf.texi @@ -1,8 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, -@c 2001, 2004 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002, +@c 2003, 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/minibuf @node Minibuffers, Command Loop, Read and Print, Top @@ -11,12 +10,13 @@ @cindex complex arguments @cindex minibuffer - A @dfn{minibuffer} is a special buffer that Emacs commands use to read -arguments more complicated than the single numeric prefix argument. -These arguments include file names, buffer names, and command names (as -in @kbd{M-x}). The minibuffer is displayed on the bottom line of the -frame, in the same place as the echo area, but only while it is in use -for reading an argument. + A @dfn{minibuffer} is a special buffer that Emacs commands use to +read arguments more complicated than the single numeric prefix +argument. These arguments include file names, buffer names, and +command names (as in @kbd{M-x}). The minibuffer is displayed on the +bottom line of the frame, in the same place as the echo area +(@pxref{The Echo Area}), but only while it is in use for reading an +argument. @menu * Intro to Minibuffers:: Basic information about minibuffers. @@ -29,6 +29,10 @@ for reading an argument. * Yes-or-No Queries:: Asking a question with a simple answer. * Multiple Queries:: Asking a series of similar questions. * Reading a Password:: Reading a password from the terminal. +* Minibuffer Commands:: Commands used as key bindings in minibuffers. +* Minibuffer Contents:: How such commands access the minibuffer text. +* Minibuffer Windows:: Operating on the special minibuffer windows. +* Recursive Mini:: Whether recursive entry to minibuffer is allowed. * Minibuffer Misc:: Various customization hooks and variables. @end menu @@ -79,7 +83,7 @@ recursive minibuffers, the innermost (or most recently entered) is the active minibuffer. We usually call this ``the'' minibuffer. You can permit or forbid recursive minibuffers by setting the variable @code{enable-recursive-minibuffers} or by putting properties of that -name on command symbols (@pxref{Minibuffer Misc}). +name on command symbols (@pxref{Recursive Mini}). Like other buffers, a minibuffer may use any of several local keymaps (@pxref{Keymaps}); these contain various exit commands and in some cases @@ -1694,11 +1698,11 @@ return if the user enters empty input. If @var{default} is @code{nil}, then @code{read-passwd} returns the null string in that case. @end defun -@node Minibuffer Misc -@section Minibuffer Miscellany +@node Minibuffer Commands +@section Minibuffer Commands - This section describes some basic functions and variables related to -minibuffers. + This section describes some commands meant for use in the +minibuffer. @deffn Command exit-minibuffer This command exits the active minibuffer. It is normally bound to @@ -1733,65 +1737,11 @@ This command replaces the minibuffer contents with the value of the regular expression). @end deffn -@defun minibuffer-prompt -This function returns the prompt string of the currently active -minibuffer. If no minibuffer is active, it returns @code{nil}. -@end defun - -@defun minibuffer-prompt-end -@tindex minibuffer-prompt-end -This function returns the current -position of the end of the minibuffer prompt, if a minibuffer is -current. Otherwise, it returns the minimum valid buffer position. -@end defun - -@defun minibuffer-contents -@tindex minibuffer-contents -This function returns the editable -contents of the minibuffer (that is, everything except the prompt) as -a string, if a minibuffer is current. Otherwise, it returns the -entire contents of the current buffer. -@end defun - -@defun minibuffer-contents-no-properties -@tindex minibuffer-contents-no-properties -This is like @code{minibuffer-contents}, except that it does not copy text -properties, just the characters themselves. @xref{Text Properties}. -@end defun - -@defun delete-minibuffer-contents -@tindex delete-minibuffer-contents -This function erases the editable -contents of the minibuffer (that is, everything except the prompt), if -a minibuffer is current. Otherwise, it erases the entire buffer. -@end defun - -@defun minibuffer-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 -This is a normal hook that is run whenever the minibuffer is entered. -@xref{Hooks}. -@end defvar - -@defvar minibuffer-exit-hook -This is a normal hook that is run whenever the minibuffer is exited. -@xref{Hooks}. -@end defvar - -@defvar minibuffer-help-form -@anchor{Definition of minibuffer-help-form} -The current value of this variable is used to rebind @code{help-form} -locally inside the minibuffer (@pxref{Help Functions}). -@end defvar +@node Minibuffer Windows +@section Minibuffer Windows -@defun minibufferp &optional buffer-or-name -This function returns non-@code{nil} if @var{buffer-or-name} is a -minibuffer. If @var{buffer-or-name} is omitted, it tests the current -buffer. -@end defun + These functions access and select minibuffer windows +and test whether they are active. @defun active-minibuffer-window This function returns the currently active minibuffer window, or @@ -1832,20 +1782,53 @@ This function returns non-@code{nil} if @var{window}, assumed to be a minibuffer window, is currently active. @end defun -@defvar minibuffer-scroll-window -@anchor{Definition of minibuffer-scroll-window} -If the value of this variable is non-@code{nil}, it should be a window -object. When the function @code{scroll-other-window} is called in the -minibuffer, it scrolls this window. -@end defvar +@node Minibuffer Contents +@section Minibuffer Contents -@defun minibuffer-selected-window -This function returns the window which was selected when the -minibuffer was entered. If selected window is not a minibuffer -window, it returns @code{nil}. + These functions access the minibuffer prompt and contents. + +@defun minibuffer-prompt +This function returns the prompt string of the currently active +minibuffer. If no minibuffer is active, it returns @code{nil}. @end defun -Finally, some functions and variables deal with recursive minibuffers +@defun minibuffer-prompt-end +@tindex minibuffer-prompt-end +This function returns the current +position of the end of the minibuffer prompt, if a minibuffer is +current. Otherwise, it returns the minimum valid buffer position. +@end defun + +@defun minibuffer-prompt-width +This function returns the current display-width of the minibuffer +prompt, if a minibuffer is current. Otherwise, it returns zero. +@end defun + +@defun minibuffer-contents +@tindex minibuffer-contents +This function returns the editable +contents of the minibuffer (that is, everything except the prompt) as +a string, if a minibuffer is current. Otherwise, it returns the +entire contents of the current buffer. +@end defun + +@defun minibuffer-contents-no-properties +@tindex minibuffer-contents-no-properties +This is like @code{minibuffer-contents}, except that it does not copy text +properties, just the characters themselves. @xref{Text Properties}. +@end defun + +@defun delete-minibuffer-contents +@tindex delete-minibuffer-contents +This function erases the editable contents of the minibuffer (that is, +everything except the prompt), if a minibuffer is current. Otherwise, +it erases the entire current buffer. +@end defun + +@node Recursive Mini +@section Recursive Minibuffers + + These functions and variables deal with recursive minibuffers (@pxref{Recursive Editing}): @defun minibuffer-depth @@ -1875,6 +1858,50 @@ to @code{t} in the interactive declaration (@pxref{Using Interactive}). The minibuffer command @code{next-matching-history-element} (normally @kbd{M-s} in the minibuffer) does the latter. +@node Minibuffer Misc +@section Minibuffer Miscellany + +@defun minibufferp &optional buffer-or-name +This function returns non-@code{nil} if @var{buffer-or-name} is a +minibuffer. If @var{buffer-or-name} is omitted, it tests the current +buffer. +@end defun + +@defvar minibuffer-setup-hook +This is a normal hook that is run whenever the minibuffer is entered. +@xref{Hooks}. +@end defvar + +@defvar minibuffer-exit-hook +This is a normal hook that is run whenever the minibuffer is exited. +@xref{Hooks}. +@end defvar + +@defvar minibuffer-help-form +@anchor{Definition of minibuffer-help-form} +The current value of this variable is used to rebind @code{help-form} +locally inside the minibuffer (@pxref{Help Functions}). +@end defvar + +@defvar minibuffer-scroll-window +@anchor{Definition of minibuffer-scroll-window} +If the value of this variable is non-@code{nil}, it should be a window +object. When the function @code{scroll-other-window} is called in the +minibuffer, it scrolls this window. +@end defvar + +@defun minibuffer-selected-window +This function returns the window which was selected when the +minibuffer was entered. If selected window is not a minibuffer +window, it returns @code{nil}. +@end defun + +@defopt max-mini-window-height +This variable specifies the maximum height for resizing minibuffer +windows. If a float, it specifies a fraction of the height of the +frame. If an integer, it specifies a number of lines. +@end defopt + @defun minibuffer-message string This function displays @var{string} temporarily at the end of the minibuffer text, for two seconds, or until the next input event diff --git a/lispref/modes.texi b/lispref/modes.texi index 053e7a511e8..49b05021d91 100644 --- a/lispref/modes.texi +++ b/lispref/modes.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, @c 2003, 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/modes @@ -869,9 +869,7 @@ command interpreter in a @samp{#!} line. Its value is an alist with elements of the form @code{(@var{interpreter} . @var{mode})}; for example, @code{("perl" . perl-mode)} is one element present by default. The element says to use mode @var{mode} if the file -specifies an interpreter which matches @var{interpreter}. The value -of @var{interpreter} is actually a regular expression. @xref{Regular -Expressions}. +specifies an interpreter which matches @var{interpreter}. @end defvar @defvar magic-mode-alist @@ -1373,7 +1371,8 @@ symbol). It defines a command named @var{mode} to toggle the minor mode, with @var{doc} as its documentation string. It also defines a variable named @var{mode}, which is set to @code{t} or @code{nil} by enabling or disabling the mode. The variable is initialized to -@var{init-value}. +@var{init-value}. Except in unusual circumstances (see below), this +value must be @code{nil}. The string @var{lighter} says what to display in the mode line when the mode is enabled; if it is @code{nil}, the mode is not displayed @@ -1424,6 +1423,14 @@ as setting the variable named @var{mode} and then executes the variable @code{@var{mode}-hook}. @end defmac + The initial value must be @code{nil} except in cases where (1) the +mode is preloaded in Emacs, or (2) it is painless to for loading to +enable the mode even though the user did not request it. For +instance, if the mode has no effect unless something else is enabled, +and will always be loaded by that time, enabling it by default is +harmless. But these are unusual circumstances. Normally, the +initial value must be @code{nil}. + @findex easy-mmode-define-minor-mode The name @code{easy-mmode-define-minor-mode} is an alias for this macro. @@ -1607,7 +1614,7 @@ 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}). +mode line (@pxref{Standard Faces,,, emacs, The GNU Emacs Manual}). @table @code @cindex percent symbol in mode line @@ -1920,7 +1927,7 @@ function. @xref{Buffer File Name}. @item %F The title (only on a window system) or the name of the selected frame. -@xref{Window Frame Parameters}. +@xref{Basic Parameters}. @item %i The size of the accessible part of the current buffer; basically diff --git a/lispref/nonascii.texi b/lispref/nonascii.texi index 9683156541d..2af367a0f85 100644 --- a/lispref/nonascii.texi +++ b/lispref/nonascii.texi @@ -1,6 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1998, 1999 Free Software Foundation, Inc. +@c Copyright (C) 1998, 1999, 2002, 2003, 2004, +@c 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/characters @node Non-ASCII Characters, Searching and Matching, Text, Top diff --git a/lispref/numbers.texi b/lispref/numbers.texi index f7f88248ff1..db28a2850a6 100644 --- a/lispref/numbers.texi +++ b/lispref/numbers.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, +@c 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/numbers @node Numbers, Strings and Characters, Lisp Data Types, Top diff --git a/lispref/objects.texi b/lispref/objects.texi index 4a693f186d6..99ef896c4b4 100644 --- a/lispref/objects.texi +++ b/lispref/objects.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, +@c 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/objects @node Lisp Data Types, Numbers, Introduction, Top diff --git a/lispref/os.texi b/lispref/os.texi index 1e6dacb7d80..3f00ae99cf0 100644 --- a/lispref/os.texi +++ b/lispref/os.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2004 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, +@c 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/os @node System Interface, Antinews, Display, Top @@ -21,8 +21,10 @@ pertaining to the terminal and the screen. * System Environment:: Distinguish the name and kind of system. * User Identification:: Finding the name and user id of the user. * Time of Day:: Getting the current time. -* Time Conversion:: Converting a time from numeric form to a string, or - to calendrical data (or vice versa). +* Time Conversion:: Converting a time from numeric form + to calendrical data, and vice versa). +* Time Parsing:: Converting a time from numeric form to text + and vice versa. * Processor Run Time:: Getting the run time used by Emacs. * Time Calculations:: Adding, subtracting, comparing times, etc. * Timers:: Setting a timer to call a function at a certain time. @@ -1071,22 +1073,102 @@ exact. Do not use this function if precise time stamps are required. @section Time Conversion These functions convert time values (lists of two or three integers) -to strings or to calendrical information. There is also a function to -convert calendrical information to a time value. You can get time -values from the functions @code{current-time} (@pxref{Time of Day}) and +to calendrical information and vice versa. You can get time values +from the functions @code{current-time} (@pxref{Time of Day}) and @code{file-attributes} (@pxref{Definition of file-attributes}). -Many operating systems are limited to time values that contain 32 bits + Many operating systems are limited to time values that contain 32 bits of information; these systems typically handle only the times from 1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC. However, some operating systems have larger time values, and can represent times far in the past or future. -Time conversion functions always use the Gregorian calendar, even for -dates before the Gregorian calendar was introduced. Year numbers count -the number of years since the year 1 B.C., and do not skip zero as -traditional Gregorian years do; for example, the year number @minus{}37 -represents the Gregorian year 38 B.C@. + Time conversion functions always use the Gregorian calendar, even +for dates before the Gregorian calendar was introduced. Year numbers +count the number of years since the year 1 B.C., and do not skip zero +as traditional Gregorian years do; for example, the year number +@minus{}37 represents the Gregorian year 38 B.C@. + +@defun decode-time &optional time +This function converts a time value into calendrical information. If +you don't specify @var{time}, it decodes the current time. The return +value is a list of nine elements, as follows: + +@example +(@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone}) +@end example + +Here is what the elements mean: + +@table @var +@item seconds +The number of seconds past the minute, as an integer between 0 and 59. +On some operating systems, this is 60 for leap seconds. +@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. +@item day +The day of the month, as an integer between 1 and 31. +@item month +The month of the year, as an integer between 1 and 12. +@item year +The year, an integer typically greater than 1900. +@item dow +The day of week, as an integer between 0 and 6, where 0 stands for +Sunday. +@item dst +@code{t} if daylight savings time is effect, otherwise @code{nil}. +@item zone +An integer indicating the time zone, as the number of seconds east of +Greenwich. +@end table + +@strong{Common Lisp Note:} Common Lisp has different meanings for +@var{dow} and @var{zone}. +@end defun + +@defun encode-time seconds minutes hour day month year &optional zone +This function is the inverse of @code{decode-time}. It converts seven +items of calendrical data into a time value. For the meanings of the +arguments, see the table above under @code{decode-time}. + +Year numbers less than 100 are not treated specially. If you want them +to stand for years above 1900, or years above 2000, 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 +(as you would get from @code{current-time-zone}), a string as in the +@code{TZ} environment variable, @code{t} for Universal Time, or an +integer (as you would get from @code{decode-time}). The specified +zone is used without any further alteration for daylight savings time. + +If you pass more than seven arguments to @code{encode-time}, the first +six are used as @var{seconds} through @var{year}, the last argument is +used as @var{zone}, and the arguments in between are ignored. This +feature makes it possible to use the elements of a list returned by +@code{decode-time} as the arguments to @code{encode-time}, like this: + +@example +(apply 'encode-time (decode-time @dots{})) +@end example + +You can perform simple date arithmetic by using out-of-range values for +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; +if you try to encode a time that is out of range, an error results. +For instance, years before 1970 do not work on some systems; +on others, years as early as 1901 do work. +@end defun + +@node Time Parsing +@section Parsing and Formatting Times + + These functions convert time values (lists of two or three integers) +to text in a string, and vice versa. @defun date-to-time string This function parses the time-string @var{string} and returns the @@ -1213,81 +1295,6 @@ seconds since the epoch, to a time value and returns that. To perform the inverse conversion, use @code{float-time}. @end defun -@defun decode-time &optional time -This function converts a time value into calendrical information. If -you don't specify @var{time}, it decodes the current time. The return -value is a list of nine elements, as follows: - -@example -(@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone}) -@end example - -Here is what the elements mean: - -@table @var -@item seconds -The number of seconds past the minute, as an integer between 0 and 59. -On some operating systems, this is 60 for leap seconds. -@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. -@item day -The day of the month, as an integer between 1 and 31. -@item month -The month of the year, as an integer between 1 and 12. -@item year -The year, an integer typically greater than 1900. -@item dow -The day of week, as an integer between 0 and 6, where 0 stands for -Sunday. -@item dst -@code{t} if daylight savings time is effect, otherwise @code{nil}. -@item zone -An integer indicating the time zone, as the number of seconds east of -Greenwich. -@end table - -@strong{Common Lisp Note:} Common Lisp has different meanings for -@var{dow} and @var{zone}. -@end defun - -@defun encode-time seconds minutes hour day month year &optional zone -This function is the inverse of @code{decode-time}. It converts seven -items of calendrical data into a time value. For the meanings of the -arguments, see the table above under @code{decode-time}. - -Year numbers less than 100 are not treated specially. If you want them -to stand for years above 1900, or years above 2000, 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 -(as you would get from @code{current-time-zone}), a string as in the -@code{TZ} environment variable, @code{t} for Universal Time, or an -integer (as you would get from @code{decode-time}). The specified -zone is used without any further alteration for daylight savings time. - -If you pass more than seven arguments to @code{encode-time}, the first -six are used as @var{seconds} through @var{year}, the last argument is -used as @var{zone}, and the arguments in between are ignored. This -feature makes it possible to use the elements of a list returned by -@code{decode-time} as the arguments to @code{encode-time}, like this: - -@example -(apply 'encode-time (decode-time @dots{})) -@end example - -You can perform simple date arithmetic by using out-of-range values for -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; -if you try to encode a time that is out of range, an error results. -For instance, years before 1970 do not work on some systems; -on others, years as early as 1901 do work. -@end defun - @node Processor Run Time @section Processor Run time diff --git a/lispref/positions.texi b/lispref/positions.texi index 3c1e642e6b4..cb249f526f1 100644 --- a/lispref/positions.texi +++ b/lispref/positions.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001, +@c 2002, 2003, 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/positions @node Positions, Markers, Frames, Top @@ -636,7 +636,7 @@ the end of the accessible portion of the buffer, and pass @var{line} and When you use @code{compute-motion} for the minibuffer, you need to use @code{minibuffer-prompt-width} to get the horizontal position of the -beginning of the first screen line. @xref{Minibuffer Misc}. +beginning of the first screen line. @xref{Minibuffer Contents}. @end defun @node List Motion diff --git a/lispref/processes.texi b/lispref/processes.texi index dddb08bc46b..afdeaa1d2a0 100644 --- a/lispref/processes.texi +++ b/lispref/processes.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2005 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, +@c 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/processes @node Processes, Display, Abbrevs, Top @@ -52,6 +52,7 @@ This function returns @code{t} if @var{object} is a process, * Datagrams:: UDP network connections. * Low-Level Network:: Lower-level but more general function to create connections and servers. +* Misc Network:: Additional relevant functions for network connections. * Byte Packing:: Using bindat to pack and unpack binary data. @end menu @@ -1716,6 +1717,20 @@ sets its remote peer address to @var{address}. @node Low-Level Network @section Low-Level Network Access + You can also create network connections by operating at a lower +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 + the machine you are using. +@end menu + +@node Make Network +@subsection @code{make-network-process} + The basic function for creating network connections and network servers is @code{make-network-process}. It can do either of those jobs, depending on the arguments you give it. @@ -1852,14 +1867,21 @@ happened. Initialize the process plist to @var{plist}. @end table -The following network options can be specified for the network -process. Except for @code{:reuseaddr}, you can set or modify these -options later using @code{set-network-process-option}. +The original argument list, modified with the actual connection +information, is available via the @code{process-contact} function. +@end defun + +@node Network Options +@subsection Network Options -For a server process, the options specified with + The following network options can be specified when you create a +network process. Except for @code{:reuseaddr}, you can also set or +modify these options later, using @code{set-network-process-option}. + + For a server process, the options specified with @code{make-network-process} are not inherited by the client connections, so you will need to set the necessary options for each -child connection as they are created. +child connection as it is created. @table @asis @item :bindtodevice @var{device-name} @@ -1914,13 +1936,8 @@ listening on that port. If @var{reuseaddr-flag} is @code{nil}, there may be a period of time after the last use of that port (by any process on the host), where it is not possible to make a new server on that port. - @end table -The original argument list, modified with the actual connection -information, is available via the @code{process-contact} function. -@end defun - @defun set-network-process-option process option value This function sets or modifies a network option for network process @var{process}. See @code{make-network-process} for details of options @@ -1930,44 +1947,8 @@ The current setting of an option is available via the @code{process-contact} function. @end defun -@defun network-interface-list -This function returns a list describing the network interfaces -of the machine you are using. The value is an alist whose -elements have the form @code{(@var{name} . @var{address})}. -@var{address} has the same form as the @var{local-address} -and @var{remote-address} arguments to @code{make-network-process}. -@end defun - -@defun network-interface-info ifname -This function returns information about the network interface named -@var{ifname}. The value is a list of the form -@code{(@var{addr} @var{bcast} @var{netmask} @var{hwaddr} @var{flags})}. - -@table @var -@item addr -The internet protocol address. -@item bcast -The broadcast address. -@item netmask -The network mask. -@item hwaddr -The layer 2 address (Ethernet MAC address, for instance). -@item flags -The current flags of the interface. -@end table -@end defun - -@defun format-network-address address &optional omit-port -This function converts the Lisp representation of a network address to -a string. For example, a five-element vector @code{[@var{a} @var{b} -@var{c} @var{d} @var{p}]} represents an IP address -@var{a}.@var{b}.@var{c}.@var{d} and port number @var{p}. -@code{format-network-address} converts that to the string -@code{"@var{a}.@var{b}.@var{c}.@var{d}:@var{p}"}. - -If @var{omit-port} is non-@code{nil}, the value does not include -the port number. -@end defun +@node Network Feature Testing +@subsection Testing Availability of Network Features To test for the availability of a given network feature, use @code{featurep} like this: @@ -2002,8 +1983,8 @@ Non-@code{nil} if the system can select the port for a server. (featurep 'make-network-process '@var{keyword}) @end example -Here are some of the option @var{keyword}s you can test in -this way. +@noindent +Here are some of the options you can test in this way. @table @code @item :bindtodevice @@ -2018,6 +1999,51 @@ That particular network option is supported by @code{make-network-process} and @code{set-network-process-option}. @end table +@node Misc Network +@section Misc Network Facilities + + These additional functions are useful for creating and operating +on network connections. + +@defun network-interface-list +This function returns a list describing the network interfaces +of the machine you are using. The value is an alist whose +elements have the form @code{(@var{name} . @var{address})}. +@var{address} has the same form as the @var{local-address} +and @var{remote-address} arguments to @code{make-network-process}. +@end defun + +@defun network-interface-info ifname +This function returns information about the network interface named +@var{ifname}. The value is a list of the form +@code{(@var{addr} @var{bcast} @var{netmask} @var{hwaddr} @var{flags})}. + +@table @var +@item addr +The internet protocol address. +@item bcast +The broadcast address. +@item netmask +The network mask. +@item hwaddr +The layer 2 address (Ethernet MAC address, for instance). +@item flags +The current flags of the interface. +@end table +@end defun + +@defun format-network-address address &optional omit-port +This function converts the Lisp representation of a network address to +a string. For example, a five-element vector @code{[@var{a} @var{b} +@var{c} @var{d} @var{p}]} represents an IP address +@var{a}.@var{b}.@var{c}.@var{d} and port number @var{p}. +@code{format-network-address} converts that to the string +@code{"@var{a}.@var{b}.@var{c}.@var{d}:@var{p}"}. + +If @var{omit-port} is non-@code{nil}, the value does not include +the port number. +@end defun + @node Byte Packing @section Packing and Unpacking Byte Arrays diff --git a/lispref/searching.texi b/lispref/searching.texi index cfb5a87d8ec..e702469a14b 100644 --- a/lispref/searching.texi +++ b/lispref/searching.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2004 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, +@c 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/searching @node Searching and Matching, Syntax Tables, Non-ASCII Characters, Top @@ -167,6 +167,16 @@ denotes a (possibly infinite) set of strings. Searching for matches for a regexp is a very powerful operation. This section explains how to write regexps; the following section says how to search for them. +@findex re-builder +@cindex authoring regular expressions + For convenient interactive development of regular expressions, you +can use the @kbd{M-x re-builder} command. It provides a convenient +interface for creating regular expressions, by giving immediate visual +feedback in a separate buffer. As you edit the regexp, all its +matches in the target buffer are highlighted. Each parenthesized +sub-expression of the regexp is shown in a distinct face, which makes +it easier to verify even very complex regexps. + @menu * Syntax of Regexps:: Rules for writing regular expressions. * Regexp Example:: Illustrates regular expression syntax. @@ -1137,6 +1147,25 @@ A positive number means to include that many lines both before and after. @section Search and Replace @cindex replacement +@defun replace-regexp-in-string regexp rep string &optional fixedcase literal subexp start +This function copies @var{string} and searches it for matches for +@var{regexp}, and replaces them with @var{rep}. It returns the +modified copy. If @var{start} is non-@code{nil}, the search for +matches starts at that index in @var{string}, so matches starting +before that index are not changed. + +This function uses @code{replace-match} to do the replacement, and it +passes the optional arguments @var{fixedcase}, @var{literal} and +@var{subexp} along to @code{replace-match}. + +Instead of a string, @var{rep} can be a function. In that case, +@code{replace-regexp-in-string} calls @var{rep} for each match, +passing the text of the match as its sole argument. It collects the +value @var{rep} returns and passes that to @code{replace-match} as the +replacement string. The match-data at this point are the result +of matching @var{regexp} against a substring of @var{string}. +@end defun + @defun perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map start end This function is the guts of @code{query-replace} and related commands. It searches for occurrences of @var{from-string} in the diff --git a/lispref/sequences.texi b/lispref/sequences.texi index 61387fe1e0c..eade483bda3 100644 --- a/lispref/sequences.texi +++ b/lispref/sequences.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, +@c 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/sequences @node Sequences Arrays Vectors, Hash Tables, Lists, Top diff --git a/lispref/streams.texi b/lispref/streams.texi index 09f8695cd25..b5a18e27d01 100644 --- a/lispref/streams.texi +++ b/lispref/streams.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2002, 2003, 2004, +@c 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/streams @node Read and Print, Minibuffers, Debugging, Top diff --git a/lispref/strings.texi b/lispref/strings.texi index d0504684f82..18c516041d6 100644 --- a/lispref/strings.texi +++ b/lispref/strings.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, +@c 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/strings @node Strings and Characters, Lists, Numbers, Top diff --git a/lispref/symbols.texi b/lispref/symbols.texi index 9f59ad1f02d..9e4b482cfa0 100644 --- a/lispref/symbols.texi +++ b/lispref/symbols.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2003 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, +@c 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/symbols @node Symbols, Evaluation, Hash Tables, Top diff --git a/lispref/syntax.texi b/lispref/syntax.texi index e582b52a2c8..5cde2badabd 100644 --- a/lispref/syntax.texi +++ b/lispref/syntax.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2004, 2005 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, +@c 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/syntax @node Syntax Tables, Abbrevs, Searching and Matching, Top diff --git a/lispref/text.texi b/lispref/text.texi index 5b9b4259a1c..59259415cc0 100644 --- a/lispref/text.texi +++ b/lispref/text.texi @@ -1,8 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, -@c 2000, 2001, 2004, 2005 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001, +@c 2002, 2003, 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/text @node Text, Non-ASCII Characters, Markers, Top diff --git a/lispref/tindex.pl b/lispref/tindex.pl index f3372bf21ee..68931bc9ed6 100755 --- a/lispref/tindex.pl +++ b/lispref/tindex.pl @@ -1,6 +1,6 @@ #! /usr/bin/perl -# Copyright (C) 2000 Free Software Foundation, Inc. +# Copyright (C) 2000, 2002, 2003, 2004, 2005 Free Software Foundation, Inc. # # This file is part of GNU Emacs. # diff --git a/lispref/tips.texi b/lispref/tips.texi index 6e309155876..46eb887dce8 100644 --- a/lispref/tips.texi +++ b/lispref/tips.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1995, 1998, 1999 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1995, 1998, 1999, 2002, 2003, +@c 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/tips @node Tips, GNU Emacs Internals, GPL, Top @@ -23,7 +23,10 @@ all. @menu * Coding Conventions:: Conventions for clean and robust programs. +* Key Binding Conventions:: Which keys should be bound by which programs. +* Programming Tips:: Making Emacs code fit smoothly in Emacs. * Compilation Tips:: Making compiled code run fast. +* Warning Tips:: Turning off compiler warnings. * Documentation Tips:: Writing readable documentation strings. * Comment Tips:: Conventions for writing comments. * Library Headers:: Standard headers for library packages. @@ -68,7 +71,7 @@ in your program. Call it @code{mylib-twiddle-files} in your program, and send mail to @samp{bug-gnu-emacs@@gnu.org} suggesting we add it to Emacs. If and when we do, we can change the name easily enough. -If one prefix is insufficient, your package may use two or three +If one prefix is insufficient, your package can use two or three alternative common prefixes, so long as they make sense. Separate the prefix from the rest of the symbol name with a hyphen, @@ -76,12 +79,10 @@ Separate the prefix from the rest of the symbol name with a hyphen, Lisp programs. @item -It is often useful to put a call to @code{provide} in each separate -library program, at least if there is more than one entry point to the -program. +Put a call to @code{provide} at the end of each separate Lisp file. @item -If a file requires certain other library programs to be loaded +If a file requires certain other Lisp programs to be loaded beforehand, then the comments at the beginning of the file should say so. Also, use @code{require} to make sure they are loaded. @@ -138,6 +139,118 @@ to store a list of functions (i.e., the variable is a hook), please follow the naming conventions for hooks. @xref{Hooks}. @item +@cindex unloading packages +If loading the file adds functions to hooks, define a function +@code{@var{feature}-unload-hook}, where @var{feature} is the name of +the feature the package provides, and make it undo any such changes. +Using @code{unload-feature} to unload the file will run this function. +@xref{Unloading}. + +@item +It is a bad idea to define aliases for the Emacs primitives. Normally +you should use the standard names instead. The case where an alias +may be useful is where it facilitates backwards compatibility or +portability. + +@item +If a package needs to define an alias or a new function for +compatibility with some other version of Emacs, name it with the package +prefix, not with the raw name with which it occurs in the other version. +Here is an example from Gnus, which provides many examples of such +compatibility issues. + +@example +(defalias 'gnus-point-at-bol + (if (fboundp 'point-at-bol) + 'point-at-bol + 'line-beginning-position)) +@end example + +@item +Redefining (or advising) an Emacs primitive is discouraged. It may do +the right thing for a particular program, but there is no telling what +other programs might break as a result. + +@item +If a file does replace any of the functions or library programs of +standard Emacs, prominent comments at the beginning of the file should +say which functions are replaced, and how the behavior of the +replacements differs from that of the originals. + +@item +Avoid using macros that define functions and variables with names that +are constructed. It is best for maintenance when the name of the +function or variable being defined is given explicitly in the source +code, as the second element of the list---as it is when you use +@code{defun}, @code{defalias}, @code{defvar} and @code{defcustom}. + +@item +Please keep the names of your Emacs Lisp source files to 13 characters +or less. This way, if the files are compiled, the compiled files' names +will be 14 characters or less, which is short enough to fit on all kinds +of Unix systems. + +@item +In some other systems there is a convention of choosing variable names +that begin and end with @samp{*}. We don't use that convention in Emacs +Lisp, so please don't use it in your programs. (Emacs uses such names +only for special-purpose buffers.) The users will find Emacs more +coherent if all libraries use the same conventions. + +@item +Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the +default indentation parameters. + +@item +Don't make a habit of putting close-parentheses on lines by themselves; +Lisp programmers find this disconcerting. Once in a while, when there +is a sequence of many consecutive close-parentheses, it may make sense +to split the sequence in one or two significant places. + +@item +Please put a copyright notice and copying permission notice on the +file if you distribute copies. Use a notice like this one: + +@smallexample +;; Copyright (C) @var{year} @var{name} + +;; This program is free software; you can redistribute it and/or +;; modify it under the terms of the GNU General Public License as +;; published by the Free Software Foundation; either version 2 of +;; the License, or (at your option) any later version. + +;; This program is distributed in the hope that it will be +;; useful, but WITHOUT ANY WARRANTY; without even the implied +;; warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR +;; PURPOSE. See the GNU General Public License for more details. + +;; You should have received a copy of the GNU General Public +;; License along with this program; if not, write to the Free +;; Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, +;; MA 02110-1301 USA +@end smallexample + +If you have signed papers to assign the copyright to the Foundation, +then use @samp{Free Software Foundation, Inc.} as @var{name}. +Otherwise, use your name. See also @xref{Library Headers}. +@end itemize + +@node Key Binding Conventions +@section Key Binding Conventions + +@itemize @bullet +@item +@cindex mouse-2 +@cindex references, following +Special major modes used for read-only text should usually redefine +@kbd{mouse-2} and @key{RET} to trace some sort of reference in the text. +Modes such as Dired, Info, Compilation, and Occur redefine it in this +way. + +In addition, they should mark the text as a kind of ``link'' so that +@kbd{mouse-1} will follow it also. @xref{Links and Mouse-1}. + +@item @cindex reserved keys @cindex keys, reserved Please do not define @kbd{C-c @var{letter}} as a key in Lisp programs. @@ -199,67 +312,15 @@ is potentially meaningful, then you must not define @kbd{@key{ESC} after @key{ESC}. In these states, you should define @kbd{@key{ESC} @key{ESC} @key{ESC}} as the way to escape. Otherwise, define @kbd{@key{ESC} @key{ESC}} instead. +@end itemize -@item -@cindex mouse-2 -@cindex references, following -Special major modes used for read-only text should usually redefine -@kbd{mouse-2} and @key{RET} to trace some sort of reference in the text. -Modes such as Dired, Info, Compilation, and Occur redefine it in this -way. - -In addition, they should mark the text as a kind of ``link'' so that -@kbd{mouse-1} will follow it also. @xref{Links and Mouse-1}. - -@cindex unloading packages -If loading the file adds functions to hooks, define a function -@code{@var{feature}-unload-hook}, where @var{feature} is the name of -the feature the package provides, and make it undo any such changes. -Using @code{unload-feature} to unload the file will run this function. -@xref{Unloading}. - -@item -It is a bad idea to define aliases for the Emacs primitives. Use the -standard names instead. - -@item -If a package needs to define an alias or a new function for -compatibility with some other version of Emacs, name it with the package -prefix, not with the raw name with which it occurs in the other version. -Here is an example from Gnus, which provides many examples of such -compatibility issues. - -@example -(defalias 'gnus-point-at-bol - (if (fboundp 'point-at-bol) - 'point-at-bol - 'line-beginning-position)) -@end example - -@item -Redefining (or advising) an Emacs primitive is discouraged. It may do -the right thing for a particular program, but there is no telling what -other programs might break as a result. - -@item -If a file does replace any of the functions or library programs of -standard Emacs, prominent comments at the beginning of the file should -say which functions are replaced, and how the behavior of the -replacements differs from that of the originals. - -@item -Avoid using macros that define functions and variables with names that -are constructed. It is best for maintenance when the name of the -function or variable being defined is given explicitly in the source -code, as the second element of the list---as it is when you use -@code{defun}, @code{defalias}, @code{defvar} and @code{defcustom}. +@node Programming Tips +@section Emacs Programming Tips -@item -Please keep the names of your Emacs Lisp source files to 13 characters -or less. This way, if the files are compiled, the compiled files' names -will be 14 characters or less, which is short enough to fit on all kinds -of Unix systems. + Following these conventions will make your program fit better +into Emacs when it runs. +@itemize @bullet @item Don't use @code{next-line} or @code{previous-line} in programs; nearly always, @code{forward-line} is more convenient as well as more @@ -278,11 +339,14 @@ In particular, don't use any of these functions: @code{beginning-of-buffer}, @code{end-of-buffer} @item @code{replace-string}, @code{replace-regexp} +@item +@code{insert-file}, @code{insert-buffer} @end itemize -If you just want to move point, or replace a certain string, without any -of the other features intended for interactive users, you can replace -these functions with one or two lines of simple Lisp code. +If you just want to move point, or replace a certain string, or insert +a file or buffer's contents, without any of the other features +intended for interactive users, you can replace these functions with +one or two lines of simple Lisp code. @item Use lists rather than vectors, except when there is a particular reason @@ -294,7 +358,7 @@ accessed in random order (not searched front to back), provided there is no need to insert or delete elements (only lists allow that). @item -The recommended way to print a message in the echo area is with +The recommended way to show a message in the echo area is with the @code{message} function, not @code{princ}. @xref{The Echo Area}. @item @@ -358,80 +422,6 @@ command does: use a new local keymap that contains one command defined to switch back to the old local keymap. Or do what the @code{edit-options} command does: switch to another buffer and let the user switch back at will. @xref{Recursive Editing}. - -@item -In some other systems there is a convention of choosing variable names -that begin and end with @samp{*}. We don't use that convention in Emacs -Lisp, so please don't use it in your programs. (Emacs uses such names -only for special-purpose buffers.) The users will find Emacs more -coherent if all libraries use the same conventions. - -@item -Try to avoid compiler warnings about undefined free variables, by adding -dummy @code{defvar} definitions for these variables, like this: - -@example -(defvar foo) -@end example - -Such a definition has no effect except to tell the compiler -not to warn about uses of the variable @code{foo} in this file. - -@item -If you use many functions and variables from a certain file, you can -add a @code{require} for that package to avoid compilation warnings -for them. For instance, - -@example -(eval-when-compile - (require 'foo)) -@end example - -@item -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 adding a definition would be -unclean if the variable has a short name, since Lisp packages should -not define short variable names. The right thing to do is to rename -this variable to start with the name prefix used for the other -functions and variables in your package. - -@item -Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the -default indentation parameters. - -@item -Don't make a habit of putting close-parentheses on lines by themselves; -Lisp programmers find this disconcerting. Once in a while, when there -is a sequence of many consecutive close-parentheses, it may make sense -to split the sequence in one or two significant places. - -@item -Please put a copyright notice on the file if you give copies to anyone. -Use a message like this one: - -@smallexample -;; Copyright (C) @var{year} @var{name} - -;; This program is free software; you can redistribute it and/or -;; modify it under the terms of the GNU General Public License as -;; published by the Free Software Foundation; either version 2 of -;; the License, or (at your option) any later version. - -;; This program is distributed in the hope that it will be -;; useful, but WITHOUT ANY WARRANTY; without even the implied -;; warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR -;; PURPOSE. See the GNU General Public License for more details. - -;; You should have received a copy of the GNU General Public -;; License along with this program; if not, write to the Free -;; Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, -;; MA 02110-1301 USA -@end smallexample - -If you have signed papers to assign the copyright to the Foundation, -then use @samp{Free Software Foundation, Inc.} as @var{name}. -Otherwise, use your name. See also @xref{Library Headers}. @end itemize @node Compilation Tips @@ -495,6 +485,46 @@ a noticeable speedup in something slow enough that users care about the speed. @xref{Inline Functions}. @end itemize +@node Warning Tips +@section Tips for Avoiding Compiler Warnings + +@itemize @bullet +@item +Try to avoid compiler warnings about undefined free variables, by adding +dummy @code{defvar} definitions for these variables, like this: + +@example +(defvar foo) +@end example + +Such a definition has no effect except to tell the compiler +not to warn about uses of the variable @code{foo} in this file. + +@item +If you use many functions and variables from a certain file, you can +add a @code{require} for that package to avoid compilation warnings +for them. For instance, + +@example +(eval-when-compile + (require 'foo)) +@end example + +@item +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 adding a definition would be +unclean if the variable has a short name, since Lisp packages should +not define short variable names. The right thing to do is to rename +this variable to start with the name prefix used for the other +functions and variables in your package. + +@item +The last resort for avoiding a warning, when you want to do something +that usually is a mistake but it's not a mistake in this one case, +is to put a call to @code{with-no-warnings} around it. +@end itemize + @node Documentation Tips @section Tips for Documentation Strings diff --git a/lispref/variables.texi b/lispref/variables.texi index 38fb929c16d..1f26b56db8f 100644 --- a/lispref/variables.texi +++ b/lispref/variables.texi @@ -1,8 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, -@c 2000, 2003, 2004 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2002, +@c 2003, 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/variables @node Variables, Functions, Control Structures, Top diff --git a/lispref/vol1.texi b/lispref/vol1.texi index f772fc58be5..e0a1f02df8d 100644 --- a/lispref/vol1.texi +++ b/lispref/vol1.texi @@ -2,8 +2,8 @@ This file is obsolete, and no longer part of the Emacs Lisp Reference Manual. It is still present in CVS in case we ever want to use some of it again. @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, +@c 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. \input texinfo @c -*-texinfo-*- diff --git a/lispref/vol2.texi b/lispref/vol2.texi index a4c6d4ae795..40ec8c4904f 100644 --- a/lispref/vol2.texi +++ b/lispref/vol2.texi @@ -2,8 +2,8 @@ This file is obsolete, and no longer part of the Emacs Lisp Reference Manual. It is still present in CVS in case we ever want to use some of it again. @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, +@c 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. diff --git a/lispref/windows.texi b/lispref/windows.texi index ec372d98aa8..e204a7ce7d0 100644 --- a/lispref/windows.texi +++ b/lispref/windows.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2004 -@c Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, +@c 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/windows @node Windows, Frames, Buffers, Top @@ -267,7 +267,7 @@ Now the screen looks like this: @end smallexample Normally, Emacs indicates the border between two side-by-side windows -with a scroll bar (@pxref{Window Frame Parameters,Scroll Bars}) or @samp{|} +with a scroll bar (@pxref{Layout Parameters,Scroll Bars}) or @samp{|} characters. The display table can specify alternative border characters; see @ref{Display Tables}. @end deffn |