procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Document Emacs 23.2 changes.

Browse source 
* 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.
This commit is contained in:
Chong Yidong 2010-04-25 17:21:51 -04:00
parent 3b0788f68e
commit eb5ed549f4
8 changed files with 169 additions and 77 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
doc/emacs/ChangeLog
View file

@ -1,3 +1,7 @@
2010-04-25 Chong Yidong <cyd@stupidchicken.com>
* misc.texi (Printing): Document htmlfontify-buffer.
2010-04-21 Glenn Morris <rgm@gnu.org>
* calendar.texi (Displaying the Diary, Format of Diary File):

10
doc/emacs/misc.texi
View file

@ -1701,8 +1701,14 @@ process, type @kbd{M-x kill-emacs}.
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.
@findex 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

14
doc/lispref/ChangeLog
View file

@ -1,3 +1,17 @@
2010-04-25 Chong Yidong <cyd@stupidchicken.com>
* 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 <juri@jurta.org>
Fix @deffn without category.

86
doc/lispref/commands.texi
View file

@ -696,71 +696,67 @@ message when called from a keyboard macro.
because it allows callers to say ``treat this call as interactive.''
But you can also do the job by testing @code{called-interactively-p}.
@defun called-interactively-p
@defun 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
@code{apply} 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
@code{called-interactively-p} 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
@var{kind} is @code{any}, @code{called-interactively-p} returns
@code{t} for any kind of interactive call, including keyboard macros.
If in doubt, use @code{any}; the only known proper use of
@code{interactive} 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}:
@noindent
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}.
@noindent
Here is another example that contrasts direct and indirect calls to
@code{called-interactively-p}.
@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.}
@end group
@group
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
@code{called-interactively-p}.
@defun 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.
@end defun
@node Command Loop Info
@comment node-name, next, previous, up
@section Information from the Command Loop
@ -2309,10 +2305,8 @@ and key sequences read from keyboard macros being executed.
@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},
@code{read-char}, 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 @@ user generates an event which is not a character,
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
@code{read-event}, @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}:
@defun read-key &optional prompt
This function reads a single key. It is ``intermediate'' between
@code{read-key-sequence} 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.
@end defun
@node Event Mod
@subsection Modifying and Translating Input Events

1
doc/lispref/elisp.texi
View file

@ -649,7 +649,6 @@ Minibuffers
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

29
doc/lispref/functions.texi
View file

@ -1197,7 +1197,7 @@ was first made obsolete---for example, a date or a release number.
@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 @@ equivalent to the following:
@end example
@end defmac
In addition, you can mark a certain a particular calling convention
for a function as obsolete:
@defun 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
@smallexample
(sit-for seconds milliseconds nodisp)
@end smallexample
However, calling @code{sit-for} this way is considered obsolete
(@pxref{Waiting}). The old calling convention is deprecated like
this:
@smallexample
(set-advertised-calling-convention
'sit-for '(seconds &optional nodisp))
@end smallexample
@end defun
@node Inline Functions
@section Inline Functions
@cindex inline functions

92
doc/lispref/minibuf.texi
View file

@ -626,7 +626,6 @@ for reading certain kinds of names with completion.
@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 @@ for reading certain kinds of names with completion.
@node Basic Completion
@subsection Basic Completion Functions
The completion functions @code{try-completion},
@code{all-completions} 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 non-@code{nil}
@code{risky-local-variable} 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
@code{try-completion} 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
@code{t}. 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 @@ Also, you cannot intern a given symbol in more than one obarray.
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 non-@code{nil}, then it must be a
function of one argument, unless @var{collection} is a hash table, in
@ -823,6 +814,10 @@ the values @var{string}, @var{predicate} and @code{lambda}; whatever
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 non-@code{nil}
@code{risky-local-variable} property. @xref{File Local Variables}.
@defvar completion-ignore-case
If the value of this variable is non-@code{nil}, Emacs does not
consider case significant in completion. Note, however, that this
@ -855,6 +850,23 @@ Here is an example of use:
@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:
@defun 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
@code{try-completion} (@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}.
@end defun
@node Minibuffer Completion
@subsection Completion and the Minibuffer
@cindex minibuffer completion
@ -869,12 +881,12 @@ providing completion. It activates the minibuffer with prompt
@var{prompt}, which must be a string.
The actual completion is done by passing @var{collection} and
@var{predicate} 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
@var{predicate} is non-@code{nil}, it should be compatible with
@var{collection} and @code{completion-ignore-case}. @xref{Definition
of test-completion}.
@var{predicate} 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
@code{test-completion}. Thus, if @var{predicate} is non-@code{nil},
it should be compatible with @var{collection} and
@code{completion-ignore-case}. @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 @@ which performs completion according to the rules used in Emacs 21; and
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 @@ unreliable to treat one differently just because it is also a possible
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.
@xref{File 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 @@ possible completions of it. You can think of
and the interface for programmed completion functions.
@end defun
@defvar completion-annotate-function
The value of this variable, if non-@code{nil}, 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}).
@end defvar
@node Yes-or-No Queries
@section Yes-or-No Queries
@cindex asking the user questions

10
etc/NEWS
View file

@ -437,6 +437,7 @@ System (CLOS). It is used by the other CEDET packages.
---
** 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 @@ key binding to toggle image display.
** 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 @@ This maximizes the frame.
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 @@ any more.
+++
*** 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.