[Emacs-diffs] /srv/bzr/emacs/emacs-23 r99783: Document Emacs 23.2 changes.

[Chong Yidong]

------------------------------------------------------------
revno: 99783
committer: Chong Yidong <address@hidden>
branch nick: emacs-23
timestamp: Sun 2010-04-25 17:21:51 -0400
message:
  Document Emacs 23.2 changes.
  
  * functions.texi (Obsolete Functions): Document
  set-advertised-calling-convention.
  
  * minibuf.texi (Basic Completion): Document completion-in-region.
  (Programmed Completion): Document completion-annotate-function.
  
  * commands.texi (Reading One Event): Document read-key.
  (Distinguish Interactive): Document KIND arg to
  called-interactively-p.  Delete obsolete interactive-p.
  
  * elisp.texi (Top): Update node description.
  
  * misc.texi (Printing): Document htmlfontify-buffer.
modified:
  doc/emacs/ChangeLog
  doc/emacs/misc.texi
  doc/lispref/ChangeLog
  doc/lispref/commands.texi
  doc/lispref/elisp.texi
  doc/lispref/functions.texi
  doc/lispref/minibuf.texi
  etc/NEWS

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2010-04-21 02:49:00 +0000
+++ b/doc/emacs/ChangeLog       2010-04-25 21:21:51 +0000
@@ -1,3 +1,7 @@
+2010-04-25  Chong Yidong  <address@hidden>
+
+       * misc.texi (Printing): Document htmlfontify-buffer.
+
 2010-04-21  Glenn Morris  <address@hidden>
 
        * calendar.texi (Displaying the Diary, Format of Diary File):

=== modified file 'doc/emacs/misc.texi'
--- a/doc/emacs/misc.texi       2010-04-18 23:02:16 +0000
+++ b/doc/emacs/misc.texi       2010-04-25 21:21:51 +0000
@@ -1701,8 +1701,14 @@
   Emacs provides commands for printing hard copies of either an entire
 buffer or just part of one, with or without page headers.  You can
 invoke the printing commands directly, as detailed in the following
-section, or using the @samp{File} menu on the menu bar.  See also the
-hardcopy commands of Dired (@pxref{Misc File Ops}) and the diary
+section, or using the @samp{File} menu on the menu bar.
+
address@hidden htmlfontify-buffer
+  Aside from the commands described in this section, you can also
+``print'' an Emacs buffer to HTML with @kbd{M-x htmlfontify-buffer}.
+This command converts the current buffer to a HTML file, replacing
+Emacs faces with CSS-based markup.  In addition, see the hardcopy
+commands of Dired (@pxref{Misc File Ops}) and the diary
 (@pxref{Displaying the Diary}).
 
 @table @kbd

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2010-04-14 22:41:21 +0000
+++ b/doc/lispref/ChangeLog     2010-04-25 21:21:51 +0000
@@ -1,3 +1,17 @@
+2010-04-25  Chong Yidong  <address@hidden>
+
+       * functions.texi (Obsolete Functions): Document
+       set-advertised-calling-convention.
+
+       * minibuf.texi (Basic Completion): Document completion-in-region.
+       (Programmed Completion): Document completion-annotate-function.
+
+       * commands.texi (Reading One Event): Document read-key.
+       (Distinguish Interactive): Document KIND arg to
+       called-interactively-p.  Delete obsolete interactive-p.
+
+       * elisp.texi (Top): Update node description.
+
 2010-04-14  Juri Linkov  <address@hidden>
 
        Fix @deffn without category.

=== modified file 'doc/lispref/commands.texi'
--- a/doc/lispref/commands.texi 2010-01-13 08:35:10 +0000
+++ b/doc/lispref/commands.texi 2010-04-25 21:21:51 +0000
@@ -696,71 +696,67 @@
 because it allows callers to say ``treat this call as interactive.''
 But you can also do the job by testing @code{called-interactively-p}.
 
address@hidden called-interactively-p
address@hidden called-interactively-p kind
 This function returns @code{t} when the calling function was called
 using @code{call-interactively}.
 
-If the containing function was called by Lisp evaluation (or with
address@hidden or @code{funcall}), then it was not called interactively.
+The argument @var{kind} should be either the symbol @code{interactive}
+or the symbol @code{any}.  If it is @code{interactive}, then
address@hidden returns @code{t} only if the call was
+made directly by the user---e.g., if the user typed a key sequence
+bound to the calling function, but @emph{not} if the user ran a
+keyboard macro that called the function (@pxref{Keyboard Macros}).  If
address@hidden is @code{any}, @code{called-interactively-p} returns
address@hidden for any kind of interactive call, including keyboard macros.
+
+If in doubt, use @code{any}; the only known proper use of
address@hidden is if you need to decide whether to display a
+helpful message while a function is running.
+
+A function is never considered to be called interactively if it was
+called via Lisp evaluation (or with @code{apply} or @code{funcall}).
 @end defun
 
