[Emacs-diffs] /srv/bzr/emacs/trunk r105600: Update manuals for some Emacs 24 changes.

[Chong Yidong]

------------------------------------------------------------
revno: 105600
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sun 2011-08-28 14:49:59 -0400
message:
  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.
modified:
  doc/emacs/ChangeLog
  doc/emacs/emacs.texi
  doc/emacs/misc.texi
  doc/lispref/ChangeLog
  doc/lispref/display.texi
  doc/lispref/frames.texi
  doc/lispref/objects.texi
  doc/lispref/os.texi
  etc/NEWS

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2011-08-27 12:10:24 +0000
+++ b/doc/emacs/ChangeLog       2011-08-28 18:49:59 +0000
@@ -1,3 +1,7 @@
+2011-08-28  Chong Yidong  <address@hidden>
+
+       * misc.texi (emacsclient Options): Document server-port.
+
 2011-08-27  Eli Zaretskii  <address@hidden>
 
        * frames.texi (Frame Commands): Advise setting focus-follows-mouse

=== modified file 'doc/emacs/emacs.texi'
--- a/doc/emacs/emacs.texi      2011-08-26 15:48:19 +0000
+++ b/doc/emacs/emacs.texi      2011-08-28 18:49:59 +0000
@@ -1054,6 +1054,12 @@
 * 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.

=== modified file 'doc/emacs/misc.texi'
--- a/doc/emacs/misc.texi       2011-08-26 15:48:19 +0000
+++ b/doc/emacs/misc.texi       2011-08-28 18:49:59 +0000
@@ -1596,6 +1596,11 @@
 (One convenient way to do the latter is to put the server file on a
 networked file system such as NFS.)
 
address@hidden server-port
+  When the Emacs server is using TCP, the variable @code{server-port}
+determines the port number to listen on; the default value,
address@hidden, means to choose a random port when the server starts.
+
 @item -n
 @itemx --no-wait
 Let @command{emacsclient} exit immediately, instead of waiting until

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2011-08-25 10:45:33 +0000
+++ b/doc/lispref/ChangeLog     2011-08-28 18:49:59 +0000
@@ -1,3 +1,16 @@
+2011-08-28  Chong Yidong  <address@hidden>
+
+       * 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  <address@hidden>
 
        * display.texi (Specified Space): Mention that `space' specs

=== modified file 'doc/lispref/display.texi'
--- a/doc/lispref/display.texi  2011-08-25 10:45:33 +0000
+++ b/doc/lispref/display.texi  2011-08-28 18:49:59 +0000
@@ -367,10 +367,9 @@
   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 @@
   (progress-reporter-done progress-reporter))
 @end smallexample
 
address@hidden 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.
address@hidden 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 @@
 on a filename, for instance, use @code{format} before calling this
 function.
 
address@hidden 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
address@hidden  If you create progress reporter when some part of
-the operation has already been completed, then specify
address@hidden 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.
address@hidden 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
address@hidden 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.
address@hidden should be greater than @var{min-value}.
+
+Alternatively, you can set @var{min-value} and @var{max-value} to
address@hidden  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.

=== modified file 'doc/lispref/frames.texi'
--- a/doc/lispref/frames.texi   2011-07-12 17:33:18 +0000
+++ b/doc/lispref/frames.texi   2011-08-28 18:49:59 +0000
@@ -695,20 +695,19 @@
 precise width by specifying that width as a negative integer.  If both
 widths are negative, only the left fringe gets the specified width.
 
address@hidden menu-bar-lines, a frame parameter
address@hidden 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.
address@hidden Bars,,,emacs, The GNU Emacs Manual}.
 
address@hidden tool-bar-lines, a frame parameter
address@hidden 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}.
 
address@hidden tool-bar-position, a frame parameter
address@hidden 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}.

=== modified file 'doc/lispref/objects.texi'
--- a/doc/lispref/objects.texi  2011-07-13 15:07:57 +0000
+++ b/doc/lispref/objects.texi  2011-08-28 18:49:59 +0000
@@ -597,6 +597,7 @@
 @end group
 @end example
 
address@hidden @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 @@
 @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,
address@hidden:@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

=== modified file 'doc/lispref/os.texi'
--- a/doc/lispref/os.texi       2011-08-08 16:06:34 +0000
+++ b/doc/lispref/os.texi       2011-08-28 18:49:59 +0000
@@ -544,10 +544,11 @@
 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 @@
 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
address@hidden, the higher level function from which
address@hidden is usually called.
address@hidden SIGTERM
address@hidden SIGHUP
address@hidden SIGINT
address@hidden 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
address@hidden or @code{SIGHUP} operating system signal (e.g. when the
+controlling terminal is disconnected), or if it receives a
address@hidden signal while running in batch mode (@pxref{Batch Mode}).
+
address@hidden 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
address@hidden, described below.
address@hidden defvar
+
+  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
address@hidden 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
-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
address@hidden, @code{save-buffers-kill-emacs} does not kill Emacs, and
-does not run the remaining functions in this hook.  Calling
address@hidden directly does not run this hook.
address@hidden defvar
-
address@hidden 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
address@hidden which runs the functions in this hook.
-
address@hidden may be invoked directly (that is not via
address@hidden) 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
address@hidden; if it needs to run regardless of
-how Emacs is killed, put it on @code{kill-emacs-hook}.
+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},
address@hidden 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

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2011-08-27 08:36:56 +0000
+++ b/etc/NEWS  2011-08-28 18:49:59 +0000
@@ -55,11 +55,12 @@
 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 @@
 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 @@
 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 @@
 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 @@
 ** 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 @@
 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 @@
 ** 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 @@
 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 @@
 ** 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 @@
 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 @@
 
 *** 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 @@
 
 ** 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