Commit ddb54206 authored by Chong Yidong's avatar Chong Yidong
Browse files

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.
parent 7a1ff57f
2011-08-28 Chong Yidong <cyd@stupidchicken.com>
* misc.texi (emacsclient Options): Document server-port.
2011-08-27 Eli Zaretskii <eliz@gnu.org>
* frames.texi (Frame Commands): Advise setting focus-follows-mouse
......
......@@ -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.
......
......@@ -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
......
2011-08-28 Chong Yidong <cyd@stupidchicken.com>
* 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 <eliz@gnu.org>
* display.texi (Specified Space): Mention that `space' specs
......
......@@ -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.
......
......@@ -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}.
......
......@@ -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
......
......@@ -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
......
......@@ -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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment