From ddb54206dd7aa4f461f59fe98b982691e1432a61 Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Sun, 28 Aug 2011 14:49:59 -0400 Subject: [PATCH] Update manuals for some Emacs 24 changes. * doc/emacs/misc.texi (emacsclient Options): Document server-port. * doc/lispref/display.texi (Progress): Document spinner functionality. * doc/lispref/frames.texi (Layout Parameters): The defaults for the menu-bar-lines and tool-bar-lines parameters depend on the mode. * doc/lispref/objects.texi (Symbol Type): Document ## print representation. * doc/lispref/os.texi (Killing Emacs): Note that kill-emacs can be called by operating system signals. Refer to save-buffers-kill-terminal instead of save-buffers-kill-emacs. --- doc/emacs/ChangeLog | 4 +++ doc/emacs/emacs.texi | 6 ++++ doc/emacs/misc.texi | 5 +++ doc/lispref/ChangeLog | 13 ++++++++ doc/lispref/display.texi | 55 +++++++++++++++++--------------- doc/lispref/frames.texi | 17 +++++----- doc/lispref/objects.texi | 10 ++++-- doc/lispref/os.texi | 68 +++++++++++++++++++++++----------------- etc/NEWS | 29 ++++++++++------- 9 files changed, 129 insertions(+), 78 deletions(-) diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog index 50eb89fe488..b3330022cb3 100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@ -1,3 +1,7 @@ +2011-08-28 Chong Yidong + + * misc.texi (emacsclient Options): Document server-port. + 2011-08-27 Eli Zaretskii * frames.texi (Frame Commands): Advise setting focus-follows-mouse diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index 060f939fa7a..5f0d66b95a3 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -1054,6 +1054,12 @@ Hyperlinking and Navigation Features * Goto Address mode:: Activating URLs. * FFAP:: Finding files etc. at point. +Emacs Lisp Packages + +* Package Menu:: Buffer for viewing and managing packages. +* Package Installation:: Options for package installation. +* Package Files:: Where packages are installed. + Customization * Easy Customization:: Convenient way to browse and change settings. diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi index 2dab70c512a..598f495784f 100644 --- a/doc/emacs/misc.texi +++ b/doc/emacs/misc.texi @@ -1596,6 +1596,11 @@ runs, and (ii) provide @command{emacsclient} with the server file. (One convenient way to do the latter is to put the server file on a networked file system such as NFS.) +@vindex server-port + When the Emacs server is using TCP, the variable @code{server-port} +determines the port number to listen on; the default value, +@code{nil}, means to choose a random port when the server starts. + @item -n @itemx --no-wait Let @command{emacsclient} exit immediately, instead of waiting until diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index ca9c93b563d..2d46ad3f774 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,16 @@ +2011-08-28 Chong Yidong + + * frames.texi (Layout Parameters): The defaults for the + menu-bar-lines and tool-bar-lines parameters depend on the mode. + + * display.texi (Progress): Document spinner functionality. + + * os.texi (Killing Emacs): Note that kill-emacs can be called by + operating system signals. Refer to save-buffers-kill-terminal + instead of save-buffers-kill-emacs. + + * objects.texi (Symbol Type): Document ## print representation. + 2011-08-25 Eli Zaretskii * display.texi (Specified Space): Mention that `space' specs diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index bf7cd126a26..cfe4b8298fb 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -367,10 +367,9 @@ echo area, or @code{nil} if there is none. When an operation can take a while to finish, you should inform the user about the progress it makes. This way the user can estimate remaining time and clearly see that Emacs is busy working, not hung. +A convenient way to do this is to use a @dfn{progress reporter}. - Functions listed in this section provide simple and efficient way of -reporting operation progress. Here is a working example that does -nothing useful: + Here is a working example that does nothing useful: @smallexample (let ((progress-reporter @@ -382,11 +381,11 @@ nothing useful: (progress-reporter-done progress-reporter)) @end smallexample -@defun make-progress-reporter message min-value max-value &optional current-value min-change min-time -This function creates and returns a @dfn{progress reporter}---an -object you will use as an argument for all other functions listed -here. The idea is to precompute as much data as possible to make -progress reporting very fast. +@defun make-progress-reporter message &optional min-value max-value current-value min-change min-time +This function creates and returns a progress reporter object, which +you will use as an argument for the other functions listed below. The +idea is to precompute as much data as possible to make progress +reporting very fast. When this progress reporter is subsequently used, it will display @var{message} in the echo area, followed by progress percentage. @@ -394,24 +393,28 @@ When this progress reporter is subsequently used, it will display on a filename, for instance, use @code{format} before calling this function. -@var{min-value} and @var{max-value} arguments stand for starting and -final states of your operation. For instance, if you scan a buffer, -they should be the results of @code{point-min} and @code{point-max} -correspondingly. It is required that @var{max-value} is greater than -@var{min-value}. If you create progress reporter when some part of -the operation has already been completed, then specify -@var{current-value} argument. But normally you should omit it or set -it to @code{nil}---it will default to @var{min-value} then. - -Remaining arguments control the rate of echo area updates. Progress -reporter will wait for at least @var{min-change} more percents of the -operation to be completed before printing next message. -@var{min-time} specifies the minimum time in seconds to pass between -successive prints. It can be fractional. Depending on Emacs and -system capabilities, progress reporter may or may not respect this -last argument or do it with varying precision. Default value for -@var{min-change} is 1 (one percent), for @var{min-time}---0.2 -(seconds.) +The arguments @var{min-value} and @var{max-value} should be numbers +standing for the starting and final states of the operation. For +instance, an operation that ``scans'' a buffer should set these to the +results of @code{point-min} and @code{point-max} correspondingly. +@var{max-value} should be greater than @var{min-value}. + +Alternatively, you can set @var{min-value} and @var{max-value} to +@code{nil}. In that case, the progress reporter does not report +process percentages; it instead displays a ``spinner'' that rotates a +notch each time you update the progress reporter. + +If @var{min-value} and @var{max-value} are numbers, you can give the +argument @var{current-value} a numerical value specifying the initial +progress; if omitted, this defaults to @var{min-value}. + +The remaining arguments control the rate of echo area updates. The +progress reporter will wait for at least @var{min-change} more +percents of the operation to be completed before printing next +message; the default is one percent. @var{min-time} specifies the +minimum time in seconds to pass between successive prints; the default +is 0.2 seconds. (On some operating systems, the progress reporter may +handle fractions of seconds with varying precision). This function calls @code{progress-reporter-update}, so the first message is printed immediately. diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index b6012a4dd53..e799cfa6b7f 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -695,20 +695,19 @@ 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. -@vindex menu-bar-lines, a frame parameter +@vindex menu-bar-lines frame parameter @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.) +bar. The default is 1 if Menu Bar mode is enabled, and 0 otherwise. +@xref{Menu Bars,,,emacs, The GNU Emacs Manual}. -@vindex tool-bar-lines, a frame parameter +@vindex tool-bar-lines frame parameter @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 and Nextstep allow at most one -tool bar line; they treat larger values as 1.) +The number of lines to use for the tool bar. The default is 1 if Tool +Bar mode is enabled, and 0 otherwise. @xref{Tool Bars,,,emacs, The +GNU Emacs Manual}. -@vindex tool-bar-position, a frame parameter +@vindex tool-bar-position frame parameter @item tool-bar-position The position of the tool bar. Currently only for the GTK tool bar. Value can be one of @code{top}, @code{bottom} @code{left}, @code{right}. diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index 6d63bb7b750..26def7858b7 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -597,6 +597,7 @@ FOO ; @r{A symbol named @samp{FOO}, different from @samp{foo}.} @end group @end example +@cindex @samp{##} read syntax @ifinfo @c This uses ``colon'' instead of a literal `:' because Info cannot @c cope with a `:' in a menu @@ -605,9 +606,12 @@ FOO ; @r{A symbol named @samp{FOO}, different from @samp{foo}.} @ifnotinfo @cindex @samp{#:} read syntax @end ifnotinfo - Normally the Lisp reader interns all symbols (@pxref{Creating -Symbols}). To prevent interning, you can write @samp{#:} before the -name of the symbol. + As an exception to the rule that a symbol's name serves as its +printed representation, @samp{##} is the printed representation for an +interned symbol whose name is an empty string. Furthermore, +@samp{#:@var{foo}} is the printed representation for an uninterned +symbol whose name is @var{foo}. (Normally, the Lisp reader interns +all symbols; @pxref{Creating Symbols}.) @node Sequence Type @subsection Sequence Types diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index 8533b77b219..7d05f8f3468 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -544,10 +544,11 @@ parent process normally resumes control. The low-level primitive for killing Emacs is @code{kill-emacs}. @deffn Command kill-emacs &optional exit-data -This command exits the Emacs process and kills it. +This command calls the hook @code{kill-emacs-hook}, then exits the +Emacs process and kills it. -If @var{exit-data} is an integer, then it is used as the exit status -of the Emacs process. (This is useful primarily in batch operation; see +If @var{exit-data} is an integer, that is used as the exit status of +the Emacs process. (This is useful primarily in batch operation; see @ref{Batch Mode}.) If @var{exit-data} is a string, its contents are stuffed into the @@ -555,35 +556,44 @@ terminal input buffer so that the shell (or whatever program next reads input) can read them. @end deffn - All the information in the Emacs process, aside from files that have -been saved, is lost when the Emacs process is killed. Because killing -Emacs inadvertently can lose a lot of work, Emacs queries for -confirmation before actually terminating if you have buffers that need -saving or subprocesses that are running. This is done in the function -@code{save-buffers-kill-emacs}, the higher level function from which -@code{kill-emacs} is usually called. +@cindex SIGTERM +@cindex SIGHUP +@cindex SIGINT +@cindex operating system signal + The @code{kill-emacs} function is normally called via the +higher-level command @kbd{C-x C-c} +(@code{save-buffers-kill-terminal}). @xref{Exiting,,, emacs, The GNU +Emacs Manual}. It is also called automatically if Emacs receives a +@code{SIGTERM} or @code{SIGHUP} operating system signal (e.g. when the +controlling terminal is disconnected), or if it receives a +@code{SIGINT} signal while running in batch mode (@pxref{Batch Mode}). -@defvar kill-emacs-query-functions -After asking the standard questions, @code{save-buffers-kill-emacs} -calls the functions in the list @code{kill-emacs-query-functions}, in -order of appearance, with no arguments. These functions can ask for -additional confirmation from the user. If any of them returns -@code{nil}, @code{save-buffers-kill-emacs} does not kill Emacs, and -does not run the remaining functions in this hook. Calling -@code{kill-emacs} directly does not run this hook. +@defvar kill-emacs-hook +This normal hook is run by @code{kill-emacs}, before it kills Emacs. + +Because @code{kill-emacs} can be called in situations where user +interaction is impossible (e.g. when the terminal is disconnected), +functions on this hook should not attempt to interact with the user. +If you want to interact with the user when Emacs is shutting down, use +@code{kill-emacs-query-functions}, described below. @end defvar -@defvar kill-emacs-hook -This variable is a normal hook; once @code{save-buffers-kill-emacs} is -finished with all file saving and confirmation, it calls -@code{kill-emacs} which runs the functions in this hook. - -@code{kill-emacs} may be invoked directly (that is not via -@code{save-buffers-kill-emacs}) if the terminal is disconnected, or in -similar situations where interaction with the user is not possible. -Thus, if your hook needs to interact with the user, put it on -@code{kill-emacs-query-functions}; if it needs to run regardless of -how Emacs is killed, put it on @code{kill-emacs-hook}. + When Emacs is killed, all the information in the Emacs process, +aside from files that have been saved, is lost. Because killing Emacs +inadvertently can lose a lot of work, the +@code{save-buffers-kill-terminal} command queries for confirmation if +you have buffers that need saving or subprocesses that are running. +It also runs the abnormal hook @code{kill-emacs-query-functions}: + +@defvar kill-emacs-query-functions +When @code{save-buffers-kill-terminal} is killing Emacs, it calls the +functions in this hook, after asking the standard questions and before +calling @code{kill-emacs}. The functions are called in order of +appearance, with no arguments. Each function can ask for additional +confirmation from the user. If any of them returns @code{nil}, +@code{save-buffers-kill-emacs} does not kill Emacs, and does not run +the remaining functions in this hook. Calling @code{kill-emacs} +directly does not run this hook. @end defvar @node Suspending Emacs diff --git a/etc/NEWS b/etc/NEWS index 4d5d19c2eb7..c208533b2e1 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -55,11 +55,12 @@ With it, Emacs integers typically have 62 bits, even on 32-bit machines. Type `C-u C-h t' to choose it in case your language setup doesn't automatically select it. -** Emacs can be compiled with support for the ImageMagick library. +** Emacs can be compiled with ImageMagick support. Emacs links to ImageMagick if version 6.2.8 or newer of the library is -present at build time. To disable ImageMagick support, use the -`--without-imagemagick' configure option. +present at build time. To inhibit ImageMagick, use the configure +option `--without-imagemagick' . +--- ** The standalone programs digest-doc and sorted-doc are removed. Emacs now uses Lisp commands `doc-file-to-man' and `doc-file-to-info'. @@ -153,7 +154,7 @@ If you had that set, then then you need to put in your ~/.authinfo file instead. ** Emacs server and client changes - ++++ *** New option `server-port' specifies the port on which the Emacs server should listen. +++ @@ -212,6 +213,7 @@ the variable `glyphless-char-display-control'. On character terminals, these methods are used for characters that cannot be encoded by the `terminal-coding-system'. +--- *** New input methods for Farsi: farsi and farsi-translit. ** Improved GTK integration @@ -267,10 +269,10 @@ for remote machines which support SELinux. higher-resolution time stamps. ** Changes for exiting Emacs - ++++ *** The function kill-emacs is now run upon receipt of the signals SIGTERM and SIGHUP, and upon SIGINT in batch mode. - ++++ *** kill-emacs-hook is now also run in batch mode. If you have code that adds something to kill-emacs-hook, you should consider if it is still appropriate to add it in the noninteractive case. @@ -410,9 +412,9 @@ also deletes newlines around point. ** Deletion changes *** New option `delete-active-region'. -If non-nil, C-d, [delete], and DEL delete the region if it is active -and no prefix argument is given. If set to `kill', these commands -kill instead. +If non-nil, [delete] and DEL delete the region if it is active and no +prefix argument is given. If set to `kill', these commands kill +instead. *** New command `delete-forward-char', bound to [delete]. This is meant for interactive use, and obeys `delete-active-region'. @@ -422,7 +424,7 @@ The command `delete-char' does not obey `delete-active-region'. Apart from obeying `delete-active-region', its behavior is unchanged. However, the byte compiler now warns if it is called from Lisp; you should use delete-char with a negative argument instead. - +--- *** The option `mouse-region-delete-keys' has been deleted. ** Selection changes. @@ -669,6 +671,7 @@ in the Rmail incoming message. ** shell-mode can track your cwd by reading it from your prompt. Just set shell-dir-cookie-re to an appropriate regexp. +--- ** SQL Mode enhancements. *** `sql-dialect' is an alias for `sql-product'. @@ -865,7 +868,7 @@ coordinate in the POSITION list now counts from the top of the text area, excluding any header line. Previously, it counted from the top of the header line. -** Remove obsolete name `e' (use `float-e' instead). +** Removed obsolete name `e' (use `float-e' instead). ** A backquote not followed by a space is now always treated as new-style. @@ -876,6 +879,7 @@ programmer-visible consequences. ** Passing a nil argument to a minor mode function now turns the mode ON unconditionally. ++++ ** During startup, Emacs no longer adds entries for `menu-bar-lines' and `tool-bar-lines' to `default-frame-alist' and `initial-frame-alist'. With these alist entries omitted, `make-frame' checks the value of the @@ -990,6 +994,7 @@ connection, directly or via STARTTLS. To do STARTTLS, additional parameters (`:end-of-command', `:success', `:capabilities-command') must also be supplied. ++++ ** pre/post-command-hook are not reset to nil upon error. Instead, the offending function is removed. @@ -1105,6 +1110,7 @@ the GnuTLS logging conventions. The output is in *Messages*. *** New hook `isearch-update-post-hook' that runs in `isearch-update'. ++++ ** Progress reporters can now "spin". The MIN-VALUE and MAX-VALUE arguments of `make-progress-reporter' can now be nil, or omitted. This makes a "non-numeric" reporter. Each @@ -1127,6 +1133,7 @@ as well as those in the -*- line. ** keymaps can inherit from multiple parents. ++++ ** New reader macro ## which stands for the empty symbol. This means that the empty symbol can now be read back. Also, #: by itself (when not immediately followed by a possible symbol character) stands for -- 2.39.2