-   Here's an example of using @code{called-interactively-p}:
address@hidden
+Here is an example of using @code{called-interactively-p}:
 
 @example
 @group
 (defun foo ()
   (interactive)
-  (when (called-interactively-p)
-    (message "foo"))
-  'haha)
-     @result{} foo
+  (when (called-interactively-p 'any)
+    (message "Interactive!")
+    'foo-called-interactively))
 @end group
 
 @group
 ;; @r{Type @kbd{M-x foo}.}
-     @print{} foo
+     @print{} Interactive!
 @end group
 
 @group
 (foo)
-     @result{} haha
+     @result{} nil
 @end group
 @end example
 
-  Here is another example that contrasts direct and indirect
-calls to @code{called-interactively-p}.
address@hidden
+Here is another example that contrasts direct and indirect calls to
address@hidden
 
 @example
 @group
 (defun bar ()
   (interactive)
-  (setq foobar (list (foo) (called-interactively-p))))
-     @result{} bar
+  (message "%s" (list (foo) (called-interactively-p 'any))))
 @end group
 
 @group
 ;; @r{Type @kbd{M-x bar}.}
-;; @r{This does not display a message.}
address@hidden group
-
address@hidden
-foobar
-     @result{} (nil t)
+     @print{} (nil t)
 @end group
 @end example
 
-  If you want to treat commands run in keyboard macros just like calls
-from Lisp programs, test @code{interactive-p} instead of
address@hidden
-
address@hidden interactive-p
-This function returns @code{t} if the containing function (the one
-whose code includes the call to @code{interactive-p}) was called in
-direct response to user input.  This means that it was called with the
-function @code{call-interactively}, and that a keyboard macro is
-not running, and that Emacs is not running in batch mode.
address@hidden defun
-
 @node Command Loop Info
 @comment  node-name,  next,  previous,  up
 @section Information from the Command Loop
@@ -2309,10 +2305,8 @@
 @cindex reading a single event
 @cindex event, reading only one
 
-  The lowest level functions for command input are those that read a
-single event.
-
-None of the three functions below suppresses quitting.
+  The lowest level functions for command input are @code{read-event},
address@hidden, and @code{read-char-exclusive}.
 
 @defun read-event &optional prompt inherit-input-method seconds
 This function reads and returns the next event of command input, waiting
@@ -2409,11 +2403,31 @@
 gets a character.  The arguments work as in @code{read-event}.
 @end defun
 
+  None of the above functions suppress quitting.
+
 @defvar num-nonmacro-input-events
 This variable holds the total number of input events received so far
 from the terminal---not counting those generated by keyboard macros.
 @end defvar
 
+  We emphasize that, unlike @code{read-key-sequence}, the functions
address@hidden, @code{read-char}, and @code{read-char-exclusive} do
+not perform the translations described in @ref{Translation Keymaps}.
+If you wish to read a single key taking these translations into
+account, use the function @code{read-key}:
+
address@hidden read-key &optional prompt
+This function reads a single key.  It is ``intermediate'' between
address@hidden and @code{read-event}.  Unlike the former, it
+reads a single key, not a key sequence.  Unlike the latter, it does
+not return a raw event, but decodes and translates the user input
+according to @code{input-decode-map}, @code{local-function-key-map},
+and @code{key-translation-map} (@pxref{Translation Keymaps}).
+
+The argument @var{prompt} is either a string to be displayed in the
+echo area as a prompt, or @code{nil}, meaning not to display a prompt.
address@hidden defun
+
 @node Event Mod
 @subsection Modifying and Translating Input Events
 

=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi    2010-04-20 01:29:37 +0000
+++ b/doc/lispref/elisp.texi    2010-04-25 21:21:51 +0000
@@ -649,7 +649,6 @@
 Completion
 
 * Basic Completion::        Low-level functions for completing strings.
-                              (These are too low level to use the minibuffer.)
 * Minibuffer Completion::   Invoking the minibuffer with completion.
 * Completion Commands::     Minibuffer commands that do completion.
 * High-Level Completion::   Convenient special cases of completion

=== modified file 'doc/lispref/functions.texi'
--- a/doc/lispref/functions.texi        2010-01-13 08:35:10 +0000
+++ b/doc/lispref/functions.texi        2010-04-25 21:21:51 +0000
@@ -1197,7 +1197,7 @@
 @end defun
 
 You can define a function as an alias and declare it obsolete at the
-same time using the macro @code{define-obsolete-function-alias}.
+same time using the macro @code{define-obsolete-function-alias}:
 
 @defmac define-obsolete-function-alias obsolete-name current-name &optional 
when docstring
 This macro marks the function @var{obsolete-name} obsolete and also
@@ -1210,6 +1210,33 @@
 @end example
 @end defmac
 
+In addition, you can mark a certain a particular calling convention
+for a function as obsolete:
+
address@hidden set-advertised-calling-convention function signature
+This function specifies the argument list @var{signature} as the
+correct way to call @var{function}.  This causes the Emacs byte
+compiler to issue a warning whenever it comes across an Emacs Lisp
+program that calls @var{function} any other way (however, it will
+still allow the code to be byte compiled).
+
+For instance, in old versions of Emacs the @code{sit-for} function
+accepted three arguments, like this
+
address@hidden
+  (sit-for seconds milliseconds nodisp)
address@hidden smallexample
+
+However, calling @code{sit-for} this way is considered obsolete
+(@pxref{Waiting}).  The old calling convention is deprecated like
+this:
+
address@hidden
+(set-advertised-calling-convention
+  'sit-for '(seconds &optional nodisp))
address@hidden smallexample
address@hidden defun
+
 @node Inline Functions
 @section Inline Functions
 @cindex inline functions

=== modified file 'doc/lispref/minibuf.texi'
--- a/doc/lispref/minibuf.texi  2010-01-13 08:35:10 +0000
+++ b/doc/lispref/minibuf.texi  2010-04-25 21:21:51 +0000
@@ -626,7 +626,6 @@
 
 @menu
 * Basic Completion::       Low-level functions for completing strings.
-                             (These are too low level to use the minibuffer.)
 * Minibuffer Completion::  Invoking the minibuffer with completion.
 * Completion Commands::    Minibuffer commands that do completion.
 * High-Level Completion::  Convenient special cases of completion
@@ -640,31 +639,23 @@
 @node Basic Completion
 @subsection Basic Completion Functions
 
-  The completion functions @code{try-completion},
address@hidden and @code{test-completion} have nothing in
-themselves to do with minibuffers.  We describe them in this chapter
-so as to keep them near the higher-level completion features that do
-use the minibuffer.
-
-  If you store a completion alist in a variable, you should mark the
-variable as ``risky'' with a address@hidden
address@hidden property.
+  The following completion functions have nothing in themselves to do
+with minibuffers.  We describe them here to keep them near the
+higher-level completion features that do use the minibuffer.
 
 @defun try-completion string collection &optional predicate
 This function returns the longest common substring of all possible
 completions of @var{string} in @var{collection}.  The value of
 @var{collection} must be a list of strings or symbols, an alist, an
-obarray, a hash table, or a function that implements a virtual set of
-strings (see below).
+obarray, a hash table, or a completion function (@pxref{Programmed
+Completion}).
 
 Completion compares @var{string} against each of the permissible
-completions specified by @var{collection}; if the beginning of the
-permissible completion equals @var{string}, it matches.  If no permissible
-completions match, @code{try-completion} returns @code{nil}.  If only
-one permissible completion matches, and the match is exact, then
address@hidden returns @code{t}.  Otherwise, the value is the
-longest initial sequence common to all the permissible completions that
-match.
+completions specified by @var{collection}.  If no permissible
+completions match, @code{try-completion} returns @code{nil}.  If there
+is just one matching completion, and the match is exact, it returns
address@hidden  Otherwise, it returns the longest initial sequence common
+to all possible matching completions.
 
 If @var{collection} is an alist (@pxref{Association Lists}), the
 permissible completions are the elements of the alist that are either
@@ -688,13 +679,13 @@
 If @var{collection} is a hash table, then the keys that are strings
 are the possible completions.  Other keys are ignored.
 
-You can also use a symbol that is a function as @var{collection}.  Then
-the function is solely responsible for performing completion;
+You can also use a symbol that is a function as @var{collection}.
+Then the function is solely responsible for performing completion;
 @code{try-completion} returns whatever this function returns.  The
 function is called with three arguments: @var{string}, @var{predicate}
-and @code{nil}.  (The reason for the third argument is so that the same
+and @code{nil} (the reason for the third argument is so that the same
 function can be used in @code{all-completions} and do the appropriate
-thing in either case.)  @xref{Programmed Completion}.
+thing in either case).  @xref{Programmed Completion}.
 
 If the argument @var{predicate} is address@hidden, then it must be a
 function of one argument, unless @var{collection} is a hash table, in
@@ -823,6 +814,10 @@
 it returns, @code{test-completion} returns in turn.
 @end defun
 
+If you store a completion alist in a variable, you should mark the
+variable as ``risky'' with a address@hidden
address@hidden property.  @xref{File Local Variables}.
+
 @defvar completion-ignore-case
 If the value of this variable is address@hidden, Emacs does not
 consider case significant in completion.  Note, however, that this
@@ -855,6 +850,23 @@
 @end smallexample
 @end defmac
 
+The function @code{completion-in-region} provides a convenient way to
+perform completion on an arbitrary stretch of text in an Emacs buffer:
+
address@hidden completion-in-region start end collection &optional predicate
+This function completes the text in the current buffer between the
+positions @var{start} and @var{end}, using @var{collection}.  The
+argument @var{collection} has the same meaning as in
address@hidden (@pxref{Basic Completion}).
+
+This function inserts the completion text directly into the current
+buffer.  Unlike @code{completing-read} (@pxref{Minibuffer
+Completion}), it does not activate the minibuffer.
+
+For this function to work, point must be somewhere between @var{start}
+and @var{end}.
address@hidden defun
+
 @node Minibuffer Completion
 @subsection Completion and the Minibuffer
 @cindex minibuffer completion
@@ -869,12 +881,12 @@
 @var{prompt}, which must be a string.
 
 The actual completion is done by passing @var{collection} and
address@hidden to the function @code{try-completion}.  This happens
-in certain commands bound in the local keymaps used for completion.
-Some of these commands also call @code{test-completion}.  Thus, if
address@hidden is address@hidden, it should be compatible with
address@hidden and @code{completion-ignore-case}.  @xref{Definition
-of test-completion}.
address@hidden to the function @code{try-completion} (@pxref{Basic
+Completion}).  This happens in certain commands bound in the local
+keymaps used for completion.  Some of these commands also call
address@hidden  Thus, if @var{predicate} is address@hidden,
+it should be compatible with @var{collection} and
address@hidden  @xref{Definition of test-completion}.
 
 The value of the optional argument @var{require-match} determines how
 the user may exit the minibuffer:
@@ -1603,8 +1615,10 @@
 
   Sometimes it is not possible to create an alist or an obarray
 containing all the intended possible completions.  In such a case, you
-can supply your own function to compute the completion of a given string.
-This is called @dfn{programmed completion}.
+can supply your own function to compute the completion of a given
+string.  This is called @dfn{programmed completion}.  Emacs uses
+programmed completion when completing file names (@pxref{File Name
+Completion}).
 
   To use this feature, pass a symbol with a function definition as the
 @var{collection} argument to @code{completing-read}.  The function
@@ -1659,9 +1673,6 @@
 function.  So you must arrange for any function you wish to use for
 completion to be encapsulated in a symbol.
 
-  Emacs uses programmed completion when completing file names.
address@hidden Name Completion}.
-
 @defun completion-table-dynamic function
 This function is a convenient way to write a function that can act as
 programmed completion function.  The argument @var{function} should be
@@ -1671,6 +1682,19 @@
 and the interface for programmed completion functions.
 @end defun
 
address@hidden completion-annotate-function
+The value of this variable, if address@hidden, should be a function
+for ``annotating'' the entries in the @samp{*Completions*} buffer.
+The function should accept a single argument, the completion string
+for an entry.  It should return an additional string to display next
+to that entry in the @samp{*Completions*} buffer, or @code{nil} if no
+additional string is to be displayed.
+
+The function can determine the collection used for the current
+completion via the variable @code{minibuffer-completion-table}
+(@pxref{Completion Commands}).
address@hidden defvar
+
 @node Yes-or-No Queries
 @section Yes-or-No Queries
 @cindex asking the user questions

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2010-04-25 06:34:03 +0000
+++ b/etc/NEWS  2010-04-25 21:21:51 +0000
@@ -437,6 +437,7 @@
 ---
 ** mpc.el is a front end for the Music Player Daemon.  Run it with M-x mpc.
 
++++
 ** htmlfontify.el turns a fontified Emacs buffer into an HTML page.
 
 +++
@@ -488,6 +489,7 @@
 ** All the default-FOO variables that hold the default value of the FOO
 variable, are now declared obsolete.
 
++++
 ** read-key is a function halfway between read-event and read-key-sequence.
 It reads a single key, but obeys input and escape sequence decoding.
 
@@ -500,18 +502,18 @@
 virtual desktops.
 
 ** Completion changes
-
+---
 *** completion-base-size is obsoleted by completion-base-position.
 This change causes a few backward incompatibilities, mostly with
 choose-completion-string-functions where the `mini-p' argument has
 been replaced by a `base-position' argument, and where the `base-size'
 argument is now always nil.
-
++++
 *** New function `completion-in-region' to use the standard completion
 facilities on a particular region of text.
 +++
 *** The 4th arg to all-completions (aka hide-spaces) is declared obsolete.
-
++++
 *** completion-annotate-function specifies how to compute annotations
 for completions displayed in *Completions*.
 
@@ -528,9 +530,11 @@
 +++
 *** New function `copy-directory', which copies a directory recursively.
 
++++
 ** called-interactively-p now takes one argument and replaces interactive-p
 which is now marked obsolete.
 
++++
 ** New function set-advertised-calling-convention makes it possible
 to obsolete arguments as well as make some arguments mandatory.