mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2025-12-15 10:30:25 -08:00
Code Issues Projects Releases Wiki Activity

Merge from emacs-24; up to 2012-11-08T14:54:03Z!monnier@iro.umontreal.ca

Browse source
This commit is contained in:
Glenn Morris 2012-11-10 15:13:33 -08:00
commit 6baf66d53b
41 changed files with 1804 additions and 1005 deletions
Download patch file Download diff file Expand all files Collapse all files

43
doc/emacs/ChangeLog
View file

@ -1,3 +1,46 @@
2012-11-10 Glenn Morris <rgm@gnu.org>
* misc.texi (Terminal emulator): Rename `term-face' to `term'.
* emacs.texi (Acknowledgments): Add profiler author.
* ack.texi (Acknowledgments): Add some recent contributions.
2012-11-10 Chong Yidong <cyd@gnu.org>
* files.texi (Diff Mode): Doc fixes for
diff-delete-trailing-whitespace (Bug#12831).
* trouble.texi (Crashing): Copyedits.
2012-11-10 Glenn Morris <rgm@gnu.org>
* files.texi (Diff Mode): Trailing whitespace updates.
2012-11-10 Chong Yidong <cyd@gnu.org>
* misc.texi (Terminal emulator): Document Term mode faces.
* mini.texi (Basic Minibuffer): New node. Document
minibuffer-electric-default-mode.
* display.texi (Visual Line Mode): Fix index entry.
* buffers.texi (Several Buffers): List Buffer Menu command anmes,
and index the keybindings. Document tabulated-list-sort.
(Kill Buffer): Capitalize Buffer Menu.
* trouble.texi (Memory Full): Capitalize Buffer Menu.
2012-11-10 Eli Zaretskii <eliz@gnu.org>
* display.texi (Auto Scrolling): Clarify that scroll-step is
ignored when scroll-conservatively is set to a non-zero value.
(Bug#12801)
2012-11-10 Chong Yidong <cyd@gnu.org>
* dired.texi (Dired Updating): Doc fix (Bug#11744).
2012-10-30 Michael Albinus <michael.albinus@gmx.de>
* trouble.texi (Known Problems): Mention command `debbugs-gnu-usertags'.

8
doc/emacs/ack.texi
View file

@ -244,8 +244,9 @@ files as ``thumbnails''.
@item
Julien Danjou wrote an implementation of ``Desktop Notifications''
(@file{notifications.el}); and @file{color.el}, a library for general
color manipulation. He also made various contributions to Gnus.
(@file{notifications.el}, and related packages for ERC and Gnus);
and @file{color.el}, a library for general color manipulation.
He also made various contributions to Gnus.
@item
Vivek Dasmohapatra wrote @file{htmlfontify.el}, to convert a buffer or
@ -789,6 +790,9 @@ mode-sensitive insertion of text into new files.
@item
Yukihiro Matsumoto and Nobuyoshi Nakada wrote Ruby-mode.
@item
Tomohiro Matsuyama wrote the native Elisp profiler.
@item
Thomas May wrote @file{blackbox.el}, a version of the traditional
blackbox game.

188
doc/emacs/buffers.texi
View file

@ -309,7 +309,7 @@ whose names begin with a space, which are used internally by Emacs.
To kill internal buffers as well, call @code{kill-matching-buffers}
with a prefix argument.
The buffer menu feature is also convenient for killing various
The Buffer Menu feature is also convenient for killing various
buffers. @xref{Several Buffers}.
@vindex kill-buffer-hook
@ -339,7 +339,7 @@ the Customization buffer to set the variable @code{midnight-mode} to
@node Several Buffers
@section Operating on Several Buffers
@cindex buffer menu
@cindex Buffer Menu
@table @kbd
@item M-x buffer-menu
@ -348,7 +348,7 @@ Begin editing a buffer listing all Emacs buffers.
Similar, but do it in another window.
@end table
The @dfn{buffer menu} opened by @kbd{C-x C-b} (@pxref{List Buffers})
The @dfn{Buffer Menu} opened by @kbd{C-x C-b} (@pxref{List Buffers})
does not merely list buffers. It also allows you to perform various
operations on buffers, through an interface similar to Dired
(@pxref{Dired}). You can save buffers, kill them (here called
@ -356,105 +356,168 @@ operations on buffers, through an interface similar to Dired
@findex buffer-menu
@findex buffer-menu-other-window
To use the buffer menu, type @kbd{C-x C-b} and switch to the window
To use the Buffer Menu, type @kbd{C-x C-b} and switch to the window
displaying the @file{*Buffer List*} buffer. You can also type
@kbd{M-x buffer-menu} to open the buffer menu in the selected window.
@kbd{M-x buffer-menu} to open the Buffer Menu in the selected window.
Alternatively, the command @kbd{M-x buffer-menu-other-window} opens
the buffer menu in another window, and selects that window.
the Buffer Menu in another window, and selects that window.
The buffer menu is a read-only buffer, and can be changed only
The Buffer Menu is a read-only buffer, and can be changed only
through the special commands described in this section. The usual
cursor motion commands can be used in this buffer. The
following commands apply to the buffer described on the current line:
cursor motion commands can be used in this buffer. The following
commands apply to the buffer described on the current line:
@table @kbd
@item d
Request to delete (kill) the buffer, then move down. The request
shows as a @samp{D} on the line, before the buffer name. Requested
deletions take place when you type the @kbd{x} command.
@findex Buffer-menu-delete
@kindex d @r{(Buffer Menu)}
Flag the buffer for deletion (killing), then move point to the next
line (@code{Buffer-menu-delete}). The deletion flag is indicated by
the character @samp{D} on the line, before the buffer name. The
deletion occurs only when you type the @kbd{x} command (see below).
@item C-d
Like @kbd{d} but move up afterwards instead of down.
@findex Buffer-menu-delete-backwards
@kindex C-d @r{(Buffer Menu)}
Like @kbd{d}, but move point up instead of down
(@code{Buffer-menu-delete-backwards}).
@item s
Request to save the buffer. The request shows as an @samp{S} on the
line. Requested saves take place when you type the @kbd{x} command.
You may request both saving and deletion for the same buffer.
@findex Buffer-menu-save
@kindex s @r{(Buffer Menu)}
Flag the buffer for saving (@code{Buffer-menu-save}). The save flag
is indicated by the character @samp{S} on the line, before the buffer
name. The saving occurs only when you type @kbd{x}. You may request
both saving and deletion for the same buffer.
@item x
Perform previously requested deletions and saves.
@findex Buffer-menu-execute
@kindex x @r{(Buffer Menu)}
Perform all flagged deletions and saves (@code{Buffer-menu-execute}).
@item u
Remove any request made for the current line, and move down.
@findex Buffer-menu-unmark
@kindex u @r{(Buffer Menu)}
Remove all flags from the current line, and move down
(@code{Buffer-menu-unmark}).
@item @key{DEL}
Move to previous line and remove any request made for that line.
@findex Buffer-menu-backup-unmark
@kindex DEL @r{(Buffer Menu)}
Move to the previous line and remove all flags on that line
(@code{Buffer-menu-backup-unmark}).
@end table
The @kbd{d}, @kbd{C-d}, @kbd{s} and @kbd{u} commands to add or remove
flags also move down (or up) one line. They accept a numeric argument
as a repeat count.
@noindent
The commands for adding or removing flags, @kbd{d}, @kbd{C-d}, @kbd{s}
and @kbd{u}, all accept a numeric argument as a repeat count.
These commands operate immediately on the buffer listed on the current
line:
The following commands operate immediately on the buffer listed on
the current line. They also accept a numeric argument as a repeat
count.
@table @kbd
@item ~
Mark the buffer ``unmodified''. The command @kbd{~} does this
immediately when you type it.
@findex Buffer-menu-not-modified
@kindex ~ @r{(Buffer Menu)}
Mark the buffer as unmodified (@code{Buffer-menu-not-modified}).
@xref{Save Commands}.
@item %
Toggle the buffer's read-only flag. The command @kbd{%} does
this immediately when you type it.
@findex Buffer-menu-toggle-read-only
@kindex % @r{(Buffer Menu)}
Toggle the buffer's read-only status
(@code{Buffer-menu-toggle-read-only}). @xref{Misc Buffer}.
@item t
Visit the buffer as a tags table. @xref{Select Tags Table}.
@findex Buffer-menu-visit-tags-table
@kindex % @r{(Buffer Menu)}
Visit the buffer as a tags table
(@code{Buffer-menu-visit-tags-table}). @xref{Select Tags Table}.
@end table
There are also commands to select another buffer or buffers:
The following commands are used to select another buffer or buffers:
@table @kbd
@item q
Quit the buffer menu---immediately display the most recent formerly
visible buffer in its place.
@findex quit-window
@kindex q @r{(Buffer Menu)}
Quit the Buffer Menu (@code{quit-window}). The most recent formerly
visible buffer is displayed in its place.
@item @key{RET}
@itemx f
Immediately select this line's buffer in place of the @file{*Buffer
List*} buffer.
@findex Buffer-menu-this-window
@kindex f @r{(Buffer Menu)}
@kindex RET @r{(Buffer Menu)}
Select this line's buffer, replacing the @file{*Buffer List*} buffer
in its window (@code{Buffer-menu-this-window}).
@item o
Immediately select this line's buffer in another window as if by
@kbd{C-x 4 b}, leaving @file{*Buffer List*} visible.
@findex Buffer-menu-other-window
@kindex o @r{(Buffer Menu)}
Select this line's buffer in another window, as if by @kbd{C-x 4 b},
leaving @file{*Buffer List*} visible
(@code{Buffer-menu-other-window}).
@item C-o
Immediately display this line's buffer in another window, but don't
select the window.
@findex Buffer-menu-switch-other-window
@kindex C-o @r{(Buffer Menu)}
Display this line's buffer in another window, without selecting it
(@code{Buffer-menu-switch-other-window}).
@item 1
Immediately select this line's buffer in a full-screen window.
@findex Buffer-menu-1-window
@kindex 1 @r{(Buffer Menu)}
Select this line's buffer in a full-frame window
(@code{Buffer-menu-1-window}).
@item 2
Immediately set up two windows, with this line's buffer selected in
one, and the previously current buffer (aside from the buffer
@file{*Buffer List*}) displayed in the other.
@findex Buffer-menu-2-window
@kindex 2 @r{(Buffer Menu)}
Set up two windows on the current frame, with this line's buffer
selected in one, and a previously current buffer (aside from
@file{*Buffer List*}) in the other (@code{Buffer-menu-2-window}).
@item b
Bury the buffer listed on this line.
@findex Buffer-menu-bury
@kindex b @r{(Buffer Menu)}
Bury this line's buffer (@code{Buffer-menu-bury}).
@item m
@findex Buffer-menu-mark
@kindex m @r{(Buffer Menu)}
Mark this line's buffer to be displayed in another window if you exit
with the @kbd{v} command. The request shows as a @samp{>} at the
beginning of the line. (A single buffer may not have both a delete
request and a display request.)
with the @kbd{v} command (@code{Buffer-menu-mark}). The display flag
is indicated by the character @samp{>} at the beginning of the line.
(A single buffer may not have both deletion and display flags.)
@item v
Immediately select this line's buffer, and also display in other windows
any buffers previously marked with the @kbd{m} command. If you have not
marked any buffers, this command is equivalent to @kbd{1}.
@findex Buffer-menu-select
@kindex v @r{(Buffer Menu)}
Select this line's buffer, and also display in other windows any
buffers flagged with the @kbd{m} command (@code{Buffer-menu-select}).
If you have not flagged any buffers, this command is equivalent to
@kbd{1}.
@end table
There is also a command that affects the entire buffer list:
The following commands affect the entire buffer list:
@table @kbd
@item T
Delete, or reinsert, lines for non-file buffers. This command toggles
the inclusion of such buffers in the buffer list.
@end table
@item S
@findex tabulated-list-sort
@kindex S @r{(Buffer Menu)}
Sort the Buffer Menu entries according to their values in the column
at point. With a numeric prefix argument @var{n}, sort according to
the @var{n}-th column (@code{tabulated-list-sort}).
What @code{buffer-menu} actually does is create and switch to a
suitable buffer, and turn on Buffer Menu mode in it. Everything else
described above is implemented by the special commands provided in
Buffer Menu mode. One consequence of this is that you can switch from
the @file{*Buffer List*} buffer to another Emacs buffer, and edit
there. You can reselect the @file{*Buffer List*} buffer later, to
perform the operations already requested, or you can kill it, or pay
no further attention to it.
@item T
@findex Buffer-menu-toggle-files-only
@kindex T @r{(Buffer Menu)}
Delete, or reinsert, lines for non-file buffers
@code{Buffer-menu-toggle-files-only}). This command toggles the
inclusion of such buffers in the buffer list.
@end table
Normally, the buffer @file{*Buffer List*} is not updated
automatically when buffers are created and killed; its contents are
@ -633,7 +696,6 @@ C-b}. To customize this buffer list, use the @code{bs} Custom group
@findex msb-mode
@cindex mode, MSB
@cindex MSB mode
@cindex buffer menu
@findex mouse-buffer-menu
@kindex C-Down-Mouse-1
MSB global minor mode (``MSB'' stands for ``mouse select buffer'')

18
doc/emacs/dired.texi
View file

@ -1170,17 +1170,17 @@ automatically when you revisit it, by setting the variable
@kindex k @r{(Dired)}
@findex dired-do-kill-lines
To delete the specified @emph{file lines} from the buffer---not
delete the files---type @kbd{k} (@code{dired-do-kill-lines}). Like
To delete @emph{file lines} from the buffer---without actually
deleting the files---type @kbd{k} (@code{dired-do-kill-lines}). Like
the file-operating commands, this command operates on the next @var{n}
files, or on the marked files if any; but it does not operate on the
current file as a last resort.
files, or on the marked files if any. However, it does not operate on
the current file, since otherwise mistyping @kbd{k} could be annoying.
If you use @kbd{k} with a numeric prefix argument to kill the line
for a file that is a directory, which you have inserted in the Dired
buffer as a subdirectory, it removed that subdirectory line from the
buffer as well. Typing @kbd{C-u k} on the header line for a
subdirectory also removes the subdirectory line from the Dired buffer.
If you use @kbd{k} to kill the line for a directory file which you
had inserted in the Dired buffer as a subdirectory
(@pxref{Subdirectories in Dired}), it removes the subdirectory listing
as well. Typing @kbd{C-u k} on the header line for a subdirectory
also removes the subdirectory line from the Dired buffer.
The @kbd{g} command brings back any individual lines that you have
killed in this way, but not subdirectories---you must use @kbd{i} to

28
doc/emacs/display.texi
View file

@ -221,20 +221,27 @@ visible portion of the text.
if you set @code{scroll-conservatively} to a small number @var{n},
then if you move point just a little off the screen (less than @var{n}
lines), Emacs scrolls the text just far enough to bring point back on
screen. By default, @code{scroll-conservatively} is@tie{}0. If you
set @code{scroll-conservatively} to a large number (larger than 100),
Emacs will never center point as result of scrolling, even if point
moves far away from the text previously displayed in the window. With
such a large value, Emacs will always scroll text just enough for
screen. If doing so fails to make point visible, Emacs centers point
in the window. By default, @code{scroll-conservatively} is@tie{}0.
If you set @code{scroll-conservatively} to a large number (larger than
100), Emacs will never center point as result of scrolling, even if
point moves far away from the text previously displayed in the window.
With such a large value, Emacs will always scroll text just enough for
bringing point into view, so point will end up at the top or bottom of
the window, depending on the scroll direction.
@vindex scroll-step
The variable @code{scroll-step} determines how many lines to scroll
the window when point moves off the screen. If moving by that number
of lines fails to bring point back into view, point is centered
instead. The default value is zero, which causes point to always be
centered after scrolling.
An alternative way of controlling how Emacs scrolls text is by
customizing the variable @code{scroll-step}. Its value determines how
many lines to scroll the window when point moves off the screen. If
moving by that number of lines fails to bring point back into view,
point is centered instead. The default value is zero, which causes
point to always be centered after scrolling.
Since both @code{scroll-conservatively} and @code{scroll-step}
control automatic scrolling in contradicting ways, you should set only
one of them. If you customize both, the value of
@code{scroll-conservatively} takes precedence.
@cindex aggressive scrolling
@vindex scroll-up-aggressively
@ -1493,6 +1500,7 @@ attempts to wrap the line at word boundaries near the right window
edge. This makes the text easier to read, as wrapping does not occur
in the middle of words.
@cindex mode, Visual Line
@cindex Visual Line mode
@findex visual-line-mode
@findex global-visual-line-mode

3
doc/emacs/emacs.texi
View file

@ -261,6 +261,7 @@ Basic Editing Commands
The Minibuffer
* Basic Minibuffer:: Basic usage of the minibuffer.
* Minibuffer File:: Entering file names with the minibuffer.
* Minibuffer Edit:: How to edit in the minibuffer.
* Completion:: An abbreviation facility for minibuffer input.
@ -1402,7 +1403,7 @@ Martin Lorentzon, Dave Love, Eric Ludlam, K
Lüdecke, Greg McGary, Roland McGrath, Michael McNamara, Alan Mackenzie,
Christopher J.@: Madsen, Neil M.@: Mager, Ken Manheimer, Bill Mann,
Brian Marick, Simon Marshall, Bengt Martensson, Charlie Martin,
Yukihiro Matsumoto, David Maus, Thomas May, Will Mengarini, David
Yukihiro Matsumoto, Tomohiro Matsuyama, David Maus, Thomas May, Will Mengarini, David
Megginson, Stefan Merten, Ben A.@: Mesander, Wayne Mesard, Brad
Miller, Lawrence Mitchell, Richard Mlynarik, Gerd Moellmann, Stefan
Monnier, Keith Moore, Jan Moringen, Morioka Tomohiko, Glenn Morris,

23
doc/emacs/files.texi
View file

@ -1341,7 +1341,7 @@ contents of the hunk.
You can edit a Diff mode buffer like any other buffer. (If it is
read-only, you need to make it writable first. @xref{Misc Buffer}.)
Whenever you change a hunk, Diff mode attempts to automatically
correct the line numbers in the hunk headers, to ensure that the diff
correct the line numbers in the hunk headers, to ensure that the patch
remains ``correct''. To disable automatic line number correction,
change the variable @code{diff-update-on-the-fly} to @code{nil}.
@ -1470,11 +1470,22 @@ name from the patch itself. This is useful for making log entries for
functions that are deleted by the patch.
@end table
By default, Diff mode highlights trailing whitespace on modified
lines, so that they are more obvious. This is done by enabling
Whitespace mode in the Diff buffer (@pxref{Useless Whitespace}). Diff
mode buffers are set up so that Whitespace mode avoids highlighting
trailing whitespace occurring in the diff context.
@c Trailing whitespace is NOT shown by default.
@c Emacs's dir-locals file enables this (for some reason).
@cindex trailing whitespace, in patches
@findex diff-delete-trailing-whitespace
Patches sometimes include trailing whitespace on modified lines, as
an unintentional and undesired change. There are two ways to deal
with this problem. Firstly, if you enable Whitespace mode in a Diff
buffer (@pxref{Useless Whitespace}), it automatically highlights
trailing whitespace in modified lines. Secondly, you can use the
command @kbd{M-x diff-delete-trailing-whitespace}, which searches for
trailing whitespace in the lines modified by the patch, and removes
that whitespace in both the patch and the patched source file(s).
This command does not save the modifications that it makes, so you can
decide whether to save the changes (the list of modified files is
displayed in the echo area). With a prefix argument, it tries to
modify the original source files rather than the patched source files.
@node Misc File Ops
@section Miscellaneous File Operations

70
doc/emacs/mini.texi
View file

@ -13,32 +13,8 @@ special-purpose buffer with a small amount of screen space. You can
use the usual Emacs editing commands in the minibuffer to edit the
argument text.
@cindex prompt
When the minibuffer is in use, it appears in the echo area, with a
cursor. The minibuffer starts with a @dfn{prompt} in a distinct
color, usually ending with a colon. The prompt states what kind of
input is expected, and how it will be used.
The simplest way to enter a minibuffer argument is to type the text,
then @key{RET} to submit the argument and exit the minibuffer. You
can cancel the minibuffer, and the command that wants the argument, by
typing @kbd{C-g}.
@cindex default argument
Sometimes, a @dfn{default argument} appears in the prompt, inside
parentheses before the colon. This default will be used as the
argument if you just type @key{RET}. For example, commands that read
buffer names usually show a buffer name as the default; you can type
@key{RET} to operate on that default buffer.
Since the minibuffer appears in the echo area, it can conflict with
other uses of the echo area. If an error message or an informative
message is emitted while the minibuffer is active, the message hides
the minibuffer for a few seconds, or until you type something; then
the minibuffer comes back. While the minibuffer is in use, keystrokes
do not echo.
@menu
* Basic Minibuffer:: Basic usage of the minibuffer.
* Minibuffer File:: Entering file names with the minibuffer.
* Minibuffer Edit:: How to edit in the minibuffer.
* Completion:: An abbreviation facility for minibuffer input.
@ -48,6 +24,50 @@ do not echo.
* Yes or No Prompts:: Replying yes or no in the echo area.
@end menu
@node Basic Minibuffer
@section Using the Minibuffer
@cindex prompt
When the minibuffer is in use, it appears in the echo area, with a
cursor. The minibuffer starts with a @dfn{prompt}, usually ending
with a colon. The prompt states what kind of input is expected, and
how it will be used. The prompt is highlighted using the
@code{minibuffer-prompt} face (@pxref{Faces}).
The simplest way to enter a minibuffer argument is to type the text,
then @key{RET} to submit the argument and exit the minibuffer.
Alternatively, you can type @kbd{C-g} to exit the minibuffer by
cancelling the command asking for the argument (@pxref{Quitting}).
@cindex default argument
Sometimes, the prompt shows a @dfn{default argument}, inside
parentheses before the colon. This default will be used as the
argument if you just type @key{RET}. For example, commands that read
buffer names usually show a buffer name as the default; you can type
@key{RET} to operate on that default buffer.
@cindex Minibuffer Electric Default mode
@cindex mode, Minibuffer Electric Default
@findex minibuffer-electric-default-mode
@vindex minibuffer-eldef-shorten-default
If you enable Minibuffer Electric Default mode, a global minor mode,
Emacs hides the default argument as soon as you modify the contents of
the minibuffer (since typing @key{RET} would no longer submit that
default). If you ever bring back the original minibuffer text, the
prompt again shows the default. Furthermore, if you change the
variable @code{minibuffer-eldef-shorten-default} to a non-@code{nil}
value, the default argument is displayed as @samp{[@var{default}]}
instead of @samp{(default @var{default})}, saving some screen space.
To enable this minor mode, type @kbd{M-x
minibuffer-electric-default-mode}.
Since the minibuffer appears in the echo area, it can conflict with
other uses of the echo area. If an error message or an informative
message is emitted while the minibuffer is active, the message hides
the minibuffer for a few seconds, or until you type something; then
the minibuffer comes back. While the minibuffer is in use, keystrokes
do not echo.
@node Minibuffer File
@section Minibuffers for File Names

48
doc/emacs/misc.texi
View file

@ -1186,30 +1186,39 @@ underlying shell, of course.
@subsection Emacs Terminal Emulator
@findex term
To run a subshell in a terminal emulator, use @kbd{M-x term}. This
creates (or reuses) a buffer named @file{*terminal*}, and runs a
To run a subshell in a text terminal emulator, use @kbd{M-x term}.
This creates (or reuses) a buffer named @file{*terminal*}, and runs a
subshell with input coming from your keyboard, and output going to
that buffer.
@cindex line mode @r{(terminal emulator)}
@cindex char mode @r{(terminal emulator)}
The terminal emulator uses Term mode, which has two input modes. In
line mode, Term basically acts like Shell mode (@pxref{Shell Mode}).
In char mode, each character is sent directly to the subshell, as
``terminal input''. Any ``echoing'' of your input is the
responsibility of the subshell. The sole exception is the terminal
escape character, which by default is @kbd{C-c} (@pxref{Term Mode}).
Any ``terminal output'' from the subshell goes into the buffer,
advancing point.
@dfn{line mode}, Term basically acts like Shell mode (@pxref{Shell
Mode}). In @dfn{char mode}, each character is sent directly to the
subshell, as terminal input; the sole exception is the terminal escape
character, which by default is @kbd{C-c} (@pxref{Term Mode}). Any
echoing of your input is the responsibility of the subshell; any
terminal output from the subshell goes into the buffer, advancing
point.
Some programs (such as Emacs itself) need to control the appearance
on the terminal screen in detail. They do this by sending special
control codes. The exact control codes needed vary from terminal to
terminal, but nowadays most terminals and terminal emulators
(including @code{xterm}) understand the ANSI-standard (VT100-style)
escape sequences. Term mode recognizes these escape sequences, and
handles each one appropriately, changing the buffer so that the
appearance of the window matches what it would be on a real terminal.
You can actually run Emacs inside an Emacs Term window.
of the terminal screen in detail. They do this by emitting special
control codes. Term mode recognizes and handles ANSI-standard
VT100-style escape sequences, which are accepted by most modern
terminals, including @command{xterm}. (Hence, you can actually run
Emacs inside an Emacs Term window.)
The @code{term} face specifies the default appearance of text
in the terminal emulator (the default is the same appearance as the
@code{default} face). When terminal control codes are used to change
the appearance of text, these are represented in the terminal emulator
by the faces @code{term-color-black}, @code{term-color-red},
@code{term-color-green}, @code{term-color-yellow}
@code{term-color-blue}, @code{term-color-magenta},
@code{term-color-cyan}, @code{term-color-white},
@code{term-color-underline}, and @code{term-color-bold}.
@xref{Faces}.
You can also Term mode to communicate with a device connected to a
serial port. @xref{Serial Terminal}.
@ -1224,6 +1233,9 @@ examining your input. But some shells can tell Term what the current
directory is. This is done automatically by @code{bash} version 1.15
and later.
@node Term Mode
@subsection Term Mode
@cindex Term mode

59
doc/emacs/trouble.texi
View file

@ -275,24 +275,25 @@ will disappear from the mode line. That means you can safely go on
editing in the same Emacs session.
Do not use @kbd{M-x buffer-menu} to save or kill buffers when you run
out of memory, because the buffer menu needs a fair amount of memory
out of memory, because the Buffer Menu needs a fair amount of memory
itself, and the reserve supply may not be enough.
@node Crashing
@subsection When Emacs Crashes
Emacs is not supposed to crash, but if it does, before it exits it
reports a brief summary of the crash to the standard error stream
@code{stderr}. If enabled, a crashed Emacs also generates a core dump
containing voluminous data about the crash. On many platforms you can
enable core dumps by putting the shell command @samp{ulimit -c unlimited}
into your shell startup script. The crash report and core dump can be
used when debugging the same version of Emacs on the same platform.
@cindex crash report
Emacs is not supposed to crash, but if it does, it produces a
@dfn{crash report} prior to exiting. The crash report is printed to
the standard error stream. If Emacs was started from a graphical
desktop, the standard error stream is commonly redirected to a file
such as @file{~/.xsession-errors}, so you can look for the crash
report there.
The format of the crash report depends on the platform, and some
platforms support backtraces.
Here is an example, generated on x86-64 GNU/Linux with version 2.15 of
the GNU C Library:
The format of the crash report depends on the platform. On some
platforms, such as those using the GNU C Library, the crash report
includes a @dfn{backtrace} describing the execution state prior to
crashing, which can be used to help debug the crash. Here is an
example:
@example
Fatal error 11: Segmentation fault
@ -304,25 +305,18 @@ emacs[0x4ed504]
/lib64/libpthread.so.0(read+0xe)[0x375220e08e]
emacs[0x509af6]
emacs[0x5acc26]
emacs[0x5adbfb]
emacs[0x56566b]
emacs[0x59bac3]
emacs[0x565151]
...
@dots{}
@end example
@noindent
The number @samp{11} is the system signal number that corresponds to
the problem, a segmentation fault here. The three dots at the end
indicate that Emacs suppressed further backtrace entries, in the
interest of brevity.
The hexadecimal program addresses can be useful in debugging sessions.
For example, the GDB command @samp{list *0x509af6} prints the
source-code lines corresponding to the @samp{emacs[0x509af6]} entry in
the backtrace. Or, if your system has @command{addr2line}, the
following shell command outputs a backtrace with source-code line
numbers:
The number @samp{11} is the system signal number corresponding to the
crash---in this case a segmentation fault. The hexadecimal numbers
are program addresses, which can be associated with source code lines
using a debugging tool. For example, the GDB command
@samp{list *0x509af6} prints the source-code lines corresponding to
the @samp{emacs[0x509af6]} entry. If your system has the
@command{addr2line} utility, the following shell command outputs a
backtrace with source-code line numbers:
@example
sed -n 's/.*\[\(.*\)]$/\1/p' @var{backtrace} |
@ -334,6 +328,15 @@ Here, @var{backtrace} is the name of a text file containing a copy of
the backtrace, and @var{bindir} is the name of the directory that
contains the Emacs executable.
@cindex core dump
Optionally, Emacs can generate a @dfn{core dump} when it crashes. A
core dump is a file containing voluminous data about the state of the
program prior to the crash, usually examined by loading it into a
debugger such as GDB. On many platforms, core dumps are disabled by
default, and you must explicitly enable them by running the shell
command @samp{ulimit -c unlimited} (e.g.@: in your shell startup
script).
@node After a Crash
@subsection Recovery After a Crash

36
doc/lispref/ChangeLog
View file

@ -1,3 +1,39 @@
2012-11-10 Martin Rudalics <rudalics@gmx.at>
* elisp.texi (Top): Add Recombining Windows to menu.
* windows.texi (Recombining Windows): New subsection.
(Splitting Windows): Rewrite text on handling of window
combinations and move it to new subsection.
2012-11-10 Chong Yidong <cyd@gnu.org>
* searching.texi (Replacing Match): Document \? in replace-match.
* variables.texi (Creating Buffer-Local): Document setq-local and
defvar-local.
(Setting Generalized Variables): Arrange table alphabetically.
* lists.texi (List Elements, List Variables): Clarify descriptions
of push and pop for generalized variables.
* edebug.texi (Specification List): setf is no longer CL-only.
2012-11-10 Glenn Morris <rgm@gnu.org>
* variables.texi (Adding Generalized Variables):
Update description of FIX-RETURN expansion.
* variables.texi (Setting Generalized Variables):
Split most of previous contents into this subsection.
(Adding Generalized Variables): New subsection.
Move note on lack of setf functions here from misc/cl.texi.
* elisp.texi: Add Generalized Variables subsections to detailed menu.
2012-11-10 Chong Yidong <cyd@gnu.org>
* frames.texi (Initial Parameters): Doc fix (Bug#12144).
2012-11-08 Michael Albinus <michael.albinus@gmx.de>
* os.texi (Notifications): Update descriptions of

4
doc/lispref/edebug.texi
View file

@ -1211,9 +1211,7 @@ A single unevaluated Lisp object, which is not instrumented.
A single evaluated expression, which is instrumented.
@item place
@c I can't see that this index entry is useful without any explanation.
@c @findex edebug-unwrap
A place to store a value, as in the Common Lisp @code{setf} construct.
A generalized variable. @xref{Generalized Variables}.
@item body
Short for @code{&rest form}. See @code{&rest} below.

7
doc/lispref/elisp.texi
View file

@ -502,6 +502,11 @@ Buffer-Local Variables
* Default Value:: The default value is seen in buffers
that don't have their own buffer-local values.
Generalized Variables
* Setting Generalized Variables:: The @code{setf} macro.
* Adding Generalized Variables:: Defining new @code{setf} forms.
Functions
* What Is a Function:: Lisp functions vs. primitives; terminology.
@ -996,6 +1001,8 @@ Windows
* Resizing Windows:: Changing the sizes of windows.
* Splitting Windows:: Splitting one window into two windows.
* Deleting Windows:: Deleting a window gives its space to other windows.
* Recombining Windows:: Preserving the frame layout when splitting and
deleting windows.
* Selecting Windows:: The selected window is the one that you edit in.
* Cyclic Window Ordering:: Moving around the existing windows.
* Buffers and Windows:: Each window displays the contents of a buffer.

14
doc/lispref/frames.texi
View file

@ -419,16 +419,16 @@ the initial frame, specify the same parameters in
@code{initial-frame-alist} with values that match the X resources.
@end defopt
If these parameters specify a separate @dfn{minibuffer-only frame} with
@code{(minibuffer . nil)}, and you have not created one, Emacs creates
one for you.
@cindex minibuffer-only frame
If these parameters include @code{(minibuffer . nil)}, that indicates
that the initial frame should have no minibuffer. In this case, Emacs
creates a separate @dfn{minibuffer-only frame} as well.
@defopt minibuffer-frame-alist
This variable's value is an alist of parameter values used when
creating an initial minibuffer-only frame. This is the
minibuffer-only frame that Emacs creates if @code{initial-frame-alist}
specifies a frame with no minibuffer.
creating an initial minibuffer-only frame (i.e.@: the minibuffer-only
frame that Emacs creates if @code{initial-frame-alist} specifies a
frame with no minibuffer).
@end defopt
@defopt default-frame-alist

42
doc/lispref/lists.texi
View file

@ -234,17 +234,15 @@ This is in contrast to @code{cdr}, which signals an error if
@end defun
@defmac pop listname
This macro is a way of examining the @sc{car} of a list,
and taking it off the list, all at once.
@c FIXME I don't think is a particularly good way to do it,
@c but generalized variables have not been introduced yet.
(In fact, this macro can act on generalized variables, not just lists.
@xref{Generalized Variables}.)
This macro provides a convenient way to examine the @sc{car} of a
list, and take it off the list, all at once. It operates on the list
stored in @var{listname}. It removes the first element from the list,
saves the @sc{cdr} into @var{listname}, then returns the removed
element.
It operates on the list which is stored in the symbol @var{listname}.
It removes this element from the list by setting @var{listname}
to the @sc{cdr} of its old value---but it also returns the @sc{car}
of that list, which is the element being removed.
In the simplest case, @var{listname} is an unquoted symbol naming a
list; in that case, this macro is equivalent to @w{@code{(prog1
(car listname) (setq listname (cdr listname)))}}.
@example
x
@ -255,7 +253,10 @@ x
@result{} (b c)
@end example
@noindent
More generally, @var{listname} can be a generalized variable. In that
case, this macro saves into @var{listname} using @code{setf}.
@xref{Generalized Variables}.
For the @code{push} macro, which adds an element to a list,
@xref{List Variables}.
@end defmac
@ -683,13 +684,12 @@ Some examples:
These functions, and one macro, provide convenient ways
to modify a list which is stored in a variable.
@defmac push newelt listname
This macro provides an alternative way to write
@code{(setq @var{listname} (cons @var{newelt} @var{listname}))}.
@c FIXME I don't think is a particularly good way to do it,
@c but generalized variables have not been introduced yet.
(In fact, this macro can act on generalized variables, not just lists.
@xref{Generalized Variables}.)
@defmac push element listname
This macro creates a new list whose @sc{car} is @var{element} and
whose @sc{cdr} is the list specified by @var{listname}, and saves that
list in @var{listname}. In the simplest case, @var{listname} is an
unquoted symbol naming a list, and this macro is equivalent
to @w{@code{(setq @var{listname} (cons @var{element} @var{listname}))}}.
@example
(setq l '(a b))
@ -700,7 +700,11 @@ l
@result{} (c a b)
@end example
@noindent
More generally, @code{listname} can be a generalized variable. In
that case, this macro does the equivalent of @w{@code{(setf
@var{listname} (cons @var{element} @var{listname}))}}.
@xref{Generalized Variables}.
For the @code{pop} macro, which removes the first element from a list,
@xref{List Elements}.
@end defmac

27
doc/lispref/searching.texi
View file

@ -1310,22 +1310,31 @@ part of one of the following sequences:
@table @asis
@item @samp{\&}
@cindex @samp{&} in replacement
@samp{\&} stands for the entire text being replaced.
This stands for the entire text being replaced.
@item @samp{\@var{n}}
@item @samp{\@var{n}}, where @var{n} is a digit
@cindex @samp{\@var{n}} in replacement
@samp{\@var{n}}, where @var{n} is a digit, stands for the text that
matched the @var{n}th subexpression in the original regexp.
Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}.
If the @var{n}th subexpression never matched, an empty string is substituted.
This stands for the text that matched the @var{n}th subexpression in
the original regexp. Subexpressions are those expressions grouped
inside @samp{\(@dots{}\)}. If the @var{n}th subexpression never
matched, an empty string is substituted.
@item @samp{\\}
@cindex @samp{\} in replacement
@samp{\\} stands for a single @samp{\} in the replacement text.
This stands for a single @samp{\} in the replacement text.
@item @samp{\?}
This stands for itself (for compatibility with @code{replace-regexp}
and related commands; @pxref{Regexp Replacement,,, emacs, The GNU
Emacs Manual}).
@end table
These substitutions occur after case conversion, if any,
so the strings they substitute are never case-converted.
@noindent
Any other character following @samp{\} signals an error.
The substitutions performed by @samp{\&} and @samp{\@var{n}} occur
after case conversion, if any. Therefore, the strings they substitute
are never case-converted.
If @var{subexp} is non-@code{nil}, that says to replace just
subexpression number @var{subexp} of the regexp that was matched, not

119
doc/lispref/variables.texi
View file

@ -1262,6 +1262,13 @@ needed if you use the @var{local} argument to @code{add-hook} or
@code{remove-hook}.
@end deffn
@defmac setq-local variable value
This macro creates a buffer-local binding in the current buffer for
@var{variable}, and gives it the buffer-local value @var{value}. It
is equivalent to calling @code{make-local-variable} followed by
@code{setq}. @var{variable} should be an unquoted symbol.
@end defmac
@deffn Command make-variable-buffer-local variable
This function marks @var{variable} (a symbol) automatically
buffer-local, so that any subsequent attempt to set it will make it
@ -1297,6 +1304,14 @@ on having separate values in separate buffers, then using
@code{make-variable-buffer-local} can be the best solution.
@end deffn
@defmac defvar-local variable value &optional docstring
This macro defines @var{variable} as a variable with initial value
@var{value} and @var{docstring}, and marks it as automatically
buffer-local. It is equivalent to calling @code{defvar} followed by
@code{make-variable-buffer-local}. @var{variable} should be an
unquoted symbol.
@end defmac
@defun local-variable-p variable &optional buffer
This returns @code{t} if @var{variable} is buffer-local in buffer
@var{buffer} (which defaults to the current buffer); otherwise,
@ -1948,7 +1963,6 @@ Attempting to assign them any other value will result in an error:
@error{} Wrong type argument: integerp, 1000.0
@end example
@c FIXME? Not sure this is the right place for this section.
@node Generalized Variables
@section Generalized Variables
@ -1958,13 +1972,20 @@ a regular Lisp variable. But the @sc{car}s and @sc{cdr}s of lists, elements
of arrays, properties of symbols, and many other locations are also
places where Lisp values are stored.
@c FIXME? Not sure this is a useful analogy...
Generalized variables are analogous to ``lvalues'' in the C
language, where @samp{x = a[i]} gets an element from an array
and @samp{a[i] = x} stores an element using the same notation.
Just as certain forms like @code{a[i]} can be lvalues in C, there
is a set of forms that can be generalized variables in Lisp.
@menu
* Setting Generalized Variables:: The @code{setf} macro.
* Adding Generalized Variables:: Defining new @code{setf} forms.
@end menu
@node Setting Generalized Variables
@subsection The @code{setf} Macro
The @code{setf} macro is the most basic way to operate on generalized
variables. The @code{setf} form is like @code{setq}, except that it
accepts arbitrary place forms on the left side rather than just
@ -1998,14 +2019,16 @@ so there is no performance penalty for using it in compiled code.
A call to any of the following standard Lisp functions:
@smallexample
car cdr nth nthcdr
caar cadr cdar cddr
aref elt get gethash
symbol-function symbol-value symbol-plist
aref cddr symbol-function
car elt symbol-plist
caar get symbol-value
cadr gethash
cdr nth
cdar nthcdr
@end smallexample
@item
The following Emacs-specific functions are also @code{setf}-able:
A call to any of the following Emacs-specific functions:
@smallexample
default-value process-get
@ -2022,8 +2045,8 @@ process-filter
@end itemize
@noindent
Using any forms other than these in the @var{place} argument to
@code{setf} will signal an error.
@code{setf} signals an error if you pass a @var{place} form that it
does not know how to handle.
@c And for cl-lib's cl-getf.
Note that for @code{nthcdr}, the list argument of the function must
@ -2049,3 +2072,81 @@ place can be used to insert or delete at any position in a list.
The @file{cl-lib} library defines various extensions for generalized
variables, including additional @code{setf} places.
@xref{Generalized Variables,,, cl, Common Lisp Extensions}.
@node Adding Generalized Variables
@subsection Defining new @code{setf} forms
This section describes how to define new forms that @code{setf} can
operate on.
@defmac gv-define-simple-setter name setter &optional fix-return
This macro enables you to easily define @code{setf} methods for simple
cases. @var{name} is the name of a function, macro, or special form.
You can use this macro whenever @var{name} has a directly
corresponding @var{setter} function that updates it, e.g.,
@code{(gv-define-simple-setter car setcar)}.
This macro translates a call of the form
@example
(setf (@var{name} @var{args}@dots{}) @var{value})
@end example
into
@example
(@var{setter} @var{args}@dots{} @var{value})
@end example
@noindent
Such a @code{setf} call is documented to return @var{value}. This is
no problem with, e.g., @code{car} and @code{setcar}, because
@code{setcar} returns the value that it set. If your @var{setter}
function does not return @var{value}, use a non-@code{nil} value for
the @var{fix-return} argument of @code{gv-define-simple-setter}. This
expands into something equivalent to
@example
(let ((temp @var{value}))
(@var{setter} @var{args}@dots{} temp)
temp)
@end example
so ensuring that it returns the correct result.
@end defmac
@defmac gv-define-setter name arglist &rest body
This macro allows for more complex @code{setf} expansions than the
previous form. You may need to use this form, for example, if there
is no simple setter function to call, or if there is one but it
requires different arguments to the place form.
This macro expands the form
@code{(setf (@var{name} @var{args}@dots{}) @var{value})} by
first binding the @code{setf} argument forms
@code{(@var{value} @var{args}@dots{})} according to @var{arglist},
and then executing @var{body}. @var{body} should return a Lisp
form that does the assignment, and finally returns the value that was
set. An example of using this macro is:
@example
(gv-define-setter caar (val x) `(setcar (car ,x) ,val))
@end example
@end defmac
@c FIXME? Not sure what, if anything, to say about this.
@ignore
@defmac gv-define-expander name handler
This is the most general way to define a new @code{setf} expansion.
@end defmac
@end ignore
@cindex CL note---no @code{setf} functions
Common Lisp defines another way to specify the @code{setf} behavior of
a function, namely ``@code{setf} functions'', whose names are lists
@code{(setf @var{name})} rather than symbols. For example,
@code{(defun (setf foo) @dots{})} defines the function that is used
when @code{setf} is applied to @code{foo}. Emacs does not support
this. It is a compile-time error to use @code{setf} on a form that
has not already had an appropriate expansion defined. In Common Lisp,
this is not an error since the function @code{(setf @var{func})} might
be defined later.

626
doc/lispref/windows.texi
View file

@ -16,8 +16,10 @@ is displayed in windows.
* Windows and Frames:: Relating windows to the frame they appear on.
* Window Sizes:: Accessing a window's size.
* Resizing Windows:: Changing the sizes of windows.
* Splitting Windows:: Splitting one window into two windows.
* Deleting Windows:: Deleting a window gives its space to other windows.
* Splitting Windows:: Creating a new window.
* Deleting Windows:: Removing a window from its frame.
* Recombining Windows:: Preserving the frame layout when splitting and
deleting windows.
* Selecting Windows:: The selected window is the one that you edit in.
* Cyclic Window Ordering:: Moving around the existing windows.
* Buffers and Windows:: Each window displays the contents of a buffer.
@ -587,7 +589,7 @@ function @code{window-resizable} above.
The choice of which window edges this function alters depends on the
values of the option @code{window-combination-resize} and the
combination limits of the involved windows; in some cases, it may alter
both edges. @xref{Splitting Windows}. To resize by moving only the
both edges. @xref{Recombining Windows}. To resize by moving only the
bottom or right edge of a window, use the function
@code{adjust-window-trailing-edge}, below.
@end defun
@ -795,6 +797,375 @@ A new live window @var{W2} is created, to the left of the internal
window @var{W3}. A new internal window @var{W1} is created, becoming
the new root window.
For interactive use, Emacs provides two commands which always split
the selected window. These call @code{split-window} internally.
@deffn Command split-window-right &optional size
This function splits the selected window into two side-by-side
windows, putting the selected window on the left. If @var{size} is
positive, the left window gets @var{size} columns; if @var{size} is
negative, the right window gets @minus{}@var{size} columns.
@end deffn
@deffn Command split-window-below &optional size
This function splits the selected window into two windows, one above
the other, leaving the upper window selected. If @var{size} is
positive, the upper window gets @var{size} lines; if @var{size} is
negative, the lower window gets @minus{}@var{size} lines.
@end deffn
@defopt split-window-keep-point
If the value of this variable is non-@code{nil} (the default),
@code{split-window-below} behaves as described above.
If it is @code{nil}, @code{split-window-below} adjusts point in each
of the two windows to minimize redisplay. (This is useful on slow
terminals.) It selects whichever window contains the screen line that
point was previously on. Note that this only affects
@code{split-window-below}, not the lower-level @code{split-window}
function.
@end defopt
@node Deleting Windows
@section Deleting Windows
@cindex deleting windows
@dfn{Deleting} a window removes it from the frame's window tree. If
the window is a live window, it disappears from the screen. If the
window is an internal window, its child windows are deleted too.
Even after a window is deleted, it continues to exist as a Lisp
object, until there are no more references to it. Window deletion can
be reversed, by restoring a saved window configuration (@pxref{Window
Configurations}).
@deffn Command delete-window &optional window
This function removes @var{window} from display and returns
@code{nil}. If @var{window} is omitted or @code{nil}, it defaults to
the selected window. If deleting the window would leave no more
windows in the window tree (e.g. if it is the only live window in the
frame), an error is signaled.
By default, the space taken up by @var{window} is given to one of its
adjacent sibling windows, if any. However, if the variable
@code{window-combination-resize} is non-@code{nil}, the space is
proportionally distributed among any remaining windows in the window
combination. @xref{Recombining Windows}.
The behavior of this function may be altered by the window parameters
of @var{window}, so long as the variable
@code{ignore-window-parameters} is @code{nil}. If the value of
the @code{delete-window} window parameter is @code{t}, this function
ignores all other window parameters. Otherwise, if the value of the
@code{delete-window} window parameter is a function, that function is
called with the argument @var{window}, in lieu of the usual action of
@code{delete-window}. Otherwise, this function obeys the
@code{window-atom} or @code{window-side} window parameter, if any.
@xref{Window Parameters}.
@end deffn
@deffn Command delete-other-windows &optional window
This function makes @var{window} fill its frame, by deleting other
windows as necessary. If @var{window} is omitted or @code{nil}, it
defaults to the selected window. The return value is @code{nil}.
The behavior of this function may be altered by the window parameters
of @var{window}, so long as the variable
@code{ignore-window-parameters} is @code{nil}. If the value of
the @code{delete-other-windows} window parameter is @code{t}, this
function ignores all other window parameters. Otherwise, if the value
of the @code{delete-other-windows} window parameter is a function,
that function is called with the argument @var{window}, in lieu of the
usual action of @code{delete-other-windows}. Otherwise, this function
obeys the @code{window-atom} or @code{window-side} window parameter,
if any. @xref{Window Parameters}.
@end deffn
@deffn Command delete-windows-on &optional buffer-or-name frame
This function deletes all windows showing @var{buffer-or-name}, by
calling @code{delete-window} on those windows. @var{buffer-or-name}
should be a buffer, or the name of a buffer; if omitted or @code{nil},
it defaults to the current buffer. If there are no windows showing
the specified buffer, this function does nothing. If the specified
buffer is a minibuffer, an error is signaled.
If there is a dedicated window showing the buffer, and that window is
the only one on its frame, this function also deletes that frame if it
is not the only frame on the terminal.
The optional argument @var{frame} specifies which frames to operate
on:
@itemize @bullet
@item @code{nil}
means operate on all frames.
@item @code{t}
means operate on the selected frame.
@item @code{visible}
means operate on all visible frames.
@item @code{0}
means operate on all visible or iconified frames.
@item A frame
means operate on that frame.
@end itemize
Note that this argument does not have the same meaning as in other
functions which scan all live windows (@pxref{Cyclic Window
Ordering}). Specifically, the meanings of @code{t} and @code{nil} here
are the opposite of what they are in those other functions.
@end deffn
@node Recombining Windows
@section Recombining Windows
When deleting the last sibling of a window @code{W}, its parent window
is deleted too, with @code{W} replacing it in the window tree. This
means that @code{W} must be recombined with its parent's siblings to
form a new window combination (@pxref{Windows and Frames}). In some
occasions, deleting a live window may even entail the deletion of two
internal windows.
@smallexample
@group
______________________________________
| ______ ____________________________ |
|| || __________________________ ||
|| ||| ___________ ___________ |||
|| |||| || ||||
|| ||||____W6_____||_____W7____||||
|| |||____________W4____________|||
|| || __________________________ ||
|| ||| |||
|| ||| |||
|| |||____________W5____________|||
||__W2__||_____________W3_____________ |
|__________________W1__________________|
@end group
@end smallexample
@noindent
Deleting @code{W5} in this configuration normally causes the deletion of
@code{W3} and @code{W4}. The remaining live windows @code{W2},
@code{W6} and @code{W7} are recombined to form a new horizontal
combination with parent @code{W1}.
Sometimes, however, it makes sense to not delete a parent window like
@code{W4}. In particular, a parent window should not be removed when it
was used to preserve a combination embedded in a combination of the same
type. Such embeddings make sense to assure that when you split a window
and subsequently delete the new window, Emacs reestablishes the layout
of the associated frame as it existed before the splitting.
Consider a scenario starting with two live windows @code{W2} and
@code{W3} and their parent @code{W1}.
@smallexample
@group
______________________________________
| ____________________________________ |
|| ||
|| ||
|| ||
|| ||
|| ||
|| ||
||_________________W2_________________||
| ____________________________________ |
|| ||
|| ||
||_________________W3_________________||
|__________________W1__________________|
@end group
@end smallexample
@noindent
Split @code{W2} to make a new window @code{W4} as follows.
@smallexample
@group
______________________________________
| ____________________________________ |
|| ||
|| ||
||_________________W2_________________||
| ____________________________________ |
|| ||
|| ||
||_________________W4_________________||
| ____________________________________ |
|| ||
|| ||
||_________________W3_________________||
|__________________W1__________________|
@end group
@end smallexample
@noindent
Now, when enlarging a window vertically, Emacs tries to obtain the
corresponding space from its lower sibling, provided such a window
exists. In our scenario, enlarging @code{W4} will steal space from
@code{W3}.
@smallexample
@group
______________________________________
| ____________________________________ |
|| ||
|| ||
||_________________W2_________________||
| ____________________________________ |
|| ||
|| ||
|| ||
|| ||
||_________________W4_________________||
| ____________________________________ |
||_________________W3_________________||
|__________________W1__________________|
@end group
@end smallexample
@noindent
Deleting @code{W4} will now give its entire space to @code{W2},
including the space earlier stolen from @code{W3}.
@smallexample
@group
______________________________________
| ____________________________________ |
|| ||
|| ||
|| ||
|| ||
|| ||
|| ||
|| ||
|| ||
||_________________W2_________________||
| ____________________________________ |
||_________________W3_________________||
|__________________W1__________________|
@end group
@end smallexample
@noindent
This can be counterintutive, in particular if @code{W4} were used for
displaying a buffer only temporarily (@pxref{Temporary Displays}), and
you want to continue working with the initial layout.
The behavior can be fixed by making a new parent window when splitting
@code{W2}. The variable described next allows to do that.
@defopt window-combination-limit
This variable controls whether splitting a window shall make a new
parent window. The following values are recognized:
@table @code
@item nil
This means that the new live window is allowed to share the existing
parent window, if one exists, provided the split occurs in the same
direction as the existing window combination (otherwise, a new internal
window is created anyway).
@item window-size
In this case @code{display-buffer} makes a new parent window if it is
passed a @code{window-height} or @code{window-width} entry in the
@var{alist} argument (@pxref{Display Action Functions}).
@item temp-buffer
This value causes the creation of a new parent window when a window is
split for showing a temporary buffer (@pxref{Temporary Displays}) only.
@item display-buffer
This means that when @code{display-buffer} (@pxref{Choosing Window})
splits a window it always makes a new parent window.
@item t
In this case a new parent window is always created when splitting a
window. Thus, if the value of this variable is at all times @code{t},
then at all times every window tree is a binary tree (a tree where each
window except the root window has exactly one sibling).
@end table
The default is @code{nil}. Other values are reserved for future use.
If, as a consequence of this variable's setting, @code{split-window}
makes a new parent window, it also calls
@code{set-window-combination-limit} (see below) on the newly-created
internal window. This affects how the window tree is rearranged when
the child windows are deleted (see below).
@end defopt
If @code{window-combination-limit} is @code{t}, splitting @code{W2} in
the initial configuration of our scenario would have produced this:
@smallexample
@group
______________________________________
| ____________________________________ |
|| __________________________________ ||
||| |||
|||________________W2________________|||
|| __________________________________ ||
||| |||
|||________________W4________________|||
||_________________W5_________________||
| ____________________________________ |
|| ||
|| ||
||_________________W3_________________||
|__________________W1__________________|
@end group
@end smallexample
@noindent
A new internal window @code{W5} has been created; its children are
@code{W2} and the new live window @code{W4}. Now, @code{W2} is the only
sibling of @code{W4}, so enlarging @code{W4} will try to shrink
@code{W2}, leaving @code{W3} unaffected. Observe that @code{W5}
represents a vertical combination of two windows embedded in the
vertical combination @code{W1}.
@cindex window combination limit
@defun set-window-combination-limit window limit
This functions sets the @dfn{combination limit} of the window
@var{window} to @var{limit}. This value can be retrieved via the
function @code{window-combination-limit}. See below for its effects;
note that it is only meaningful for internal windows. The
@code{split-window} function automatically calls this function, passing
it @code{t} as @var{limit}, provided the value of the variable
@code{window-combination-limit} is @code{t} when it is called.
@end defun
@defun window-combination-limit window
This function returns the combination limit for @var{window}.
The combination limit is meaningful only for an internal window. If it
is @code{nil}, then Emacs is allowed to automatically delete
@var{window}, in response to a window deletion, in order to group the
child windows of @var{window} with its sibling windows to form a new
window combination. If the combination limit is @code{t}, the child
windows of @var{window} are never automatically recombined with its
siblings.
If, in the configuration shown at the beginning of this section, the
combination limit of @code{W4} (the parent window of @code{W6} and
@code{W7}) is @code{t}, deleting @code{W5} will not implicitly delete
@code{W4} too.
@end defun
Alternatively, the problems sketched above can be avoided by always
resizing all windows in the same combination whenever one of its windows
is split or deleted. This also permits to split windows that would be
otherwise too small for such an operation.
@defopt window-combination-resize
If this variable is @code{nil}, @code{split-window} can only split a
window (denoted by @var{window}) if @var{window}'s screen area is large
@ -810,11 +1181,11 @@ combination.
The default is @code{nil}. Other values are reserved for future use.
The value of this variable is ignored when
@code{window-combination-limit} is non-@code{nil} (see below).
@code{window-combination-limit} is non-@code{nil}.
@end defopt
To illustrate the effect of @code{window-combination-resize},
consider the following window configuration:
To illustrate the effect of @code{window-combination-resize}, consider
the following frame layout.
@smallexample
@group
@ -885,248 +1256,11 @@ height:
@end group
@end smallexample
@defopt window-combination-limit
If the value of this variable is @code{t}, the @code{split-window}
function always creates a new internal window. If the value is
@code{nil}, the new live window is allowed to share the existing
parent window, if one exists, provided the split occurs in the same
direction as the existing window combination (otherwise, a new
internal window is created anyway). The default is @code{nil}. Other
values are reserved for future use.
Thus, if the value of this variable is at all times @code{t}, then at
all times every window tree is a binary tree (a tree where each window
except the root window has exactly one sibling).
Furthermore, @code{split-window} calls
@code{set-window-combination-limit} on the newly-created internal
window, recording the current value of this variable. This affects
how the window tree is rearranged when the child windows are deleted
(see below).
@end defopt
@cindex window combination limit
@defun set-window-combination-limit window limit
This functions sets the @dfn{combination limit} of the window
@var{window} to @var{limit}. This value can be retrieved via the
function @code{window-combination-limit}. See below for its effects;
note that it is only meaningful for internal windows. The
@code{split-window} function automatically calls this function, passing
the value of the variable @code{window-combination-limit} as
@var{limit}.
@end defun
@defun window-combination-limit window
This function returns the combination limit for @var{window}.
The combination limit is meaningful only for an internal window. If
it is @code{nil}, then Emacs is allowed to automatically delete
@var{window}, in response to a window deletion, in order to group the
child windows of @var{window} with its sibling windows to form a new
window combination. If the combination limit is @code{t}, the child
windows of @var{window} are never automatically re-combined with its
siblings.
@end defun
To illustrate the effect of @code{window-combination-limit},
consider the following configuration (throughout this example, we will
assume that @code{window-combination-resize} is @code{nil}):
@smallexample
@group
______________________________________
| ____________________________________ |
|| ||
|| ||
|| ||
|| ||
|| ||
|| ||
||_________________W2_________________||
| ____________________________________ |
|| ||
|| ||
||_________________W3_________________||
|__________________W1__________________|
@end group
@end smallexample
@noindent
If @code{window-combination-limit} is @code{nil}, splitting @code{W2}
into two windows, one above the other, yields
Deleting any of the live windows @code{W2}, @code{W3} or @code{W4} will
distribute its space proportionally among the two remaining live
windows.
@smallexample
@group
______________________________________
| ____________________________________ |
|| ||
|| ||
||_________________W2_________________||
| ____________________________________ |
|| ||
|| ||
||_________________W4_________________||
| ____________________________________ |
|| ||
|| ||
||_________________W3_________________||
|__________________W1__________________|
@end group
@end smallexample
@noindent
The newly-created window, @code{W4}, shares the same internal window
@code{W1}. If @code{W4} is resized, it is allowed to resize the other
live window, @code{W3}.
If @code{window-combination-limit} is @code{t}, splitting @code{W2}
in the initial configuration would instead have produced this:
@smallexample
@group
______________________________________
| ____________________________________ |
|| __________________________________ ||
||| |||
|||________________W2________________|||
|| __________________________________ ||
||| |||
|||________________W4________________|||
||_________________W5_________________||
| ____________________________________ |
|| ||
|| ||
||_________________W3_________________||
|__________________W1__________________|
@end group
@end smallexample
@noindent
A new internal window @code{W5} has been created; its children are
@code{W2} and the new live window @code{W4}. Now, @code{W2} is the
only sibling of @code{W4}, so resizing @code{W4} will resize
@code{W2}, leaving @code{W3} unaffected.
For interactive use, Emacs provides two commands which always split
the selected window. These call @code{split-window} internally.
@deffn Command split-window-right &optional size
This function splits the selected window into two side-by-side
windows, putting the selected window on the left. If @var{size} is
positive, the left window gets @var{size} columns; if @var{size} is
negative, the right window gets @minus{}@var{size} columns.
@end deffn
@deffn Command split-window-below &optional size
This function splits the selected window into two windows, one above
the other, leaving the upper window selected. If @var{size} is
positive, the upper window gets @var{size} lines; if @var{size} is
negative, the lower window gets @minus{}@var{size} lines.
@end deffn
@defopt split-window-keep-point
If the value of this variable is non-@code{nil} (the default),
@code{split-window-below} behaves as described above.
If it is @code{nil}, @code{split-window-below} adjusts point in each
of the two windows to minimize redisplay. (This is useful on slow
terminals.) It selects whichever window contains the screen line that
point was previously on. Note that this only affects
@code{split-window-below}, not the lower-level @code{split-window}
function.
@end defopt
@node Deleting Windows
@section Deleting Windows
@cindex deleting windows
@dfn{Deleting} a window removes it from the frame's window tree. If
the window is a live window, it disappears from the screen. If the
window is an internal window, its child windows are deleted too.
Even after a window is deleted, it continues to exist as a Lisp
object, until there are no more references to it. Window deletion can
be reversed, by restoring a saved window configuration (@pxref{Window
Configurations}).
@deffn Command delete-window &optional window
This function removes @var{window} from display and returns
@code{nil}. If @var{window} is omitted or @code{nil}, it defaults to
the selected window. If deleting the window would leave no more
windows in the window tree (e.g. if it is the only live window in the
frame), an error is signaled.
By default, the space taken up by @var{window} is given to one of its
adjacent sibling windows, if any. However, if the variable
@code{window-combination-resize} is non-@code{nil}, the space is
proportionally distributed among any remaining windows in the window
combination. @xref{Splitting Windows}.
The behavior of this function may be altered by the window parameters
of @var{window}, so long as the variable
@code{ignore-window-parameters} is @code{nil}. If the value of
the @code{delete-window} window parameter is @code{t}, this function
ignores all other window parameters. Otherwise, if the value of the
@code{delete-window} window parameter is a function, that function is
called with the argument @var{window}, in lieu of the usual action of
@code{delete-window}. Otherwise, this function obeys the
@code{window-atom} or @code{window-side} window parameter, if any.
@xref{Window Parameters}.
@end deffn
@deffn Command delete-other-windows &optional window
This function makes @var{window} fill its frame, by deleting other
windows as necessary. If @var{window} is omitted or @code{nil}, it
defaults to the selected window. The return value is @code{nil}.
The behavior of this function may be altered by the window parameters
of @var{window}, so long as the variable
@code{ignore-window-parameters} is @code{nil}. If the value of
the @code{delete-other-windows} window parameter is @code{t}, this
function ignores all other window parameters. Otherwise, if the value
of the @code{delete-other-windows} window parameter is a function,
that function is called with the argument @var{window}, in lieu of the
usual action of @code{delete-other-windows}. Otherwise, this function
obeys the @code{window-atom} or @code{window-side} window parameter,
if any. @xref{Window Parameters}.
@end deffn
@deffn Command delete-windows-on &optional buffer-or-name frame
This function deletes all windows showing @var{buffer-or-name}, by
calling @code{delete-window} on those windows. @var{buffer-or-name}
should be a buffer, or the name of a buffer; if omitted or @code{nil},
it defaults to the current buffer. If there are no windows showing
the specified buffer, this function does nothing. If the specified
buffer is a minibuffer, an error is signaled.
If there is a dedicated window showing the buffer, and that window is
the only one on its frame, this function also deletes that frame if it
is not the only frame on the terminal.
The optional argument @var{frame} specifies which frames to operate
on:
@itemize @bullet
@item @code{nil}
means operate on all frames.
@item @code{t}
means operate on the selected frame.
@item @code{visible}
means operate on all visible frames.
@item @code{0}
means operate on all visible or iconified frames.
@item A frame
means operate on that frame.
@end itemize
Note that this argument does not have the same meaning as in other
functions which scan all live windows (@pxref{Cyclic Window
Ordering}). Specifically, the meanings of @code{t} and @code{nil} here
are the opposite of what they are in those other functions.
@end deffn
@node Selecting Windows
@section Selecting Windows

29
doc/misc/ChangeLog
View file

@ -1,3 +1,32 @@
2012-11-10 Chong Yidong <cyd@gnu.org>
* url.texi (Introduction): Move url-configuration-directory to
Customization node.
(Parsed URIs): Split into its own node.
(URI Encoding): New node.
(Defining New URLs): Remove empty chapter.
(Retrieving URLs): Add an introduction. Doc fix for url-retrieve.
Improve docs for url-queue-*.
(Supported URL Types): Copyedits. Delete empty subnodes.
* url.texi (Introduction): Rename from Getting Started. Rewrite
the introduction.
(URI Parsing): Rewrite. Omit the obsolete attributes slot.
2012-11-10 Glenn Morris <rgm@gnu.org>
* cl.texi (Obsolete Setf Customization):
Revert defsetf example to the more correct let rather than prog1.
Give define-modify-macro, defsetf, and define-setf-method
gv.el replacements.
* cl.texi (Overview): Mention EIEIO here, as well as the appendix.
(Setf Extensions): Remove obsolete reference.
(Obsolete Setf Customization):
Move note on lack of setf functions to lispref/variables.texi.
Undocument get-setf-method, since it no longer exists.
Mention simple defsetf replaced by gv-define-simple-setter.
2012-11-03 Glenn Morris <rgm@gnu.org>
* cl.texi: Further general copyedits.

151
doc/misc/cl.texi
View file

@ -107,7 +107,8 @@ for various reasons:
@item
Some features are too complex or bulky relative to their benefit
to Emacs Lisp programmers. CLOS and Common Lisp streams are fine
examples of this group.
examples of this group. (The separate package EIEIO implements
a subset of CLOS functionality. @xref{Top, , Introduction, eieio, EIEIO}.)
@item
Other features cannot be implemented without modification to the
@ -974,7 +975,7 @@ a
The generalized variable @code{buffer-substring}, listed above,
also works in this way by replacing a portion of the current buffer.
@c FIXME? Also `eq'? (see cl-lib.el)
@c FIXME? Also `eq'? (see cl-lib.el)
@c Currently commented out in cl.el.
@ignore
@ -989,13 +990,10 @@ only interesting when used with places you define yourself with
@xref{Obsolete Setf Customization}.
@end ignore
@c FIXME? Is this still true?
@item
A macro call, in which case the macro is expanded and @code{setf}
is applied to the resulting form.
@item
Any form for which a @code{defsetf} or @code{define-setf-method}
has been made. @xref{Obsolete Setf Customization}.
@end itemize
@c FIXME should this be in lispref? It seems self-evident.
@ -2867,7 +2865,6 @@ temporary variables.
This function creates a new, uninterned symbol (using @code{make-symbol})
with a unique name. (The name of an uninterned symbol is relevant
only if the symbol is printed.) By default, the name is generated
@c FIXME no longer true?
from an increasing sequence of numbers, @samp{G1000}, @samp{G1001},
@samp{G1002}, etc. If the optional argument @var{x} is a string, that
string is used as a prefix instead of @samp{G}. Uninterned symbols
@ -4481,14 +4478,6 @@ The @code{equal} predicate does not distinguish
between IEEE floating-point plus and minus zero. The @code{cl-equalp}
predicate has several differences with Common Lisp; @pxref{Predicates}.
@c FIXME consider moving to lispref
@ignore
The @code{setf} mechanism is entirely compatible, except that
setf-methods return a list of five values rather than five
values directly. Also, the new ``@code{setf} function'' concept
(typified by @code{(defun (setf foo) @dots{})}) is not implemented.
@end ignore
The @code{cl-do-all-symbols} form is the same as @code{cl-do-symbols}
with no @var{obarray} argument. In Common Lisp, this form would
iterate over all symbols in all packages. Since Emacs obarrays
@ -4907,15 +4896,17 @@ Common Lisp defines three macros, @code{define-modify-macro},
@code{defsetf}, and @code{define-setf-method}, that allow the
user to extend generalized variables in various ways.
In Emacs, these are obsolete, replaced by various features of
@file{gv.el} in Emacs 24.3. Many of the implementation
details in the following are out-of-date.
@c FIXME this whole section needs updating.
@file{gv.el} in Emacs 24.3.
@xref{Adding Generalized Variables,,,elisp,GNU Emacs Lisp Reference Manual}.
@defmac define-modify-macro name arglist function [doc-string]
This macro defines a ``read-modify-write'' macro similar to
@code{cl-incf} and @code{cl-decf}. The macro @var{name} is defined
to take a @var{place} argument followed by additional arguments
described by @var{arglist}. The call
@code{cl-incf} and @code{cl-decf}. You can replace this macro
with @code{gv-letplace}.
The macro @var{name} is defined to take a @var{place} argument
followed by additional arguments described by @var{arglist}. The call
@example
(@var{name} @var{place} @var{args}@dots{})
@ -4938,8 +4929,8 @@ which in turn is roughly equivalent to
For example:
@example
(define-modify-macro cl-incf (&optional (n 1)) +)
(define-modify-macro cl-concatf (&rest args) concat)
(define-modify-macro incf (&optional (n 1)) +)
(define-modify-macro concatf (&rest args) concat)
@end example
Note that @code{&key} is not allowed in @var{arglist}, but
@ -4948,16 +4939,31 @@ Note that @code{&key} is not allowed in @var{arglist}, but
Most of the modify macros defined by Common Lisp do not exactly
follow the pattern of @code{define-modify-macro}. For example,
@code{push} takes its arguments in the wrong order, and @code{pop}
is completely irregular. You can define these macros ``by hand''
using @code{get-setf-method}, or consult the source
to see how to use the internal @code{setf} building blocks.
is completely irregular.
The above @code{incf} example could be written using
@code{gv-letplace} as:
@example
(defmacro incf (place &optional n)
(gv-letplace (getter setter) place
(macroexp-let2 nil v (or n 1)
(funcall setter `(+ ,v ,getter)))))
@end example
@ignore
(defmacro concatf (place &rest args)
(gv-letplace (getter setter) place
(macroexp-let2 nil v (mapconcat 'identity args "")
(funcall setter `(concat ,getter ,v)))))
@end ignore
@end defmac
@defmac defsetf access-fn update-fn
This is the simpler of two @code{defsetf} forms. Where
@var{access-fn} is the name of a function which accesses a place,
this declares @var{update-fn} to be the corresponding store
function. From now on,
This is the simpler of two @code{defsetf} forms, and is
replaced by @code{gv-define-simple-setter}.
With @var{access-fn} the name of a function that accesses a place,
this declares @var{update-fn} to be the corresponding store function.
From now on,
@example
(setf (@var{access-fn} @var{arg1} @var{arg2} @var{arg3}) @var{value})
@ -4972,7 +4978,7 @@ will be expanded to
@noindent
The @var{update-fn} is required to be either a true function, or
a macro which evaluates its arguments in a function-like way. Also,
a macro that evaluates its arguments in a function-like way. Also,
the @var{update-fn} is expected to return @var{value} as its result.
Otherwise, the above expansion would not obey the rules for the way
@code{setf} is supposed to behave.
@ -4988,25 +4994,32 @@ something more like
temp)
@end example
Some examples of the use of @code{defsetf}, drawn from the standard
suite of setf methods, are:
Some examples are:
@example
(defsetf car setcar)
(defsetf symbol-value set)
(defsetf buffer-name rename-buffer t)
@end example
These translate directly to @code{gv-define-simple-setter}:
@example
(gv-define-simple-setter car setcar)
(gv-define-simple-setter buffer-name rename-buffer t)
@end example
@end defmac
@defmac defsetf access-fn arglist (store-var) forms@dots{}
This is the second, more complex, form of @code{defsetf}. It is
rather like @code{defmacro} except for the additional @var{store-var}
argument. The @var{forms} should return a Lisp form that stores
the value of @var{store-var} into the generalized variable formed
by a call to @var{access-fn} with arguments described by @var{arglist}.
The @var{forms} may begin with a string which documents the @code{setf}
method (analogous to the doc string that appears at the front of a
function).
This is the second, more complex, form of @code{defsetf}.
It can be replaced by @code{gv-define-setter}.
This form of @code{defsetf} is rather like @code{defmacro} except for
the additional @var{store-var} argument. The @var{forms} should
return a Lisp form that stores the value of @var{store-var} into the
generalized variable formed by a call to @var{access-fn} with
arguments described by @var{arglist}. The @var{forms} may begin with
a string which documents the @code{setf} method (analogous to the doc
string that appears at the front of a function).
For example, the simple form of @code{defsetf} is shorthand for
@ -5021,20 +5034,28 @@ macros like @code{cl-incf} that invoke this
setf-method will insert temporary variables as needed to make
sure the apparent order of evaluation is preserved.
Another example drawn from the standard package:
Another standard example:
@example
(defsetf nth (n x) (store)
(list 'setcar (list 'nthcdr n x) store))
`(setcar (nthcdr ,n ,x) ,store))
@end example
You could write this using @code{gv-define-setter} as:
@example
(gv-define-setter nth (store n x)
`(setcar (nthcdr ,n ,x) ,store))
@end example
@end defmac
@defmac define-setf-method access-fn arglist forms@dots{}
This is the most general way to create new place forms. When
a @code{setf} to @var{access-fn} with arguments described by
@var{arglist} is expanded, the @var{forms} are evaluated and
must return a list of five items:
@c FIXME Is this still true?
This is the most general way to create new place forms. You can
replace this by @code{gv-define-setter} or @code{gv-define-expander}.
When a @code{setf} to @var{access-fn} with arguments described by
@var{arglist} is expanded, the @var{forms} are evaluated and must
return a list of five items:
@enumerate
@item
@ -5063,6 +5084,9 @@ This is exactly like the Common Lisp macro of the same name,
except that the method returns a list of five values rather
than the five values themselves, since Emacs Lisp does not
support Common Lisp's notion of multiple return values.
(Note that the @code{setf} implementation provided by @file{gv.el}
does not use this five item format. Its use here is only for
backwards compatibility.)
Once again, the @var{forms} may begin with a documentation string.
@ -5078,45 +5102,22 @@ turn out to be unnecessary, so there is little reason for the
setf-method itself to optimize.
@end defmac
@c Removed in Emacs 24.3, not possible to make a compatible replacement.
@ignore
@defun get-setf-method place &optional env
This function returns the setf-method for @var{place}, by
invoking the definition previously recorded by @code{defsetf}
or @code{define-setf-method}. The result is a list of five
values as described above. You can use this function to build
your own @code{cl-incf}-like modify macros.
@c These no longer exist.
@ignore
(Actually, it is better to use the internal functions
@code{cl-setf-do-modify} and @code{cl-setf-do-store}, which are a bit
easier to use and which also do a number of optimizations; consult the
source code for the @code{cl-incf} function for a simple example.)
@end ignore
The argument @var{env} specifies the ``environment'' to be
passed on to @code{macroexpand} if @code{get-setf-method} should
need to expand a macro in @var{place}. It should come from
an @code{&environment} argument to the macro or setf-method
that called @code{get-setf-method}.
@c FIXME No longer true.
See also the source code for the setf-method for
@c Also @code{apply}, but that is commented out.
@code{substring}, which works by calling @code{get-setf-method} on a
simpler case, then massaging the result.
@end defun
@c FIXME does not belong here any more, maybe in lispref?
Modern Common Lisp defines a second, independent way to specify
the @code{setf} behavior of a function, namely ``@code{setf}
functions'' whose names are lists @code{(setf @var{name})}
rather than symbols. For example, @code{(defun (setf foo) @dots{})}
defines the function that is used when @code{setf} is applied to
@code{foo}. This package does not currently support @code{setf}
functions. In particular, it is a compile-time error to use
@code{setf} on a form which has not already been @code{defsetf}'d
or otherwise declared; in newer Common Lisps, this would not be
an error since the function @code{(setf @var{func})} might be
defined later.
@end ignore
@node GNU Free Documentation License

642
doc/misc/url.texi
View file

@ -18,7 +18,7 @@
@end direntry
@copying
This file documents the Emacs Lisp URL loading package.
This is the manual for the @code{url} Emacs Lisp library.
Copyright @copyright{} 1993-1999, 2002, 2004-2012 Free Software Foundation, Inc.
@ -57,10 +57,10 @@ developing GNU and promoting software freedom.''
@end ifnottex
@menu
* Getting Started:: Preparing your program to use URLs.
* Introduction:: About the @code{url} library.
* URI Parsing:: Parsing (and unparsing) URIs.
* Retrieving URLs:: How to use this package to retrieve a URL.
* Supported URL Types:: Descriptions of URL types currently supported.
* Defining New URLs:: How to define a URL loader for a new protocol.
* General Facilities:: URLs can be cached, accessed via a gateway
and tracked in a history list.
* Customization:: Variables you can alter.
@ -70,93 +70,129 @@ developing GNU and promoting software freedom.''
* Concept Index::
@end menu
@node Getting Started
@chapter Getting Started
@cindex URLs, definition
@cindex URIs
@node Introduction
@chapter Introduction
@cindex URL
@cindex URI
@cindex uniform resource identifier
@cindex uniform resource locator
@dfn{Uniform Resource Locators} (URLs) are a specific form of
@dfn{Uniform Resource Identifiers} (URI) described in RFC 2396 which
updates RFC 1738 and RFC 1808. RFC 2016 defines uniform resource
agents.
A @dfn{Uniform Resource Identifier} (URI) is a specially-formatted
name, such as an Internet address, that identifies some name or
resource. The format of URIs is described in RFC 3986, which updates
and replaces the earlier RFCs 2732, 2396, 1808, and 1738. A
@dfn{Uniform Resource Locator} (URL) is an older but still-common
term, which basically refers to a URI corresponding to a resource that
can be accessed (usually over a network) in a specific way.
URIs have the form @var{scheme}:@var{scheme-specific-part}, where the
@var{scheme}s supported by this library are described below.
@xref{Supported URL Types}.
FTP, NFS, HTTP, HTTPS, @code{rlogin}, @code{telnet}, tn3270,
IRC and gopher URLs all have the form
Here are some examples of URIs (taken from RFC 3986):
@example
@var{scheme}://@r{[}@var{userinfo}@@@r{]}@var{hostname}@r{[}:@var{port}@r{]}@r{[}/@var{path}@r{]}
ftp://ftp.is.co.za/rfc/rfc1808.txt
http://www.ietf.org/rfc/rfc2396.txt
ldap://[2001:db8::7]/c=GB?objectClass?one
mailto:John.Doe@@example.com
news:comp.infosystems.www.servers.unix
tel:+1-816-555-1212
telnet://192.0.2.16:80/
urn:oasis:names:specification:docbook:dtd:xml:4.1.2
@end example
This manual describes the @code{url} library, an Emacs Lisp library
for parsing URIs and retrieving the resources to which they refer.
(The library is so-named for historical reasons; nowadays, the ``URI''
terminology is regarded as the more general one, and ``URL'' is
technically obsolete despite its widespread vernacular usage.)
@node URI Parsing
@chapter URI Parsing
A URI consists of several @dfn{components}, each having a different
meaning. For example, the URI
@example
http://www.gnu.org/software/emacs/
@end example
@noindent
where @samp{@r{[}} and @samp{@r{]}} delimit optional parts.
@var{userinfo} sometimes takes the form @var{username}:@var{password}
but you should beware of the security risks of sending cleartext
passwords. @var{hostname} may be a domain name or a dotted decimal
address. If the @samp{:@var{port}} is omitted then the library will
use the ``well known'' port for that service when accessing URLs. With
the possible exception of @code{telnet}, it is rare for ports to be
specified, and it is possible using a non-standard port may have
undesired consequences if a different service is listening on that
port (e.g., an HTTP URL specifying the SMTP port can cause mail to be
sent). @c , but @xref{Other Variables, url-bad-port-list}.
The meaning of the @var{path} component depends on the service.
specifies the scheme component @samp{http}, the hostname component
@samp{www.gnu.org}, and the path component @samp{/software/emacs/}.
@cindex parsed URIs
The format of URIs is specified by RFC 3986. The @code{url} library
provides the Lisp function @code{url-generic-parse-url}, a (mostly)
standard-compliant URI parser, as well as function
@code{url-recreate-url}, which converts a parsed URI back into a URI
string.
@defun url-generic-parse-url uri-string
This function returns a parsed version of the string @var{uri-string}.
@end defun
@defun url-recreate-url uri-obj
@cindex unparsing URLs
Given a parsed URI, this function returns the corresponding URI string.
@end defun
@cindex parsed URI
The return value of @code{url-generic-parse-url}, and the argument
expected by @code{url-recreate-url}, is a @dfn{parsed URI}: a CL
structure whose slots hold the various components of the URI.
@xref{top,the CL Manual,,cl,GNU Emacs Common Lisp Emulation}, for
details about CL structures. Most of the other functions in the
@code{url} library act on parsed URIs.
@menu
* Configuration::
* Parsed URLs:: URLs are parsed into vector structures.
* Parsed URIs:: Format of parsed URI structures.
* URI Encoding:: Non-@acronym{ASCII} characters in URIs.
@end menu
@node Configuration
@section Configuration
@node Parsed URIs
@section Parsed URI structures
@defvar url-configuration-directory
@cindex @file{~/.url}
@cindex configuration files
The directory in which URL configuration files, the cache etc.,
reside. The old default was @file{~/.url}, and this directory
is still used if it exists. The new default is a @file{url/}
directory in @code{user-emacs-directory}, which is normally
@file{~/.emacs.d}.
@end defvar
Each parsed URI structure contains the following slots:
@node Parsed URLs
@section Parsed URLs
@cindex parsed URLs
The library functions typically operate on @dfn{parsed} versions of
URLs. These are actually CL structures (vectors) of the form:
@example
[cl-struct-url @var{type} @var{user} @var{password} @var{host} @var{port} @var{filename} @var{target} @var{attributes} @var{fullness} @var{use-cookies}]
@end example
@noindent where
@table @var
@table @code
@item type
is the type of the URL scheme, e.g., @code{http}
The URI scheme (a string, e.g.@: @code{http}). @xref{Supported URL
Types}, for a list of schemes that the @code{url} library knows how to
process. This slot can also be @code{nil}, if the URI is not fully
specified.
@item user
is the username associated with it, or @code{nil};
The user name (a string), or @code{nil}.
@item password
is the user password associated with it, or @code{nil};
The user password (a string), or @code{nil}. The use of this URI
component is strongly discouraged; nowadays, passwords are transmitted
by other means, not as part of a URI.
@item host
is the host name associated with it, or @code{nil};
The host name (a string), or @code{nil}. If present, this is
typically a domain name or IP address.
@item port
is the port number associated with it, or @code{nil};
The port number (an integer), or @code{nil}. Omitting this component
usually means to use the ``standard'' port associated with the URI
scheme.
@item filename
is the ``file'' part of it, or @code{nil}. This doesn't necessarily
actually refer to a file;
The combination of the ``path'' and ``query'' components of the URI (a
string), or @code{nil}. If the query component is present, it is the
substring following the first @samp{?} character, and the path
component is the substring before the @samp{?}. The meaning of these
components is scheme-dependent; they do not necessarily refer to a
file on a disk.
@item target
is the target part, or @code{nil};
@item attributes
is the attributes associated with it, or @code{nil};
The fragment component (a string), or @code{nil}. The fragment
component specifies a ``secondary resource'', such as a section of a
webpage.
@item fullness
is @code{t} for a fully-specified URL, with a host part indicated by
@samp{//} after the scheme part.
@item use-cookies
is @code{nil} to neither send or store cookies to the server, @code{t}
otherwise.
This is @code{t} if the URI is fully specified, i.e.@: the
hierarchical components of the URI (the hostname and/or username
and/or password) are preceded by @samp{//}.
@end table
@findex url-type
@ -168,64 +204,165 @@ otherwise.
@findex url-target
@findex url-attributes
@findex url-fullness
These attributes have accessors named @code{url-@var{part}}, where
@var{part} is the name of one of the elements above, e.g.,
@code{url-host}. These attributes can be set with the same accessors
using @code{setf}:
These slots have accessors named @code{url-@var{part}}, where
@var{part} is the slot name. For example, the accessor for the
@code{host} slot is the function @code{url-host}. The @code{url-port}
accessor returns the default port for the URI scheme if the parsed
URI's @var{port} slot is @code{nil}.
The slots can be set using @code{setf}. For example:
@example
(setf (url-port url) 80)
@end example
If @var{port} is @var{nil}, @code{url-port} returns the default port
of the protocol.
@node URI Encoding
@section URI Encoding
There are functions for parsing and unparsing between the string and
vector forms.
@cindex percent encoding
The @code{url-generic-parse-url} parser does not obey RFC 3986 in
one respect: it allows non-@acronym{ASCII} characters in URI strings.
@defun url-generic-parse-url url
Return a parsed version of the string @var{url}.
Strictly speaking, RFC 3986 compatible URIs may only consist of
@acronym{ASCII} characters; non-@acronym{ASCII} characters are
represented by converting them to UTF-8 byte sequences, and performing
@dfn{percent encoding} on the bytes. For example, the o-umlaut
character is converted to the UTF-8 byte sequence @samp{\xD3\xA7},
then percent encoded to @samp{%D3%A7}. (Certain ``reserved''
@acronym{ASCII} characters must also be percent encoded when they
appear in URI components.)
The function @code{url-encode-url} can be used to convert a URI
string containing arbitrary characters to one that is properly
percent-encoded in accordance with RFC 3986.
@defun url-encode-url url-string
This function return a properly URI-encoded version of
@var{url-string}. It also performs @dfn{URI normalization},
e.g.@: converting the scheme component to lowercase if it was
previously uppercase.
@end defun
@defun url-recreate-url url
@cindex unparsing URLs
Recreates a URL string from the parsed @var{url}.
To convert between a string containing arbitrary characters and a
percent-encoded all-@acronym{ASCII} string, use the functions
@code{url-hexify-string} and @code{url-unhex-string}:
@defun url-hexify-string string &optional allowed-chars
This function performs percent-encoding on @var{string}, and returns
the result.
If @var{string} is multibyte, it is first converted to a UTF-8 byte
string. Each byte corresponding to an allowed character is left
as-is, while all other bytes are converted to a three-character
sequence: @samp{%} followed by two upper-case hex digits.
@vindex url-unreserved-chars
@cindex unreserved characters
The allowed characters are specified by @var{allowed-chars}. If this
argument is @code{nil}, the allowed characters are those specified as
@dfn{unreserved characters} by RFC 3986 (see the variable
@code{url-unreserved-chars}). Otherwise, @var{allowed-chars} should
be a vector whose @var{n}-th element is non-@code{nil} if character
@var{n} is allowed.
@end defun
@defun url-unhex-string string &optional allow-newlines
This function replaces percent-encoding sequences in @var{string} with
their character equivalents, and returns the resulting string.
If @var{allow-newlines} is non-@code{nil}, it allows the decoding of
carriage returns and line feeds, which are normally forbidden in URIs.
@end defun
@node Retrieving URLs
@chapter Retrieving URLs
The @code{url} library defines the following three functions for
retrieving the data specified by a URL. The actual retrieval protocol
depends on the URL's URI scheme, and is performed by lower-level
scheme-specific functions. (Those lower-level functions are not
documented here, and generally should not be called directly.)
In each of these functions, the @var{url} argument can be either a
string or a parsed URL structure. If it is a string, that string is
passed through @code{url-encode-url} before using it, to ensure that
it is properly URI-encoded (@pxref{URI Encoding}).
@defun url-retrieve-synchronously url
Retrieve @var{url} synchronously and return a buffer containing the
data. @var{url} is either a string or a parsed URL structure. Return
@code{nil} if there are no data associated with it (the case for dired,
info, or mailto URLs that need no further processing).
This function synchronously retrieves the data specified by @var{url},
and returns a buffer containing the data. The return value is
@code{nil} if there is no data associated with the URL (as is the case
for @code{dired}, @code{info}, and @code{mailto} URLs).
@end defun
@defun url-retrieve url callback &optional cbargs silent no-cookies
Retrieve @var{url} asynchronously and call @var{callback} with args
@var{cbargs} when finished. The callback is called when the object
has been completely retrieved, with the current buffer containing the
object and any MIME headers associated with it. @var{url} is either a
string or a parsed URL structure. Returns the buffer @var{url} will
load into, or @code{nil} if the process has already completed.
If the optional argument @var{silent} is non-@code{nil}, suppress
progress messages. If the optional argument @var{no-cookies} is
non-@code{nil}, do not store or send cookies.
This function retrieves @var{url} asynchronously, calling the function
@var{callback} when the object has been completely retrieved. The
return value is the buffer into which the data will be inserted, or
@code{nil} if the process has already completed.
The callback function is called this way:
@example
(apply @var{callback} @var{status} @var{cbargs})
@end example
@noindent
where @var{status} is a plist representing what happened during the
retrieval, with most recent events first, or an empty list if no
events have occurred. Each pair in the plist is one of:
@table @code
@item (:redirect @var{redirected-to})
This means that the request was redirected to the URL
@var{redirected-to}.
@item (:error (@var{error-symbol} . @var{data}))
This means that an error occurred. If so desired, the error can be
signaled with @code{(signal @var{error-symbol} @var{data})}.
@end table
When the callback function is called, the current buffer is the one
containing the retrieved data (if any). The buffer also contains any
MIME headers associated with the data retrieval.
If the optional argument @var{silent} is non-@code{nil}, progress
messages are suppressed. If the optional argument @var{no-cookies} is
non-@code{nil}, cookies are not stored or sent.
@end defun
@defun url-queue-retrieve url callback &optional cbargs silent no-cookies
This function acts like @code{url-retrieve}, but with limits on the
number of concurrently-running network processes. The option
@code{url-queue-parallel-processes} controls the number of concurrent
processes, and the option @code{url-queue-timeout} sets a timeout in
seconds.
To use this function, you must @code{(require 'url-queue)}.
@end defun
@vindex url-queue-parallel-processes
@defopt url-queue-parallel-processes
The value of this option is an integer specifying the maximum number
of concurrent @code{url-queue-retrieve} network processes. If the
number of @code{url-queue-retrieve} calls is larger than this number,
later ones are queued until ealier ones are finished.
@end defopt
@vindex url-queue-timeout
@defun url-queue-retrieve url callback &optional cbargs silent no-cookies
This acts like the @code{url-retrieve} function, but with limits on
the degree of parallelism. The option @code{url-queue-parallel-processes}
controls the number of concurrent processes, and the option
@code{url-queue-timeout} sets a timeout in seconds.
@end defun
@defopt url-queue-timeout
The value of this option is a number specifying the maximum lifetime
of a @code{url-queue-retrieve} network process, once it is started.
If a process is not finished by then, it is killed and removed from
the queue.
@end defopt
@node Supported URL Types
@chapter Supported URL Types
This chapter describes functions and variables affecting URL retrieval
for specific schemes.
@menu
* http/https:: Hypertext Transfer Protocol.
* file/ftp:: Local files and FTP archives.
@ -236,48 +373,31 @@ controls the number of concurrent processes, and the option
* irc:: Internet Relay Chat.
* data:: Embedded data URLs.
* nfs:: Networked File System
@c * finger::
@c * gopher::
@c * netrek::
@c * prospero::
* cid:: Content-ID.
* about::
* ldap:: Lightweight Directory Access Protocol
* imap:: IMAP mailboxes.
* man:: Unix man pages.
@end menu
@node http/https
@section @code{http} and @code{https}
The scheme @code{http} is Hypertext Transfer Protocol. The library
supports version 1.1, specified in RFC 2616. (This supersedes 1.0,
defined in RFC 1945) HTTP URLs have the following form, where most of
the parts are optional:
@example
http://@var{user}:@var{password}@@@var{host}:@var{port}/@var{path}?@var{searchpart}#@var{fragment}
@end example
@c The @code{:@var{port}} part is optional, and @var{port} defaults to
@c 80. The @code{/@var{path}} part, if present, is a slash-separated
@c series elements. The @code{?@var{searchpart}}, if present, is the
@c query for a search or the content of a form submission. The
@c @code{#fragment} part, if present, is a location in the document.
The @code{http} scheme refers to the Hypertext Transfer Protocol. The
@code{url} library supports HTTP version 1.1, specified in RFC 2616.
Its default port is 80.
The scheme @code{https} is a secure version of @code{http}, with
transmission via SSL. It is defined in RFC 2069. Its default port is
443. This scheme depends on SSL support in Emacs via the
@file{ssl.el} library and is actually implemented by forcing the
@code{ssl} gateway method to be used. @xref{Gateways in general}.
The @code{https} scheme is a secure version of @code{http}, with
transmission via SSL. It is defined in RFC 2069, and its default port
is 443. When using @code{https}, the @code{url} library performs SSL
encryption via the @code{ssl} library, by forcing the @code{ssl}
gateway method to be used. @xref{Gateways in general}.
@defopt url-honor-refresh-requests
This controls honoring of HTTP @samp{Refresh} headers by which
servers can direct clients to reload documents from the same URL or a
or different one. @code{nil} means they will not be honored,
@code{t} (the default) means they will always be honored, and
otherwise the user will be asked on each request.
If this option is non-@code{nil} (the default), the @code{url} library
honors the HTTP @samp{Refresh} header, which is used by servers to
direct clients to reload documents from the same URL or a or different
one. If the value is @code{nil}, the @samp{Refresh} header is
ignored; any other value means to ask the user on each request.
@end defopt
@menu
* Cookies::
* HTTP language/coding::
@ -409,26 +529,32 @@ emacs-mime, The Emacs MIME Manual}.
@cindex compressed files
@cindex dired
The @code{ftp} and @code{file} schemes are defined in RFC 1808. The
@code{url} library treats @samp{ftp:} and @samp{file:} as synonymous.
Such URLs have the form
@example
ftp://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file}
file://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file}
@end example
These schemes are defined in RFC 1808.
@samp{ftp:} and @samp{file:} are synonymous in this library. They
allow reading arbitrary files from hosts. Either @samp{ange-ftp}
(Emacs) or @samp{efs} (XEmacs) is used to retrieve them from remote
hosts. Local files are accessed directly.
@noindent
If the URL specifies a local file, it is retrieved by reading the file
contents in the usual way. If it specifies a remote file, it is
retrieved using the Ange-FTP package. @xref{Remote Files,,, emacs,
The GNU Emacs Manual}.
Compressed files are handled, but support is hard-coded so that
@code{jka-compr-compression-info-list} and so on have no affect.
Suffixes recognized are @samp{.z}, @samp{.gz}, @samp{.Z} and
@samp{.bz2}.
When retrieving a compressed file, it is automatically uncompressed
if it has the file suffix @file{.z}, @file{.gz}, @file{.Z},
@file{.bz2}, or @file{.xz}. (The list of supported suffixes is
hard-coded, and cannot be altered by customizing
@code{jka-compr-compression-info-list}.)
@defopt url-directory-index-file
The filename to look for when indexing a directory, default
@samp{"index.html"}. If this file exists, and is readable, then it
will be viewed instead of using @code{dired} to view the directory.
This option specifies the filename to look for when a @code{file} or
@code{ftp} URL specifies a directory. The default is
@file{index.html}. If this file exists and is readable, it is viewed.
Otherwise, Emacs visits the directory using Dired.
@end defopt
@node info
@ -437,47 +563,53 @@ will be viewed instead of using @code{dired} to view the directory.
@cindex Texinfo
@findex Info-goto-node
The @code{info} scheme is non-standard. Such URLs have the form
@example
info:@var{file}#@var{node}
@end example
Info URLs are not officially defined. They invoke
@code{Info-goto-node} with argument @samp{(@var{file})@var{node}}.
@samp{#@var{node}} is optional, defaulting to @samp{Top}.
@noindent
and are retrieved by invoking @code{Info-goto-node} with argument
@samp{(@var{file})@var{node}}. If @samp{#@var{node}} is omitted, the
@samp{Top} node is opened.
@node mailto
@section mailto
@cindex mailto
@cindex email
A mailto URL will send an email message to the address in the
URL, for example @samp{mailto:foo@@bar.com} would compose a
message to @samp{foo@@bar.com}.
A @code{mailto} URL specifies an email message to be sent to a given
email address. For example, @samp{mailto:foo@@bar.com} specifies
sending a message to @samp{foo@@bar.com}. The ``retrieval method''
for such URLs is to open a mail composition buffer in which the
appropriate content (e.g.@: the recipient address) has been filled in.
@defopt url-mail-command
@vindex mail-user-agent
The function called whenever url needs to send mail. This should
normally be left to default from @var{mail-user-agent}. @xref{Mail
Methods, , Mail-Composition Methods, emacs, The GNU Emacs Manual}.
@end defopt
As defined in RFC 2368, a @code{mailto} URL has the form
An @samp{X-Url-From} header field containing the URL of the document
that contained the mailto URL is added if that URL is known.
RFC 2368 extends the definition of mailto URLs in RFC 1738.
The form of a mailto URL is
@example
@samp{mailto:@var{mailbox}[?@var{header}=@var{contents}[&@var{header}=@var{contents}]]}
@end example
@noindent where an arbitrary number of @var{header}s can be added. If the
@var{header} is @samp{body}, then @var{contents} is put in the body
otherwise a @var{header} header field is created with @var{contents}
as its contents. Note that the URL library does not consider any
headers ``dangerous'' so you should check them before sending the
message.
@c Fixme: update
Email messages are defined in @sc{rfc}822.
@noindent
where an arbitrary number of @var{header}s can be added. If the
@var{header} is @samp{body}, then @var{contents} is put in the message
body; otherwise, a @var{header} header field is created with
@var{contents} as its contents. Note that the @code{url} library does
not perform any checking of @var{header} or @var{contents}, so you
should check them before sending the message.
@defopt url-mail-command
@vindex mail-user-agent
The value of this variable is the function called whenever url needs
to send mail. This should normally be left its default, which is the
standard mail-composition command @code{compose-mail}. @xref{Sending
Mail,,, emacs, The GNU Emacs Manual}.
@end defopt
If the document containing the @code{mailto} URL itself possessed a
known URL, Emacs automatically inserts an @samp{X-Url-From} header
field into the mail buffer, specifying that URL.
@node news/nntp/snews
@section @code{news}, @code{nntp} and @code{snews}
@ -487,11 +619,13 @@ Email messages are defined in @sc{rfc}822.
@cindex NNTP
@cindex snews
@c draft-gilman-news-url-01
The network news URL scheme take the following forms following RFC
1738 except that for compatibility with other clients, host and port
fields may be included in news URLs though they are properly only
allowed for nntp an snews.
The @code{news}, @code{nntp}, and @code{snews} schemes, defined in RFC
1738, are used for reading Usenet newsgroups. For compatibility with
non-standard-compliant news clients, the @code{url} library allows
host and port fields to be included in @code{news} URLs, even though
they are properly only allowed for @code{nntp} and @code{snews}.
@code{news} and @code{nntp} URLs have the following form:
@table @samp
@item news:@var{newsgroup}
@ -506,24 +640,22 @@ Retrieves a list of all available newsgroups;
Similar to the @samp{news} versions.
@end table
@samp{:@var{port}} is optional and defaults to :119.
The default port for @code{nntp} (and @code{news}) is 119. The
difference between an @code{nntp} URL and a @code{news} URL is that an
@code{nttp} URL may specify an article by its number. The
@samp{snews} scheme is the same as @samp{nntp}, except that it is
tunneled through SSL and has default port 563.
@samp{snews} is the same as @samp{nntp} except that the default port
is :563.
@cindex SSL
(It is tunneled through SSL.)
These URLs are retrieved via the Gnus package.
An @samp{nntp} URL is the same as a news URL, except that the URL may
specify an article by its number.
@defopt url-news-server
This variable can be used to override the default news server.
Usually this will be set by the Gnus package, which is used to fetch
news.
@cindex environment variable
@vindex NNTPSERVER
It may be set from the conventional environment variable
@code{NNTPSERVER}.
@defopt url-news-server
This variable specifies the default news server from which to fetch
news, if no server was specified in the URL. The default value,
@code{nil}, means to use the server specified by the standard
environment variable @samp{NNTPSERVER}, or @samp{news} if that
environment variable is unset.
@end defopt
@node rlogin/telnet/tn3270
@ -534,12 +666,15 @@ It may be set from the conventional environment variable
@cindex terminal emulation
@findex terminal-emulator
These URL schemes from RFC 1738 for logon via a terminal emulator have
the form
These URL schemes are defined in RFC 1738, and are used for logging in
via a terminal emulator. They have the form
@example
telnet://@var{user}:@var{password}@@@var{host}:@var{port}
@end example
but the @code{:@var{password}} component is ignored.
@noindent
but the @var{password} component is ignored.
To handle rlogin, telnet and tn3270 URLs, a @code{rlogin},
@code{telnet} or @code{tn3270} (the program names and arguments are
@ -553,39 +688,43 @@ Well-known ports are used if the URL does not specify a port.
@cindex ZEN IRC
@cindex ERC
@cindex rcirc
@c Fixme: reference (was http://www.w3.org/Addressing/draft-mirashi-url-irc-01.txt)
@dfn{Internet Relay Chat} (IRC) is handled by handing off the @sc{irc}
session to a function named in @code{url-irc-function}.
The @code{irc} scheme is defined in the Internet Draft at
@url{http://www.w3.org/Addressing/draft-mirashi-url-irc-01.txt} (which
was never approved as an RFC). Such URLs have the form
@example
irc://@var{host}:@var{port}/@var{target},@var{needpass}
@end example
@noindent
and are retrieved by opening an @acronym{IRC} session using the
function specified by @code{url-irc-function}.
@defopt url-irc-function
A function to actually open an IRC connection.
This function
must take five arguments, @var{host}, @var{port}, @var{channel},
@var{user} and @var{password}. The @var{channel} argument specifies the
channel to join immediately, this can be @code{nil}. By default this is
@code{url-irc-rcirc}.
The value of this option is a function, which is called to open an IRC
connection for @code{irc} URLs. This function must take five
arguments, @var{host}, @var{port}, @var{channel}, @var{user} and
@var{password}. The @var{channel} argument specifies the channel to
join immediately, and may be @code{nil}.
The default is @code{url-irc-rcirc}, which uses the Rcirc package.
Other options are @code{url-irc-erc} (which uses ERC) and
@code{url-irc-zenirc} (which uses ZenIRC).
@end defopt
@defun url-irc-rcirc host port channel user password
Processes the arguments and lets @code{rcirc} handle the session.
@end defun
@defun url-irc-erc host port channel user password
Processes the arguments and lets @code{ERC} handle the session.
@end defun
@defun url-irc-zenirc host port channel user password
Processes the arguments and lets @code{zenirc} handle the session.
@end defun
@node data
@section data
@cindex data URLs
The @code{data} scheme, defined in RFC 2397, contains MIME data in
the URL itself. Such URLs have the form
@example
data:@r{[}@var{media-type}@r{]}@r{[};@var{base64}@r{]},@var{data}
@end example
Data URLs contain MIME data in the URL itself. They are defined in
RFC 2397.
@noindent
@var{media-type} is a MIME @samp{Content-Type} string, possibly
including parameters. It defaults to
@samp{text/plain;charset=US-ASCII}. The @samp{text/plain} can be
@ -598,14 +737,14 @@ present, the @var{data} are base64-encoded.
@cindex Network File System
@cindex automounter
The @code{nfs} scheme, defined in RFC 2224, is similar to @code{ftp}
except that it points to a file on a remote host that is handled by an
NFS automounter on the local host. Such URLs have the form
@example
nfs://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file}
@end example
The @samp{nfs:} scheme is defined in RFC 2224. It is similar to
@samp{ftp:} except that it points to a file on a remote host that is
handled by the automounter on the local host.
@defvar url-nfs-automounter-directory-spec
@end defvar
A string saying how to invoke the NFS automounter. Certain @samp{%}
@ -628,15 +767,6 @@ A literal @samp{%}.
Each can be used any number of times.
@node cid
@section cid
@cindex Content-ID
RFC 2111
@node about
@section about
@node ldap
@section ldap
@cindex LDAP
@ -644,50 +774,21 @@ RFC 2111
The LDAP scheme is defined in RFC 2255.
@node imap
@section imap
@cindex IMAP
RFC 2192
@node man
@section man
@cindex @command{man}
@cindex Unix man pages
@findex man
The @code{man} scheme is a non-standard one. Such URLs have the form
@example
@samp{man:@var{page-spec}}
@end example
This is a non-standard scheme. @var{page-spec} is passed directly to
the Lisp @code{man} function.
@node Defining New URLs
@chapter Defining New URLs
@menu
* Naming conventions::
* Required functions::
* Optional functions::
* Asynchronous fetching::
* Supporting file-name-handlers::
@end menu
@node Naming conventions
@section Naming conventions
@node Required functions
@section Required functions
@node Optional functions
@section Optional functions
@node Asynchronous fetching
@section Asynchronous fetching
@node Supporting file-name-handlers
@section Supporting file-name-handlers
@noindent
and are retrieved by passing @var{page-spec} to the Lisp function
@code{man}.
@node General Facilities
@chapter General Facilities
@ -1108,11 +1209,9 @@ You can use this function to do completion of URLs from the history.
@node Customization
@chapter Customization
@section Environment Variables
@cindex environment variables
The following environment variables affect the library's operation at
startup.
The following environment variables affect the @code{url} library's
operation at startup.
@table @code
@item TMPDIR
@ -1122,10 +1221,21 @@ If this is defined, @var{url-temporary-directory} is initialized from
it.
@end table
@section General User Options
The following user options affect the general operation of
@code{url} library.
The following user options, settable with Customize, affect the
general operation of the package.
@defopt url-configuration-directory
@cindex configuration files
The value of this variable specifies the name of the directory where
the @code{url} library stores its various configuration files, cache
files, etc.
The default value specifies a subdirectory named @file{url/} in the
standard Emacs user data directory specified by the variable
@code{user-emacs-directory} (normally @file{~/.emacs.d}). However,
the old default was @file{~/.url}, and this directory is used instead
if it exists.
@end defopt
@defopt url-debug
@cindex debugging

4
etc/ERC-NEWS
View file

@ -1,8 +1,10 @@
ERC NEWS -*- outline -*-
Copyright (C) 2006-2012 Free Software Foundation, Inc.
Copyright (C) 2006-2012 Free Software Foundation, Inc.
See the end of the file for license conditions.
* For changes after ERC 5.3, see the main Emacs NEWS file
* Changes in ERC 5.3
** New function `erc-tls' is to be used for connecting to a server via TLS.

3
etc/GNUS-NEWS
View file

@ -9,6 +9,9 @@ For older news, see Gnus info node "New Features".
* New features
** New package `gnus-notifications.el' can send notifications when you
receive new messages.
** If you have the "tnef" program installed, Gnus will display ms-tnef
files, aka "winmail.dat".

189
etc/NEWS
View file

@ -150,15 +150,14 @@ autoloads have been redefined as functions).
---
*** In minibuffer filename prompts, `C-M-f' and `C-M-b' now move to the
next and previous path separator, respectively.
+++
*** minibuffer-electric-default-mode can rewrite (default ...) to [...].
Just set minibuffer-eldef-shorten-default to t before enabling the mode.
** ImageMagick support, if available, is automatically enabled.
It is no longer necessary to call `imagemagick-register-types'
explicitly to install ImageMagick image types; that function is called
automatically at startup, or when customizing a relevant imagemagick-
option.
automatically at startup, or when customizing an imagemagick- option.
+++
*** Setting `imagemagick-types-inhibit' to t now disables the use of
ImageMagick to view images. You must call imagemagick-register-types
@ -188,6 +187,7 @@ and sorted above the other "available" packages by default.
** `C-x C-q' is now bound to the new minor mode `read-only-mode'.
This minor mode replaces `toggle-read-only', which is now obsolete.
+++
** Emacs now generates backtraces on fatal errors.
On encountering a fatal error, Emacs now outputs a textual description
of the fatal signal, and a short backtrace on platforms like glibc
@ -359,13 +359,16 @@ of `symbol-function' in place forms.
A side effect is that vars without corresponding value are bound to nil
rather than making them unbound.
*** The following methods of extending `setf' are obsolete.
Use gv.el instead (FIXME; details).
`define-setf-expander', `defsetf', `define-modify-macro'
** Compilation mode
+++
*** New option `compilation-always-kill'.
*** The following methods of extending `setf' are obsolete
(use features from gv.el instead):
`define-modify-macro' (use `gv-letplace')
`defsetf' (use `gv-define-simple-setter' or `gv-define-setter')
`define-setf-expander' (use `gv-define-setter' or `gv-define-expander')
`get-setf-method' no longer exists (see "Incompatible Lisp Changes")
+++
** New compilation option `compilation-always-kill'.
** Customize
---
@ -375,10 +378,9 @@ Use gv.el instead (FIXME; details).
`customize-apropos-options' (i.e. the prefix argument does nothing for
these commands now).
** Desktop
---
*** `desktop-path' no longer includes the "." directory. Desktop
files are now located in ~/.emacs.d by default.
** `desktop-path' no longer includes the "." directory.
Desktop files are now located in ~/.emacs.d by default.
** D-Bus
@ -412,18 +414,21 @@ details.
** Diff mode
---
*** Changes are now highlighted using the same color scheme as in
modern VCSes. Deletions are displayed in red (new faces
`diff-refine-removed' and `smerge-refined-removed' and new definition
`diff-refine-removed' and `smerge-refined-removed', and new definition
of `diff-removed'), insertions in green (new faces `diff-refine-added'
and `smerge-refined-added' and new definition of `diff-added').
and `smerge-refined-added', and new definition of `diff-added').
---
*** The variable `diff-use-changed-face' defines whether to use the
face `diff-changed', or `diff-removed' and `diff-added' to highlight
changes in context diffs.
*** The new command `diff-remove-trailing-whitespace' fixes trailing
whitespace problems introduced by the diff.
+++
*** The new command `diff-delete-trailing-whitespace' removes trailing
whitespace introduced by a diff.
** Dired
+++
@ -449,37 +454,34 @@ The global binding for `M-=', `count-words-region' is in effect.
---
** Ediff now uses the same color scheme as Diff mode.
** erc will look up server/channel names via auth-source and use the
channel keys found, if any.
** ERC
*** New package `erc-desktop-notifications.el', which can send a notification
when you receive a private message or your nickname is mentioned.
*** ERC will look up server/channel names via auth-source and use any
channel keys found.
** Flymake uses fringe bitmaps to indicate errors and warnings.
See `flymake-fringe-indicator-position', `flymake-error-bitmap' and
`flymake-warning-bitmap'.
** Follow mode
---
*** The obsolete variable `follow-mode-off-hook' has been removed.
---
*** Follow mode no longer works by using advice.
** Follow mode no longer works by using advice.
The option `follow-intercept-processes' has been removed.
** FFAP
*** The option `ffap-url-unwrap-remote' can now be a list of strings,
** The FFAP option `ffap-url-unwrap-remote' can now be a list of strings,
specifying URL types which should be converted to remote file names at
the FFAP prompt. The default is now '("ftp").
** Generic-x
`javascript-generic-mode' is now an obsolete alias for `js-mode'.
** Ibuffer
*** New `derived-mode' filter, bound to `/ M'.
** New Ibuffer `derived-mode' filter, bound to `/ M'.
The old binding for `/ M' (filter by used-mode) is now bound to `/ m'.
** Mouse Avoidance mode
---
** `javascript-generic-mode' is now an obsolete alias for `js-mode'.
+++
*** New variable `mouse-avoidance-banish-position' specifies where the
** New option `mouse-avoidance-banish-position' specifies where the
`banish' mouse avoidance setting moves the mouse.
+++
@ -547,37 +549,28 @@ python-send-string | python-shell-send-string
python-switch-to-python | python-shell-switch-to-shell
python-describe-symbol | python-eldoc-at-point
---
** reStructuredText mode
*** Rebind nearly all keys making room for more keys and complying
better to usage in other modes. Describe bindings with C-c C-h.
*** Keybindings (see `C-c C-h'), TAB indentation, filling and auto-filling,
fontification, comment handling, and customization have all been revised
and improved.
*** Major revision of indentation working very similar to other
modes. TAB is your friend.
*** Support for `imenu' and `which-function-mode'.
*** Major revision of filling working fine with most of
reStructuredText syntax. Support auto-filling.
*** Major revision of comment handling.
*** Major revision of fontification working with `jit-lock-mode'.
*** Cover reStructuredText syntax more closely. Improve
the experience for Sphinx users.
*** The reStructuredText syntax is more closely covered.
Sphinx support has been improved.
*** `rst-insert-list' inserts new list or continues existing lists.
*** Extend correct and improve customization.
*** A negative prefix argument always works for `rst-adjust'.
*** Negative prefix argument always works for `rst-adjust'.
*** The window configuration is reset after displaying a TOC.
*** Reset window configuration after displaying TOC.
*** The constant `rst-version' describes the rst.el package version.
*** Package version in `rst-version'.
*** Support `imenu' and `which-func'.
** SH Script mode
---
** Shell Script mode
*** Pairing of parens/quotes uses electric-pair-mode instead of skeleton-pair.
@ -585,49 +578,45 @@ the experience for Sphinx users.
*** `sh-use-smie' lets you choose a new indentation and navigation code.
** Shell
*** New option `async-shell-command-buffer' specifies what buffer to use
** New option `async-shell-command-buffer' specifies the buffer to use
for a new asynchronous shell command when the default output buffer
`*Async Shell Command*' is already taken by another running command.
** SQL Mode
*** DB2 added `sql-db2-escape-newlines'
`*Async Shell Command*' is already in use.
---
** SQL mode has a new option `sql-db2-escape-newlines'.
If non-nil, newlines sent to the command interpreter will be escaped
by a backslash. The default does not escape the newlines and assumes
that the sql statement will be terminated by a semicolon.
** Tabulated List and packages derived from it
+++
*** New command `tabulated-list-sort', bound to `S', sorts the column
at point, or the Nth column if a numeric prefix argument is given.
** Term
The variables `term-default-fg-color' and `term-default-bg-color' are
now deprecated in favor of the `term-face' face, that you can
customize. Also, it is now possible to customize how are displayed the
ANSI terminal colors and styles by customizing the corresponding
`term-color-<COLOR>', `term-color-underline' and `term-color-bold'
faces.
+++
*** The variables `term-default-fg-color' and `term-default-bg-color' are
now deprecated in favor of the customizable face `term'.
+++
*** You can customize how to display ANSI terminal colors and styles
by customizing the corresponding `term-color-<COLOR>',
`term-color-underline' and `term-color-bold' faces.
** Tramp
+++
*** The syntax has been extended in order to allow ad-hoc proxy
definitions. See the manual for details.
*** The syntax has been extended in order to allow ad-hoc proxy definitions.
See the manual for details.
+++
*** Remote processes are now supported also on remote Windows host.
** URL
+++
*** Structs made by `url-generic-parse-url' have nil `attributes' slot.
Previously, this slot stored semicolon-separated attribute-value pairs
appended to some imap URLs, but this is not compatible with RFC 3986.
So now the `filename' slot stores the entire path and query components
and the `attributes' slot is always nil.
+++
*** New function `url-encode-url' for encoding a URI string.
The `url-retrieve' function now uses this to encode its URL argument,
in case that is not properly encoded.
@ -643,9 +632,8 @@ in case that is not properly encoded.
*** Accepts \r and \f as whitespace.
** Which Function mode
+++
*** `which-func-modes' now defaults to t, so Which Function mode, when
** `which-func-modes' now defaults to t, so Which Function mode, when
enabled, applies to all applicable major modes.
---
@ -686,6 +674,8 @@ And in any case it's just a terrible package: ugly semantics, terrible
inefficiency, and not namespace-clean.
---
*** bruce.el
+++
*** cust-print.el
---
*** ledit.el
---
@ -694,14 +684,6 @@ inefficiency, and not namespace-clean.
*** mouse-sel.el
---
*** patcomp.el
+++
*** cust-print.el
* New Modes and Packages in Emacs 24.3
FIXME? erc-desktop-notifications.el, gv.el, profiler.el,
gnus-notifications.el, mm-archive.el
* Incompatible Lisp Changes in Emacs 24.3
@ -720,6 +702,7 @@ sequence in later calls.
font name as a string. Whether it returns a font spec or a font name
depends on the graphical library.
+++
** If the NEWTEXT arg to `replace-match' contains a substring "\?",
that substring is inserted literally even if the LITERAL arg is
non-nil, instead of causing an error to be signaled.
@ -745,6 +728,13 @@ third argument is a frame (that usage was obsolete since Emacs 22.2).
but keywords or keyword-string pairs. The old argument list will
still be supported for Emacs 24.x.
+++
** The CL package's `get-setf-method' function no longer exists.
Generalized variables are now part of core Emacs Lisp, and implemented
differently to the way cl.el used to do it. It is not possible to
define a compatible replacement for `get-setf-method'. See the file
gv.el for internal details of the new implementation.
** Spelling changes.
Some Lisp symbols have been renamed to avoid problems with spelling
that is incorrect or inconsistent with how Emacs normally spells a word.
@ -776,16 +766,18 @@ are deprecated and will be removed eventually.
deactivate-current-input-method-function
+++
** Some obsolete functions, variables, and faces were removed:
** Some obsolete functions, variables, and faces have been removed:
*** `last-input-char', `last-command-char', `unread-command-char'
*** `facemenu-unlisted-faces'
*** `rmail-decode-mime-charset'
*** `last-input-char', `last-command-char', `unread-command-char'.
*** `iswitchb-read-buffer'
*** `sc-version', `sc-submit-bug-report'
*** `set-char-table-default'
*** `string-to-sequence' (use `string-to-list' or `string-to-vector').
*** `string-to-sequence' (use `string-to-list' or `string-to-vector')
*** `compile-internal'
*** `modeline'
*** `mode-line-inverse-video'
*** `follow-mode-off-hook'
*** `cvs-commit-buffer-require-final-newline'
(use `log-edit-require-final-newline' instead)
*** `cvs-changelog-full-paragraphs'
@ -794,18 +786,20 @@ are deprecated and will be removed eventually.
*** `vc-ignore-vc-files' (use `vc-handled-backends' instead)
*** `vc-master-templates' (use `vc-handled-backends' instead)
*** `vc-checkout-carefully'
*** `modeline'
* Lisp changes in Emacs 24.3
** New sampling-based Elisp profiler.
Try M-x profiler-start ... M-x profiler-stop; and then M-x profiler-report.
The sampling rate can be based on CPU time (only supported on some
systems), or based on memory allocations.
Try M-x profiler-start, do some work, and then call M-x profiler-report.
When finished, use M-x profiler-stop. The sampling rate can be based on
CPU time (only supported on some systems) or memory allocations.
+++
** CL-style generalized variables are now in core Elisp.
`setf' is autoloaded; `push' and `pop' accept generalized variables.
You can define your own generalized variables using `gv-define-simple-setter',
`gv-define-setter', etc.
+++
** `defun' also accepts a (declare DECLS) form, like `defmacro'.
@ -837,7 +831,7 @@ These do not trigger the debugger.
*** Set `debug-on-message' to enter the debugger when a certain
message is displayed in the echo area. This can be useful when trying
to work out which code is doing something.
---
*** New var `inhibit-debugger', automatically set to prevent accidental
recursive invocations.
@ -845,7 +839,7 @@ recursive invocations.
+++
*** The functions get-lru-window, get-mru-window and get-largest-window
now accept a third argument to avoid choosing the selected window.
+++
*** Additional values recognized for option `window-combination-limit'.
*** New macro `with-temp-buffer-window'.
@ -931,9 +925,9 @@ describing the cycle.
** Miscellaneous new functions:
+++
*** `autoloadp'
*** `autoloadp' tests if its argument is an autoloaded object.
+++
*** `autoload-do-load'
*** `autoload-do-load' performs the autoloading operation.
+++
*** `buffer-narrowed-p' tests if the buffer is narrowed.
+++
@ -950,6 +944,7 @@ describing the cycle.
+++
*** `tty-top-frame' returns the topmost frame of a text terminal.
+++
** New macros `setq-local' and `defvar-local'.
+++
@ -960,13 +955,13 @@ See the "Face Attributes" section of the Elisp manual.
** The following functions and variables are obsolete:
---
*** `automount-dir-prefix'
*** `automount-dir-prefix' (use `directory-abbrev-alist')
+++
*** `buffer-has-markers-at'
---
*** `macro-declaration-function' (use `macro-declarations-alist')
---
*** `window-system-version'
*** `window-system-version' (provides no useful information)
---
*** `dired-pop-to-buffer' (use `dired-mark-pop-up')
---

75
lisp/ChangeLog
View file

@ -1,3 +1,78 @@
2012-11-10 Glenn Morris <rgm@gnu.org>
* term.el (term-default-fg-color, term-default-bg-color):
Make obsolete, rather than just saying "deprecated" in the doc.
* term.el (term): Rename from `term-face'.
(term-current-face, ansi-term-color-vector)
(term-default-fg-color, term-default-bg-color, term-ansi-reset):
Update all users.
2012-11-10 Jan Djärv <jan.h.d@swipnet.se>
* server.el (server-create-window-system-frame): Handle Nextstep
specially (Bug#12780).
2012-11-10 Glenn Morris <rgm@gnu.org>
* mail/emacsbug.el (report-emacs-bug-query-existing-bugs):
Unautoload, and make obsolete. (Bug#7449)
2012-11-10 Chong Yidong <cyd@gnu.org>
* vc/diff-mode.el (diff-delete-trailing-whitespace): Rewrite, and
rename from diff-remove-trailing-whitespace (Bug#12831).
2012-11-10 Stefan Monnier <monnier@iro.umontreal.ca>
* emacs-lisp/advice.el: Require `cl-lib' at run-time to fix
miscompilation of trace.el.
2012-11-10 Glenn Morris <rgm@gnu.org>
* vc/diff-mode.el (diff-remove-trailing-whitespace): Doc fix.
2012-11-10 Stefan Monnier <monnier@iro.umontreal.ca>
* emacs-lisp/gv.el (gv-define-simple-setter): Fix last change
(bug#12812).
2012-11-10 Chong Yidong <cyd@gnu.org>
* minibuf-eldef.el (minibuffer-eldef-shorten-default): Convert to
a defcustom with an appropriate :set function.
(minibuffer-default--in-prompt-regexps): New function.
2012-11-10 Glenn Morris <rgm@gnu.org>
* emacs-lisp/cl.el (define-setf-expander, defsetf)
(define-modify-macro): Doc fixes.
* emacs-lisp/gv.el (gv-letplace): Fix doc typo.
(gv-define-simple-setter): Update doc of `fix-return'.
2012-11-10 Stefan Monnier <monnier@iro.umontreal.ca>
* emacs-lisp/gv.el (gv-define-simple-setter): Don't evaluate `val'
twice when `fix-return' is set (bug#12813).
* emacs-lisp/cl.el (defsetf): Pass the third arg to
gv-define-simple-setter (bug#12812).
* woman.el (woman-decode-region): Disable adaptive-fill when rendering
(bug#12756).
2012-11-10 Glenn Morris <rgm@gnu.org>
* emacs-lisp/gv.el (gv-define-setter): Fix doc typo.
* emacs-lisp/cl-extra.el (cl-prettyexpand):
* emacs-lisp/cl-lib.el (cl-proclaim, cl-declaim):
* emacs-lisp/cl-macs.el (cl-destructuring-bind, cl-locally)
(cl-the, cl-compiler-macroexpand): Add basic doc strings.
* emacs-lisp/cl-extra.el (cl-maplist, cl-mapcan): Doc fix.
2012-11-10 Leo Liu <sdl.web@gmail.com>
* ido.el (ido-set-matches-1): Improve flex matching performance by

3
lisp/emacs-lisp/advice.el
View file

@ -1709,7 +1709,8 @@
;; During a normal load this is a noop:
(require 'advice-preload "advice.el")
(require 'macroexp)
(eval-when-compile (require 'cl-lib))
;; At run-time also, since ad-do-advised-functions returns code that uses it.
(require 'cl-lib)
;; @@ Variable definitions:
;; ========================

7
lisp/emacs-lisp/cl-extra.el
View file

@ -131,7 +131,7 @@ TYPE is the sequence type to return.
;;;###autoload
(defun cl-maplist (cl-func cl-list &rest cl-rest)
"Map FUNCTION to each sublist of LIST or LISTs.
Like `mapcar', except applies to lists and their cdr's rather than to
Like `cl-mapcar', except applies to lists and their cdr's rather than to
the elements themselves.
\n(fn FUNCTION LIST...)"
(if cl-rest
@ -170,7 +170,7 @@ the elements themselves.
;;;###autoload
(defun cl-mapcan (cl-func cl-seq &rest cl-rest)
"Like `mapcar', but nconc's together the values returned by the function.
"Like `cl-mapcar', but nconc's together the values returned by the function.
\n(fn FUNCTION SEQUENCE...)"
(apply 'nconc (apply 'cl-mapcar cl-func cl-seq cl-rest)))
@ -675,6 +675,9 @@ PROPLIST is a list of the sort returned by `symbol-plist'.
;;;###autoload
(defun cl-prettyexpand (form &optional full)
"Expand macros in FORM and insert the pretty-printed result.
Optional argument FULL non-nil means to expand all macros,
including `cl-block' and `cl-eval-when'."
(message "Expanding...")
(let ((cl--compiling-file full)
(byte-compile-macro-environment nil))

7
lisp/emacs-lisp/cl-lib.el
View file

@ -251,12 +251,17 @@ one value.
(defvar cl-proclaims-deferred nil)
(defun cl-proclaim (spec)
"Record a global declaration specified by SPEC."
(if (fboundp 'cl-do-proclaim) (cl-do-proclaim spec t)
(push spec cl-proclaims-deferred))
nil)
(defmacro cl-declaim (&rest specs)
(let ((body (mapcar (function (lambda (x) (list 'cl-proclaim (list 'quote x))))
"Like `cl-proclaim', but takes any number of unevaluated, unquoted arguments.
Puts `(cl-eval-when (compile load eval) ...)' around the declarations
so that they are registered at compile-time as well as run-time."
(let ((body (mapcar (function (lambda (x)
(list 'cl-proclaim (list 'quote x))))
specs)))
(if (cl--compiling-file) (cl-list* 'cl-eval-when '(compile load eval) body)
(cons 'progn body)))) ; avoid loading cl-macs.el for cl-eval-when

7
lisp/emacs-lisp/cl-macs.el
View file

@ -554,6 +554,7 @@ its argument list allows full Common Lisp conventions."
;;;###autoload
(defmacro cl-destructuring-bind (args expr &rest body)
"Bind the variables in ARGS to the result of EXPR and execute BODY."
(declare (indent 2)
(debug (&define cl-macro-list def-form cl-declarations def-body)))
(let* ((cl--bind-lets nil) (cl--bind-forms nil) (cl--bind-inits nil)
@ -1886,10 +1887,12 @@ values. For compatibility, (cl-values A B C) is a synonym for (list A B C).
;;;###autoload
(defmacro cl-locally (&rest body)
"Equivalent to `progn'."
(declare (debug t))
(cons 'progn body))
;;;###autoload
(defmacro cl-the (_type form)
"At present this ignores _TYPE and is simply equivalent to FORM."
(declare (indent 1) (debug (cl-type-spec form)))
form)
@ -2537,6 +2540,10 @@ and then returning foo."
;;;###autoload
(defun cl-compiler-macroexpand (form)
"Like `macroexpand', but for compiler macros.
Expands FORM repeatedly until no further expansion is possible.
Returns FORM unchanged if it has no compiler macro, or if it has a
macro that returns its `&whole' argument."
(while
(let ((func (car-safe form)) (handler nil))
(while (and (symbolp func)

54
lisp/emacs-lisp/cl.el
View file

@ -547,13 +547,15 @@ deprecated usage of `symbol-function' in place forms)." ; bug#12760
(defmacro define-setf-expander (name arglist &rest body)
"Define a `setf' method.
This method shows how to handle `setf's to places of the form (NAME ARGS...).
The argument forms ARGS are bound according to ARGLIST, as if NAME were
going to be expanded as a macro, then the BODY forms are executed and must
return a list of five elements: a temporary-variables list, a value-forms
list, a store-variables list (of length one), a store-form, and an access-
form. See `gv-define-expander', `gv-define-setter', and `gv-define-expander'
for a better and simpler ways to define setf-methods."
This method shows how to handle `setf's to places of the form
\(NAME ARGS...). The argument forms ARGS are bound according to
ARGLIST, as if NAME were going to be expanded as a macro, then
the BODY forms are executed and must return a list of five elements:
a temporary-variables list, a value-forms list, a store-variables list
\(of length one), a store-form, and an access- form.
See `gv-define-expander', and `gv-define-setter' for better and
simpler ways to define setf-methods."
(declare (debug
(&define name cl-lambda-list cl-declarations-or-string def-body)))
`(progn
@ -566,23 +568,31 @@ for a better and simpler ways to define setf-methods."
(defmacro defsetf (name arg1 &rest args)
"Define a `setf' method.
This macro is an easy-to-use substitute for `define-setf-expander' that works
well for simple place forms. In the simple `defsetf' form, `setf's of
the form (setf (NAME ARGS...) VAL) are transformed to function or macro
calls of the form (FUNC ARGS... VAL). Example:
This macro is an easy-to-use substitute for `define-setf-expander'
that works well for simple place forms.
In the simple `defsetf' form, `setf's of the form (setf (NAME
ARGS...) VAL) are transformed to function or macro calls of the
form (FUNC ARGS... VAL). For example:
(defsetf aref aset)
You can replace this form with `gv-define-simple-setter'.
Alternate form: (defsetf NAME ARGLIST (STORE) BODY...).
Here, the above `setf' call is expanded by binding the argument forms ARGS
according to ARGLIST, binding the value form VAL to STORE, then executing
BODY, which must return a Lisp form that does the necessary `setf' operation.
Actually, ARGLIST and STORE may be bound to temporary variables which are
introduced automatically to preserve proper execution order of the arguments.
Example:
Here, the above `setf' call is expanded by binding the argument
forms ARGS according to ARGLIST, binding the value form VAL to
STORE, then executing BODY, which must return a Lisp form that
does the necessary `setf' operation. Actually, ARGLIST and STORE
may be bound to temporary variables which are introduced
automatically to preserve proper execution order of the arguments.
For example:
(defsetf nth (n x) (v) `(setcar (nthcdr ,n ,x) ,v))
You can replace this form with `gv-define-setter'.
\(fn NAME [FUNC | ARGLIST (STORE) BODY...])"
(declare (debug
(&define name
@ -597,7 +607,7 @@ Example:
(cl-function
(lambda (,@(car args) ,@arg1) ,@(cdr args)))
do args)))
`(gv-define-simple-setter ,name ,arg1)))
`(gv-define-simple-setter ,name ,arg1 ,(car args))))
;; FIXME: CL used to provide a setf method for `apply', but I haven't been able
;; to find a case where it worked. The code below tries to handle it as well.
@ -639,8 +649,12 @@ Example:
(defmacro define-modify-macro (name arglist func &optional doc)
"Define a `setf'-like modify macro.
If NAME is called, it combines its PLACE argument with the other arguments
from ARGLIST using FUNC: (define-modify-macro incf (&optional (n 1)) +)"
If NAME is called, it combines its PLACE argument with the other
arguments from ARGLIST using FUNC. For example:
(define-modify-macro incf (&optional (n 1)) +)
You can replace this macro with `gv-letplace'."
(declare (debug
(&define name cl-lambda-list ;; should exclude &key
symbolp &optional stringp)))

17
lisp/emacs-lisp/gv.el
View file

@ -111,7 +111,7 @@ DO must return an Elisp expression."
GETTER will be bound to a copyable expression that returns the value
of PLACE.
SETTER will be bound to a function that takes an expression V and returns
and new expression that sets PLACE to V.
a new expression that sets PLACE to V.
BODY should return some Elisp expression E manipulating PLACE via GETTER
and SETTER.
The returned value will then be an Elisp expression that first evaluates
@ -194,7 +194,7 @@ well for simple place forms.
Assignments of VAL to (NAME ARGS...) are expanded by binding the argument
forms (VAL ARGS...) according to ARGLIST, then executing BODY, which must
return a Lisp form that does the assignment.
The first arg in ARLIST (the one that receives VAL) receives an expression
The first arg in ARGLIST (the one that receives VAL) receives an expression
which can do arbitrary things, whereas the other arguments are all guaranteed
to be pure and copyable. Example use:
(gv-define-setter aref (v a i) `(aset ,a ,i ,v))"
@ -209,13 +209,20 @@ to be pure and copyable. Example use:
This macro is an easy-to-use substitute for `gv-define-expander' that works
well for simple place forms. Assignments of VAL to (NAME ARGS...) are
turned into calls of the form (SETTER ARGS... VAL).
If FIX-RETURN is non-nil, then SETTER is not assumed to return VAL and
instead the assignment is turned into (prog1 VAL (SETTER ARGS... VAL))
instead the assignment is turned into something equivalent to
\(let ((temp VAL))
(SETTER ARGS... temp)
temp)
so as to preserve the semantics of `setf'."
(declare (debug (sexp (&or symbolp lambda-expr) &optional sexp)))
(let ((set-call `(cons ',setter (append args (list val)))))
`(gv-define-setter ,name (val &rest args)
,(if fix-return `(list 'prog1 val ,set-call) set-call))))
,(if fix-return
`(macroexp-let2 nil v val
(cons ',setter (append args (list v)))
v)
`(cons ',setter (append args (list val))))))
;;; Typical operations on generalized variables.

3
lisp/mail/emacsbug.el
View file

@ -517,7 +517,6 @@ and send the mail again%s."
buglist))))
(report-emacs-bug-create-existing-bugs-buffer (nreverse buglist) keywords)))
;;;###autoload
(defun report-emacs-bug-query-existing-bugs (keywords)
"Query for KEYWORDS at `report-emacs-bug-tracker-url', and return the result.
The result is an alist with items of the form (URL SUBJECT NO)."
@ -527,6 +526,8 @@ The result is an alist with items of the form (URL SUBJECT NO)."
(replace-regexp-in-string "[[:space:]]+" "+" keywords)
";package=emacs")
'report-emacs-bug-parse-query-results (list keywords)))
(make-obsolete 'report-emacs-bug-query-existing-bugs
"use the `debbugs' package from GNU ELPA instead." "24.3")
(provide 'emacsbug)

20
lisp/minibuf-eldef.el
View file

@ -33,13 +33,25 @@
;;; Code:
(defvar minibuffer-eldef-shorten-default nil
"If non-nil, shorten \"(default ...)\" to \"[...]\" in minibuffer prompts.")
(defvar minibuffer-eldef-shorten-default)
(defvar minibuffer-default-in-prompt-regexps
(defun minibuffer-default--in-prompt-regexps ()
`(("\\( (default\\(?: is\\)? \\(.*\\))\\):? \\'"
1 ,(if minibuffer-eldef-shorten-default " [\\2]"))
("\\( \\[.*\\]\\):? *\\'" 1))
("\\( \\[.*\\]\\):? *\\'" 1)))
(defcustom minibuffer-eldef-shorten-default nil
"If non-nil, shorten \"(default ...)\" to \"[...]\" in minibuffer prompts."
:set (lambda (symbol value)
(set-default symbol value)
(setq-default minibuffer-default-in-prompt-regexps
(minibuffer-default--in-prompt-regexps)))
:type 'boolean
:group 'minibuffer
:version "24.3")
(defvar minibuffer-default-in-prompt-regexps
(minibuffer-default--in-prompt-regexps)
"A list of regexps matching the parts of minibuffer prompts showing defaults.
When `minibuffer-electric-default-mode' is active, these regexps are
used to identify the portions of prompts to elide.

9
lisp/server.el
View file

@ -842,6 +842,15 @@ This handles splitting the command if it would be bigger than
(unless (assq w window-system-initialization-alist)
(setq w nil))
;; Special case for ns. This is because DISPLAY may not be set at all
;; which in the ns case isn't an error. The variable display then becomes
;; the fully qualified hostname, which make-frame-on-display below
;; does not understand and throws an error.
;; It may also be a valid X display, but if Emacs is compiled for ns, it
;; can not make X frames.
(if (featurep 'ns-win)
(setq w 'ns display "ns"))
(cond (w
;; Flag frame as client-created, but use a dummy client.
;; This will prevent the frame from being deleted when

18
lisp/term.el
View file

@ -452,7 +452,7 @@ state 4: term-terminal-parameter contains pending output.")
"A queue of strings whose echo we want suppressed.")
(defvar term-terminal-parameter)
(defvar term-terminal-previous-parameter)
(defvar term-current-face 'term-face)
(defvar term-current-face 'term)
(defvar term-scroll-start 0 "Top-most line (inclusive) of scrolling region.")
(defvar term-scroll-end) ; Number of line (zero-based) after scrolling region.
(defvar term-pager-count nil
@ -759,7 +759,7 @@ Buffer local variable.")
;;; Faces
(defvar ansi-term-color-vector
[term-face
[term
term-color-black
term-color-red
term-color-green
@ -770,18 +770,20 @@ Buffer local variable.")
term-color-white])
(defcustom term-default-fg-color nil
"If non-nil, default color for foreground in Term mode.
This is deprecated in favor of customizing the `term-face' face."
"If non-nil, default color for foreground in Term mode."
:group 'term
:type 'string)
(make-obsolete-variable 'term-default-fg-color "use the face `term' instead."
"24.3")
(defcustom term-default-bg-color nil
"If non-nil, default color for foreground in Term mode.
This is deprecated in favor of customizing the `term-face' face."
"If non-nil, default color for foreground in Term mode."
:group 'term
:type 'string)
(make-obsolete-variable 'term-default-bg-color "use the face `term' instead."
"24.3")
(defface term-face
(defface term
`((t
:foreground ,term-default-fg-color
:background ,term-default-bg-color
@ -988,7 +990,7 @@ is buffer-local."
dt))
(defun term-ansi-reset ()
(setq term-current-face 'term-face)
(setq term-current-face 'term)
(setq term-ansi-current-underline nil)
(setq term-ansi-current-bold nil)
(setq term-ansi-current-reverse nil)

96
lisp/vc/diff-mode.el
View file

@ -178,7 +178,7 @@ when editing big diffs)."
["Unified -> Context" diff-unified->context
:help "Convert unified diffs to context diffs"]
;;["Fixup Headers" diff-fixup-modifs (not buffer-read-only)]
["Remove trailing whitespace" diff-remove-trailing-whitespace
["Remove trailing whitespace" diff-delete-trailing-whitespace
:help "Remove trailing whitespace problems introduced by the diff"]
["Show trailing whitespace" whitespace-mode
:style toggle :selected (bound-and-true-p whitespace-mode)
@ -2048,35 +2048,71 @@ I.e. like `add-change-log-entry-other-window' but applied to all hunks."
;; When there's no more hunks, diff-hunk-next signals an error.
(error nil))))
(defun diff-remove-trailing-whitespace ()
"When on a buffer that contains a diff, inspects the
differences and removes trailing whitespace (spaces, tabs) from
the lines modified or introduced by this diff. Shows a message
with the name of the altered buffers, which are unsaved. If a
file referenced on the diff has no buffer and needs to be fixed,
a buffer visiting that file is created."
(interactive)
;; We assume that the diff header has no trailing whitespace.
(let ((modified-buffers nil))
(save-excursion
(goto-char (point-min))
(while (re-search-forward "^[+!>].*[ \t]+$" (point-max) t)
(pcase-let ((`(,buf ,line-offset ,pos ,src ,_dst ,_switched)
(diff-find-source-location t t)))
(when line-offset
(with-current-buffer buf
(save-excursion
(goto-char (+ (car pos) (cdr src)))
(beginning-of-line)
(when (re-search-forward "\\([ \t]+\\)$" (line-end-position) t)
(unless (memq buf modified-buffers)
(push buf modified-buffers))
(replace-match ""))))))))
(if modified-buffers
(message "Deleted new trailing whitespace from: %s"
(mapconcat (lambda (buf) (concat "`" (buffer-name buf) "'"))
modified-buffers " "))
(message "No trailing whitespace fixes needed."))))
(defun diff-delete-trailing-whitespace (&optional other-file)
"Remove trailing whitespace from lines modified in this diff.
This edits both the current Diff mode buffer and the patched
source file(s). If `diff-jump-to-old-file' is non-nil, edit the
original (unpatched) source file instead. With a prefix argument
OTHER-FILE, flip the choice of which source file to edit.
If a file referenced in the diff has no buffer and needs to be
fixed, visit it in a buffer."
(interactive "P")
(save-excursion
(goto-char (point-min))
(let* ((other (diff-xor other-file diff-jump-to-old-file))
(modified-buffers nil)
(style (save-excursion
(when (re-search-forward diff-hunk-header-re nil t)
(goto-char (match-beginning 0))
(diff-hunk-style))))
(regexp (concat "^[" (if other "-<" "+>") "!]"
(if (eq style 'context) " " "")
".*?\\([ \t]+\\)$"))
(inhibit-read-only t)
(end-marker (make-marker))
hunk-end)
;; Move to the first hunk.
(re-search-forward diff-hunk-header-re nil 1)
(while (progn (save-excursion
(re-search-forward diff-hunk-header-re nil 1)
(setq hunk-end (point)))
(< (point) hunk-end))
;; For context diffs, search only in the appropriate half of
;; the hunk. For other diffs, search within the entire hunk.
(if (not (eq style 'context))
(set-marker end-marker hunk-end)
(let ((mid-hunk
(save-excursion
(re-search-forward diff-context-mid-hunk-header-re hunk-end)
(point))))
(if other
(set-marker end-marker mid-hunk)
(goto-char mid-hunk)
(set-marker end-marker hunk-end))))
(while (re-search-forward regexp end-marker t)
(let ((match-data (match-data)))
(pcase-let ((`(,buf ,line-offset ,pos ,src ,_dst ,_switched)
(diff-find-source-location other-file)))
(when line-offset
;; Remove the whitespace in the Diff mode buffer.
(set-match-data match-data)
(replace-match "" t t nil 1)
;; Remove the whitespace in the source buffer.
(with-current-buffer buf
(save-excursion
(goto-char (+ (car pos) (cdr src)))
(beginning-of-line)
(when (re-search-forward "\\([ \t]+\\)$" (line-end-position) t)
(unless (memq buf modified-buffers)
(push buf modified-buffers))
(replace-match ""))))))))
(goto-char hunk-end))
(if modified-buffers
(message "Deleted trailing whitespace from %s."
(mapconcat (lambda (buf) (concat "`" (buffer-name buf) "'"))
modified-buffers ", "))
(message "No trailing whitespace to delete.")))))
;; provide the package
(provide 'diff-mode)

4
lisp/woman.el
View file

@ -2253,7 +2253,9 @@ Currently set only from '\" t in the first line of the source file.")
(set-face-font 'woman-symbol woman-symbol-font
(and (frame-live-p woman-frame) woman-frame)))
;; Set syntax and display tables:
(setq-local adaptive-fill-mode nil) ; No special "%" "#" etc filling.
;; Set syntax and display tables:
(set-syntax-table woman-syntax-table)
(woman-set-buffer-display-table)

21
src/ChangeLog
View file

@ -1,3 +1,24 @@
2012-11-10 Martin Rudalics <rudalics@gmx.at>
* window.c (Fsplit_window_internal): Set combination limit of
new parent window to t iff Vwindow_combination_limit is t;
fixing a regression introduced with the change from 2012-09-22.
(Fset_window_combination_limit): Fix doc-string.
2012-11-10 Eli Zaretskii <eliz@gnu.org>
* xdisp.c (try_scrolling): Fix correction of aggressive-scroll
amount when the scroll margins are too large. When scrolling
backwards in the buffer, give up if cannot reach point or the
scroll margin within a reasonable number of screen lines. Fixes
point position in window under scroll-up/down-aggressively when
point is positioned many lines beyond the window top/bottom.
(Bug#12811)
* ralloc.c (relinquish): If real_morecore fails to return memory
to the system, don't crash; instead, leave the last heap
unchanged and return. (Bug#12774)
2012-11-09 Stefan Monnier <monnier@iro.umontreal.ca>
* lisp.h (AUTOLOADP): New macro.

34
src/ralloc.c
View file

@ -327,6 +327,8 @@ relinquish (void)
if ((char *)last_heap->end - (char *)last_heap->bloc_start <= excess)
{
heap_ptr lh_prev;
/* This heap should have no blocs in it. If it does, we
cannot return it to the system. */
if (last_heap->first_bloc != NIL_BLOC
@ -335,28 +337,26 @@ relinquish (void)
/* Return the last heap, with its header, to the system. */
excess = (char *)last_heap->end - (char *)last_heap->start;
last_heap = last_heap->prev;
last_heap->next = NIL_HEAP;
lh_prev = last_heap->prev;
/* If the system doesn't want that much memory back, leave
last_heap unaltered to reflect that. This can occur if
break_value is still within the original data segment. */
if ((*real_morecore) (- excess) != 0)
{
last_heap = lh_prev;
last_heap->next = NIL_HEAP;
}
}
else
{
excess = (char *) last_heap->end
- (char *) ROUNDUP ((char *)last_heap->end - excess);
last_heap->end = (char *) last_heap->end - excess;
}
if ((*real_morecore) (- excess) == 0)
{
/* If the system didn't want that much memory back, adjust
the end of the last heap to reflect that. This can occur
if break_value is still within the original data segment. */
last_heap->end = (char *) last_heap->end + excess;
/* Make sure that the result of the adjustment is accurate.
It should be, for the else clause above; the other case,
which returns the entire last heap to the system, seems
unlikely to trigger this mode of failure. */
if (last_heap->end != (*real_morecore) (0))
emacs_abort ();
/* If the system doesn't want that much memory back, leave
the end of the last heap unchanged to reflect that. This
can occur if break_value is still within the original
data segment. */
if ((*real_morecore) (- excess) != 0)
last_heap->end = (char *) last_heap->end - excess;
}
}
}

13
src/window.c
View file

@ -618,11 +618,13 @@ internal windows only. */)
DEFUN ("set-window-combination-limit", Fset_window_combination_limit, Sset_window_combination_limit, 2, 2, 0,
doc: /* Set combination limit of window WINDOW to LIMIT; return LIMIT.
WINDOW must be a valid window and defaults to the selected one.
If LIMIT is nil, child windows of WINDOW can be recombined with WINDOW's
siblings. LIMIT t means that child windows of WINDOW are never
\(re-)combined with WINDOW's siblings. Other values are reserved for
future use. */)
future use.
WINDOW must be a valid window. Setting the combination limit is
meaningful for internal windows only. */)
(Lisp_Object window, Lisp_Object limit)
{
wset_combination_limit (decode_valid_window (window), limit);
@ -3869,9 +3871,10 @@ set correctly. See the code of `split-window' for how this is done. */)
make_parent_window (old, horflag);
p = XWINDOW (o->parent);
/* Store t in the new parent's combination_limit slot to avoid
that its children get merged into another window. */
wset_combination_limit (p, Qt);
if (EQ (Vwindow_combination_limit, Qt))
/* Store t in the new parent's combination_limit slot to avoid
that its children get merged into another window. */
wset_combination_limit (p, Qt);
/* These get applied below. */
wset_new_total (p, horflag ? o->total_cols : o->total_lines);
wset_new_normal (p, new_normal);

40
src/xdisp.c
View file

@ -14786,13 +14786,18 @@ try_scrolling (Lisp_Object window, int just_this_one_p,
if (NUMBERP (aggressive))
{
double float_amount = XFLOATINT (aggressive) * height;
amount_to_scroll = float_amount;
if (amount_to_scroll == 0 && float_amount > 0)
amount_to_scroll = 1;
int aggressive_scroll = float_amount;
if (aggressive_scroll == 0 && float_amount > 0)
aggressive_scroll = 1;
/* Don't let point enter the scroll margin near top of
the window. */
if (amount_to_scroll > height - 2*this_scroll_margin + dy)
amount_to_scroll = height - 2*this_scroll_margin + dy;
the window. This could happen if the value of
scroll_up_aggressively is too large and there are
non-zero margins, because scroll_up_aggressively
means put point that fraction of window height
_from_the_bottom_margin_. */
if (aggressive_scroll + 2*this_scroll_margin > height)
aggressive_scroll = height - 2*this_scroll_margin;
amount_to_scroll = dy + aggressive_scroll;
}
}
@ -14852,7 +14857,8 @@ try_scrolling (Lisp_Object window, int just_this_one_p,
/* Compute the vertical distance from PT to the scroll
margin position. Move as far as scroll_max allows, or
one screenful, or 10 screen lines, whichever is largest.
Give up if distance is greater than scroll_max. */
Give up if distance is greater than scroll_max or if we
didn't reach the scroll margin position. */
SET_TEXT_POS (pos, PT, PT_BYTE);
start_display (&it, w, pos);
y0 = it.current_y;
@ -14862,7 +14868,8 @@ try_scrolling (Lisp_Object window, int just_this_one_p,
y_to_move, -1,
MOVE_TO_POS | MOVE_TO_X | MOVE_TO_Y);
dy = it.current_y - y0;
if (dy > scroll_max)
if (dy > scroll_max
|| IT_CHARPOS (it) < CHARPOS (scroll_margin_pos))
return SCROLLING_FAILED;
/* Compute new window start. */
@ -14880,15 +14887,16 @@ try_scrolling (Lisp_Object window, int just_this_one_p,
if (NUMBERP (aggressive))
{
double float_amount = XFLOATINT (aggressive) * height;
amount_to_scroll = float_amount;
if (amount_to_scroll == 0 && float_amount > 0)
amount_to_scroll = 1;
amount_to_scroll -=
this_scroll_margin - dy - FRAME_LINE_HEIGHT (f);
int aggressive_scroll = float_amount;
if (aggressive_scroll == 0 && float_amount > 0)
aggressive_scroll = 1;
/* Don't let point enter the scroll margin near
bottom of the window. */
if (amount_to_scroll > height - 2*this_scroll_margin + dy)
amount_to_scroll = height - 2*this_scroll_margin + dy;
bottom of the window, if the value of
scroll_down_aggressively happens to be too
large. */
if (aggressive_scroll + 2*this_scroll_margin > height)
aggressive_scroll = height - 2*this_scroll_margin;
amount_to_scroll = dy + aggressive_scroll;
}
}