summaryrefslogtreecommitdiff
path: root/doc/lispref
diff options
context:
space:
mode:
Diffstat (limited to 'doc/lispref')
-rw-r--r--doc/lispref/buffers.texi4
-rw-r--r--doc/lispref/display.texi40
-rw-r--r--doc/lispref/elisp.texi20
-rw-r--r--doc/lispref/eval.texi9
-rw-r--r--doc/lispref/files.texi32
-rw-r--r--doc/lispref/frames.texi40
-rw-r--r--doc/lispref/functions.texi17
-rw-r--r--doc/lispref/help.texi12
-rw-r--r--doc/lispref/internals.texi4
-rw-r--r--doc/lispref/loading.texi61
-rw-r--r--doc/lispref/modes.texi63
-rw-r--r--doc/lispref/os.texi17
-rw-r--r--doc/lispref/positions.texi12
-rw-r--r--doc/lispref/processes.texi48
-rw-r--r--doc/lispref/strings.texi13
-rw-r--r--doc/lispref/syntax.texi8
-rw-r--r--doc/lispref/text.texi166
-rw-r--r--doc/lispref/tips.texi16
-rw-r--r--doc/lispref/windows.texi128
19 files changed, 606 insertions, 104 deletions
diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 45a21c8e806..55fa5bcd6f0 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -716,7 +716,9 @@ The special commands of these modes bind @code{buffer-read-only} to
@defvar buffer-read-only
This buffer-local variable specifies whether the buffer is read-only.
-The buffer is read-only if this variable is non-@code{nil}.
+The buffer is read-only if this variable is non-@code{nil}. However,
+characters that have the @code{inhibit-read-only} text property can
+still be modified. @xref{Special Properties, inhibit-read-only}.
@end defvar
@defvar inhibit-read-only
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index ad248b116ed..d1ac85a7cab 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -330,7 +330,7 @@ support them, then @code{message-box} uses the echo area, like
@code{message}.
@end defun
-@defun display-message-or-buffer message &optional buffer-name not-this-window frame
+@defun display-message-or-buffer message &optional buffer-name action frame
This function displays the message @var{message}, which may be either a
string or a buffer. If it is shorter than the maximum height of the
echo area, as defined by @code{max-mini-window-height}, it is displayed
@@ -346,7 +346,7 @@ pop-up buffer is used, defaulting to @file{*Message*}. In the case
where @var{message} is a string and displayed in the echo area, it is
not specified whether the contents are inserted into the buffer anyway.
-The optional arguments @var{not-this-window} and @var{frame} are as for
+The optional arguments @var{action} and @var{frame} are as for
@code{display-buffer}, and only used if a buffer is displayed.
@end defun
@@ -1889,12 +1889,13 @@ end of the result if it falls short of @var{width}. It is also used at
the beginning of the result if one multi-column character in
@var{string} extends across the column @var{start-column}.
+@vindex truncate-string-ellipsis
If @var{ellipsis} is non-@code{nil}, it should be a string which will
replace the end of @var{string} (including any padding) if it extends
beyond @var{width}, unless the display width of @var{string} is equal
to or less than the display width of @var{ellipsis}. If
@var{ellipsis} is non-@code{nil} and not a string, it stands for
-@code{"..."}.
+the value of the variable @code{truncate-string-ellipsis}.
@example
(truncate-string-to-width "\tab\t" 12 4)
@@ -3659,6 +3660,39 @@ tag (or @code{nil}, which stands for the default langsys), and each
@end table
@end defun
+@cindex font information for layout
+The following four functions return size information about fonts used
+by various faces, allowing various layout considerations in Lisp
+programs. These functions take face remapping into consideration,
+returning information about the remapped face, if the face in question
+was remapped. @xref{Face Remapping}.
+
+@defun default-font-width
+This function returns the average width in pixels of the font used by
+the current buffer's default face.
+@end defun
+
+@defun default-font-height
+This function returns the height in pixels of the font used by the
+current buffer's default face.
+@end defun
+
+@defun window-font-width &optional window face
+This function returns the average width in pixels for the font used by
+@var{face} in @var{window}. The specified @var{window} must be a live
+window. If @code{nil} or omitted, @var{window} defaults to the
+selected window, and @var{face} defaults to the default face in
+@var{window}.
+@end defun
+
+@defun window-font-height &optional window face
+This function returns the height in pixels for the font used by
+@var{face} in @var{window}. The specified @var{window} must be a live
+window. If @code{nil} or omitted, @var{window} defaults to the
+selected window, and @var{face} defaults to the default face in
+@var{window}.
+@end defun
+
@node Fringes
@section Fringes
@cindex fringes
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 2d3548f65ba..56d303e2e9e 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -467,6 +467,10 @@ Control Structures
* Generators:: Generic sequences and coroutines.
* Nonlocal Exits:: Jumping out of a sequence.
+Conditionals
+
+* Pattern matching case statement:: How to use @code{pcase}.
+
Nonlocal Exits
* Catch and Throw:: Nonlocal exits for the program's own purposes.
@@ -535,6 +539,7 @@ Functions
* Function Cells:: Accessing or setting the function definition
of a symbol.
* Closures:: Functions that enclose a lexical environment.
+* Advising Functions:: Adding to the definition of a function.
* Obsolete Functions:: Declaring functions obsolete.
* Inline Functions:: Defining functions that the compiler
will expand inline.
@@ -552,6 +557,13 @@ Lambda Expressions
* Argument List:: Details and special features of argument lists.
* Function Documentation:: How to put documentation in a function.
+Advising Emacs Lisp Functions
+
+* Core Advising Primitives:: Primitives to manipulate advice.
+* Advising Named Functions:: Advising named functions.
+* Advice combinators:: Ways to compose advice.
+* Porting old advice:: Adapting code using the old defadvice.
+
Macros
* Simple Macro:: A basic example.
@@ -602,6 +614,7 @@ Loading
* Unloading:: How to unload a library that was loaded.
* Hooks for Loading:: Providing code to be run when
particular libraries are loaded.
+* Dynamic Modules:: Modules provide additional Lisp primitives.
Byte Compilation
@@ -1191,6 +1204,10 @@ Text Properties
* Not Intervals:: Why text properties do not use
Lisp-visible text intervals.
+Parsing HTML and XML
+
+* Document Object Model:: Access, manipulate and search the @acronym{DOM}.
+
Non-@acronym{ASCII} Characters
* Text Representations:: How Emacs represents text.
@@ -1530,9 +1547,12 @@ GNU Emacs Internals
* Building Emacs:: How the dumped Emacs is made.
* Pure Storage:: Kludge to make preloaded Lisp functions shareable.
* Garbage Collection:: Reclaiming space for Lisp objects no longer used.
+* Stack-allocated Objects:: Temporary conses and strings on C stack.
* Memory Usage:: Info about total size of Lisp objects made so far.
+* C Dialect:: What C variant Emacs is written in.
* Writing Emacs Primitives:: Writing C code for Emacs.
* Object Internals:: Data formats of buffers, windows, processes.
+* C Integer Types:: How C integer types are used inside Emacs.
Object Internals
diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi
index 067dbd2d99f..dfad9fb709d 100644
--- a/doc/lispref/eval.texi
+++ b/doc/lispref/eval.texi
@@ -780,7 +780,8 @@ to specify this function, but it is more robust to use the
@deffn Command eval-buffer &optional buffer-or-name stream filename unibyte print
This is similar to @code{eval-region}, but the arguments provide
different optional features. @code{eval-buffer} operates on the
-entire accessible portion of buffer @var{buffer-or-name}.
+entire accessible portion of buffer @var{buffer-or-name}
+(@pxref{Narrowing,,, emacs, The GNU Emacs Manual}).
@var{buffer-or-name} can be a buffer, a buffer name (a string), or
@code{nil} (or omitted), which means to use the current buffer.
@var{stream} is used as in @code{eval-region}, unless @var{stream} is
@@ -833,9 +834,9 @@ The value of this variable is a list of the values returned by all the
expressions that were read, evaluated, and printed from buffers
(including the minibuffer) by the standard Emacs commands which do
this. (Note that this does @emph{not} include evaluation in
-@file{*ielm*} buffers, nor evaluation using @kbd{C-j} in
-@code{lisp-interaction-mode}.) The elements are ordered most recent
-first.
+@file{*ielm*} buffers, nor evaluation using @kbd{C-j}, @kbd{C-x C-e},
+and similar evaluation commands in @code{lisp-interaction-mode}.) The
+elements are ordered most recent first.
@example
@group
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 9a1b2cd217f..918bf5becbd 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2030,11 +2030,6 @@ form.
@end example
@end defun
-@defun directory-name-p filename
-This function returns non-@code{nil} if @var{filename} ends with a
-forward slash (@samp{/}) character.
-@end defun
-
@node Directory Names
@subsection Directory Names
@cindex directory name
@@ -2076,6 +2071,13 @@ string (if it does not already end in one).
@end example
@end defun
+@defun directory-name-p filename
+This function returns non-@code{nil} if @var{filename} ends with a
+directory separator character. This is the forward slash @samp{/} on
+Unix and GNU systems; MS-Windows and MS-DOS recognize both the forward
+slash and the backslash @samp{\} as directory separators.
+@end defun
+
@defun directory-file-name dirname
This function returns a string representing @var{dirname} in a form
that the operating system will interpret as the name of a file (a
@@ -2632,12 +2634,20 @@ An error is signaled if @var{directory} is not the name of a directory
that can be read.
@end defun
-@defun directory-files-recursively directory match &optional include-directories
-Return all files under @var{directory} whose file names match
-@var{match} recursively. The file names are returned depth first,
-meaning that contents of sub-directories are returned before contents
-of the directories. If @var{include-directories} is non-@code{nil},
-also return directory names that have matching names.
+@defun directory-files-recursively directory regexp &optional include-directories
+Return all files under @var{directory} whose names match @var{regexp}.
+This function searches the specified @var{directory} and its
+sub-directories, recursively, for files whose basenames (i.e., without
+the leading directories) match the specified @var{regexp}, and returns
+a list of the absolute file names of the matching files
+(@pxref{Relative File Names, absolute file names}). The file names
+are returned in depth-first order, meaning that files in some
+sub-directory are returned before the files in its parent directory.
+In addition, matching files found in each subdirectory are sorted
+alphabetically by their basenames. By default, directories whose
+names match @var{regexp} are omitted from the list, but if the
+optional argument @var{include-directories} is non-@code{nil}, they
+are included.
@end defun
@defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 3ae33082fc4..80a4af29f1a 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -557,7 +557,7 @@ The top left corner of the native frame specifies the @dfn{native
position} of the frame. (1)--(3) in the drawing above indicate that
position for the various builds:
-@itemize @w
+@itemize @w{}
@item (1) non-toolkit and terminal frames
@item (2) Lucid, Motif and Windows frames
@@ -1001,18 +1001,40 @@ parameters of @var{frame} and their values. If @var{frame} is
@end defun
@defun modify-frame-parameters frame alist
-This function alters the parameters of frame @var{frame} based on the
-elements of @var{alist}. Each element of @var{alist} has the form
-@code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
-parameter. If you don't mention a parameter in @var{alist}, its value
-doesn't change. If @var{frame} is @code{nil}, it defaults to the selected
-frame.
+This function alters the frame @var{frame} based on the elements of
+@var{alist}. Each element of @var{alist} has the form
+@code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming
+a parameter. If you don't mention a parameter in @var{alist}, its
+value doesn't change. If @var{frame} is @code{nil}, it defaults to
+the selected frame.
+
+Some parameters are only meaningful for frames on certain kinds of
+display (@pxref{Frames}). If @var{alist} includes parameters that are
+not meaningful for the @var{frame}'s display, this function will
+change its value in the frame's parameter list, but will otherwise
+ignore it.
+
+When @var{alist} specifies more than one parameter whose value can
+affect the new size of @var{frame}, the final size of the frame may
+differ according to the toolkit used. For example, specifying that a
+frame should from now on have a menu and/or tool bar instead of none and
+simultaneously specifying the new height of the frame will inevitably
+lead to a recalculation of the frame's height. Conceptually, in such
+case, this function will try to have the explicit height specification
+prevail. It cannot be excluded, however, that the addition (or removal)
+of the menu or tool bar, when eventually performed by the toolkit, will
+defeat this intention.
+
+Sometimes, binding @code{frame-inhibit-implied-resize} (@pxref{Implied
+Frame Resizing}) to a non-@code{nil} value around calls to this function
+may fix the problem sketched here. Sometimes, however, exactly such
+binding may be hit by the problem.
@end defun
@defun set-frame-parameter frame parm value
This function sets the frame parameter @var{parm} to the specified
-@var{value}. If @var{frame} is @code{nil}, it defaults to the
-selected frame.
+@var{value}. If @var{frame} is @code{nil}, it defaults to the selected
+frame.
@end defun
@defun modify-all-frames-parameters alist
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 8835667b82d..7cc041fa77e 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -861,15 +861,18 @@ into a list. @code{mapc} always returns @var{sequence}.
@defun mapconcat function sequence separator
@code{mapconcat} applies @var{function} to each element of
-@var{sequence}: the results, which must be strings, are concatenated.
-Between each pair of result strings, @code{mapconcat} inserts the string
-@var{separator}. Usually @var{separator} contains a space or comma or
-other suitable punctuation.
+@var{sequence}; the results, which must be sequences of characters
+(strings, vectors, or lists), are concatenated into a single string
+return value. Between each pair of result sequences, @code{mapconcat}
+inserts the characters from @var{separator}, which also must be a
+string, or a vector or list of characters. @xref{Sequences Arrays
+Vectors}.
The argument @var{function} must be a function that can take one
-argument and return a string. The argument @var{sequence} can be any
-kind of sequence except a char-table; that is, a list, a vector, a
-bool-vector, or a string.
+argument and returns a sequence of characters: a string, a vector, or
+a list. The argument @var{sequence} can be any kind of sequence
+except a char-table; that is, a list, a vector, a bool-vector, or a
+string.
@example
@group
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 387587a4203..685995b395f 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -352,16 +352,16 @@ string in Emacs Lisp.
@defvar text-quoting-style
@cindex curved quotes
@cindex curly quotes
-The value of this variable specifies the style used to generate text
-quotes. If the variable's value is @code{curve}, the style is
+The value of this variable is a symbol that specifies the style Emacs
+should use for single quotes in the wording of help and messages.
+If the variable's value is @code{curve}, the style is
@t{‘like this’} with curved single quotes. If the value is
@code{straight}, the style is @t{'like this'} with straight
apostrophes. If the value is @code{grave}, the style is @t{`like
-this'} with grave accent and apostrophe. The default value @code{nil}
+this'} with grave accent and apostrophe, the standard style
+before Emacs version 25. The default value @code{nil}
acts like @code{curve} if curved single quotes are displayable, and
-like @code{grave} otherwise. To use the traditional @code{grave}
-style, put the line @code{(setq text-quoting-style 'grave)} into your
-@file{~/.emacs} file.
+like @code{grave} otherwise.
@end defvar
@defun substitute-command-keys string
diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index e620da0b4ff..e111d358ba0 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -32,7 +32,9 @@ executable. You don't have to know this material to build and install
Emacs, since the makefiles do all these things automatically. This
information is pertinent to Emacs developers.
- Compilation of the C source files in the @file{src} directory
+ Building Emacs requires GNU Make version 3.81 or later.
+
+ Compilation of the C source files in the @file{src} directory
produces an executable file called @file{temacs}, also called a
@dfn{bare impure Emacs}. It contains the Emacs Lisp interpreter and
I/O routines, but not the editing commands.
diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index 82de765876e..e01f3161731 100644
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -29,7 +29,15 @@ into a buffer and evaluated there. (Indeed, most code is tested this
way.) Most often, the forms are function definitions and variable
definitions.
-For on-demand loading of external libraries, @pxref{Dynamic Libraries}.
+ Emacs can also load compiled dynamic modules: shared libraries that
+provide additional functionality for use in Emacs Lisp programs, just
+like a package written in Emacs Lisp would. When a dynamic module is
+loaded, Emacs calls a specially-named initialization function which
+the module needs to implement, and which exposes the additional
+functions and variables to Emacs Lisp programs.
+
+For on-demand loading of external libraries which are known in advance
+to be required by certain Emacs primitives, @pxref{Dynamic Libraries}.
@menu
* How Programs Do Loading:: The @code{load} function and others.
@@ -43,6 +51,7 @@ For on-demand loading of external libraries, @pxref{Dynamic Libraries}.
* Unloading:: How to unload a library that was loaded.
* Hooks for Loading:: Providing code to be run when
particular libraries are loaded.
+* Dynamic Modules:: Modules provide additional Lisp primitives.
@end menu
@node How Programs Do Loading
@@ -1076,3 +1085,53 @@ defined in another library (those meant for outside use), you can do
it immediately---there is no need to wait until the library is loaded.
If you need to call functions defined by that library, you should load
the library, preferably with @code{require} (@pxref{Named Features}).
+
+@node Dynamic Modules
+@section Emacs Dynamic Modules
+@cindex dynamic modules
+
+@c FIXME: This is intentionally incomplete, as the module integration
+@c is not yet finished. To be refined later.
+ A @dfn{dynamic Emacs module} is a shared library that provides
+additional functionality for use in Emacs Lisp programs, just like a
+package written in Emacs Lisp would.
+
+ Functions that load Emacs Lisp packages can also load dynamic
+modules. They recognize dynamic modules by looking at their file-name
+extension, a.k.a.@: ``suffix''. This suffix is platform-dependent.
+
+@defvar module-file-suffix
+This variable holds the system-dependent value of the file-name
+extension of the module files. Its value is @file{.so} on Posix hosts
+and @file{.dll} on MS-Windows.
+@end defvar
+
+@findex emacs_module_init
+@vindex plugin_is_GPL_compatible
+Every dynamic module should export a C-callable function named
+@code{emacs_module_init}, which Emacs will call as part of the call to
+@code{load} or @code{require} which loads the module. It should also
+export a symbol named @code{plugin_is_GPL_compatible} to indicate that
+its code is released under the GPL or compatible license; Emacs will
+refuse to load modules that don't export such a symbol.
+
+If a module needs to call Emacs functions, it should do so through the
+API defined and documented in the header file @file{emacs-module.h}
+that is part of the Emacs distribution.
+
+@cindex user-ptr object
+Modules can create @code{user-ptr} Lisp objects that embed pointers to
+C struct's defined by the module. This is useful for keeping around
+complex data structures created by a module, to be passed back to the
+module's functions. User-ptr objects can also have associated
+@dfn{finalizers} -- functions to be run when the object is GC'ed; this
+is useful for freeing any resources allocated for the underlying data
+structure, such as memory, open file descriptors, etc.
+
+@defun user-ptrp object
+This function returns @code{t} if its argument is a @code{user-ptr}
+object.
+@end defun
+
+Loadable modules in Emacs are enabled by using the
+@kbd{--with-modules} option at configure time.
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index a1747707d11..3b8550e13b9 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -2509,6 +2509,53 @@ Search-based fontification happens second.
@node Font Lock Basics
@subsection Font Lock Basics
+ The Font Lock functionality is based on several basic functions.
+Each of these calls the function specified by the corresponding
+variable. This indirection allows major modes to modify the way
+fontification works in the buffers of that mode, and even use the Font
+Lock mechanisms for features that have nothing to do with
+fontification. (This is why the description below says ``should''
+when it describes what the functions do: the major mode can customize
+the values of the corresponding variables to do something entirely
+different.) The variables mentioned below are described in @ref{Other
+Font Lock Variables}.
+
+@ftable @code
+@item font-lock-fontify-buffer
+This function should fontify the current buffer's accessible portion,
+by calling the function specified by
+@code{font-lock-fontify-buffer-function}.
+
+@item font-lock-unfontify-buffer
+Used when turning Font Lock off to remove the fontification. Calls
+the function specified by @code{font-lock-unfontify-buffer-function}.
+
+@item font-lock-fontify-region beg end &optional loudly
+Should fontify the region between @var{beg} and @var{end}. If
+@var{loudly} is non-@code{nil}, should display status messages while
+fontifying. Calls the function specified by
+@code{font-lock-fontify-region-function}.
+
+@item font-lock-unfontify-region beg end
+Should remove fontification from the region between @var{beg} and
+@var{end}. Calls the function specified by
+@code{font-lock-unfontify-region-function}.
+
+@item font-lock-flush &optional beg end
+This function should mark the fontification of the region between
+@var{beg} and @var{end} as outdated. If not specified or @code{nil},
+@var{beg} and @var{end} default to the beginning and end of the
+buffer's accessible portion. Calls the function specified by
+@code{font-lock-flush-function}.
+
+@item font-lock-ensure &optional beg end
+This function should make sure the region between @var{beg} and
+@var{end} has been fontified. The optional arguments @var{beg} and
+@var{end} default to the beginning and the end of the buffer's
+accessible portion. Calls the function specified by
+@code{font-lock-ensure-function}.
+@end ftable
+
There are several variables that control how Font Lock mode highlights
text. But major modes should not set any of these variables directly.
Instead, they should set @code{font-lock-defaults} as a buffer-local
@@ -2936,6 +2983,22 @@ arguments, the beginning and end of the region. The default value is
@code{font-lock-default-unfontify-region}.
@end defvar
+@defvar font-lock-flush-function
+Function to use for declaring that a region's fontification is out of
+date. It takes two arguments, the beginning and end of the region.
+The default value of this variable is
+@code{font-lock-after-change-function}.
+@end defvar
+
+@defvar font-lock-ensure-function
+Function to use for making sure a region of the current buffer has
+been fontified. It is called with two arguments, the beginning and
+end of the region. The default value of this variable is a function
+that calls @code{font-lock-default-fontify-buffer} if the buffer is
+not fontified; the effect is to make sure the entire accessible
+portion of the buffer is fontified.
+@end defvar
+
@defun jit-lock-register function &optional contextual
This function tells Font Lock mode to run the Lisp function
@var{function} any time it has to fontify or refontify part of the
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 17a0b47ad06..92e3ee2b33c 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -902,6 +902,9 @@ Hewlett-Packard HPUX operating system.
@item irix
Silicon Graphics Irix system.
+@item nacl
+Google Native Client (@acronym{NaCl}) sandboxing system.
+
@item ms-dos
Microsoft's DOS@. Emacs compiled with DJGPP for MS-DOS binds
@code{system-type} to @code{ms-dos} even when you run it on MS-Windows.
@@ -911,7 +914,7 @@ AT&T Unix System V.
@item windows-nt
Microsoft Windows NT, 9X and later. The value of @code{system-type}
-is always @code{windows-nt}, e.g., even on Windows 7.
+is always @code{windows-nt}, e.g., even on Windows 10.
@end table
@@ -2922,6 +2925,18 @@ means complete; it is intended to give you an idea of the security
issues involved, rather than to be a security checklist.
@table @asis
+@item File local variables
+@cindex file local variables
+A file that Emacs visits can contain variable settings that affects
+the buffer visiting that file; @xref{File Local Variables}.
+Similarly, a directory can specify local variable values common to all
+files in that directory; @xref{Directory Local Variables}. Although
+Emacs takes some effort to protect against misuse of these variables,
+a security hole can be created merely by a package setting
+@code{safe-local-variable} too optimistically, a problem that is all
+too common. To disable this feature for both files and directories,
+set @code{enable-local-variables} to @code{nil}.
+
@item Access control
Although Emacs normally respects access permissions of the underlying
operating system, in some cases it handles accesses specially. For
diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi
index 72b76ce5c8f..9daf5cef059 100644
--- a/doc/lispref/positions.texi
+++ b/doc/lispref/positions.texi
@@ -572,6 +572,18 @@ The value returned is the window line number point has moved to, with
the top line in the window numbered 0.
@end deffn
+@vindex move-to-window-group-line-function
+@defun move-to-window-group-line count
+This function is like @code{move-to-window-line}, except that when the
+selected window is a part of a group of windows (@pxref{Window
+Group}), @code{move-to-window-group-line} will move to a position with
+respect to the entire group, not just the single window. This
+condition holds when the buffer local variable
+@code{move-to-window-group-line-function} is set to a function. In
+this case, @code{move-to-window-group-line} calls the function with
+the argument @var{count}, then returns its result.
+@end defun
+
@defun compute-motion from frompos to topos width offsets window
This function scans the current buffer, calculating screen positions.
It scans the buffer forward from position @var{from}, assuming that is
diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index 0ce696ad533..41255e7e8d0 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -737,10 +737,12 @@ If @var{stopped} is non-@code{nil}, start the process in the
stopped state.
@item :filter @var{filter}
-Initialize the process filter to @var{filter}.
+Initialize the process filter to @var{filter}. If not specified, a
+default filter will be provided. @xref{Filter Functions}.
@item :sentinel @var{sentinel}
-Initialize the process sentinel to @var{sentinel}.
+Initialize the process sentinel to @var{sentinel}. If not specified,
+a default sentinel will be used. @xref{Sentinels}.
@item :stderr @var{stderr}
Associate @var{stderr} with the standard error of the process.
@@ -789,10 +791,12 @@ If @var{stopped} is non-@code{nil}, start the process in the
stopped state.
@item :filter @var{filter}
-Initialize the process filter to @var{filter}.
+Initialize the process filter to @var{filter}. If not specified, a
+default filter will be provided. @xref{Filter Functions}.
@item :sentinel @var{sentinel}
-Initialize the process sentinel to @var{sentinel}.
+Initialize the process sentinel to @var{sentinel}. If not specified,
+a default sentinel will be used. @xref{Sentinels}.
@end table
The original argument list, modified with the actual connection
@@ -922,9 +926,10 @@ For a network process, the values include (see
@item :buffer
The associated value is the process buffer.
@item :filter
-The associated value is the process filter function.
+The associated value is the process filter function. @xref{Filter
+Functions}.
@item :sentinel
-The associated value is the process sentinel function.
+The associated value is the process sentinel function. @xref{Sentinels}.
@item :remote
In a connection, the address in internal format of the remote peer.
@item :local
@@ -1379,6 +1384,7 @@ subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}).
@cindex filter function
@cindex process filter
+@cindex default filter function of a process
A process @dfn{filter function} is a function that receives the
standard output from the associated process. @emph{All} output from
that process is passed to the filter. The default filter simply
@@ -1632,21 +1638,43 @@ also called if the process exits. The sentinel receives two
arguments: the process for which the event occurred, and a string
describing the type of event.
+@cindex default sentinel function of a process
+ If no sentinel function was specified for a process, it will use the
+default sentinel function, which inserts a message in the process's
+buffer with the process name and the string describing the event.
+
The string describing the event looks like one of the following:
-@c FIXME? Also "killed\n" - see example below?
@itemize @bullet
@item
@code{"finished\n"}.
@item
-@code{"exited abnormally with code @var{exitcode}\n"}.
+@code{"deleted\n"}.
+
+@item
+@code{"exited abnormally with code @var{exitcode} (core dumped)\n"}.
+The ``core dumped'' part is optional, and only appears if the process
+dumped core.
+
+@item
+@code{"failed with code @var{fail-code}\n"}.
+
+@item
+@code{"@var{signal-description} (core dumped)\n"}. The
+@var{signal-description} is a system-dependent textual description of
+a signal, e.g., @code{"killed"} for @code{SIGKILL}. The ``core
+dumped'' part is optional, and only appears if the process dumped
+core.
+
+@item
+@code{"open from @var{host-name}\n"}.
@item
-@code{"@var{name-of-signal}\n"}.
+@code{"open\n"}.
@item
-@code{"@var{name-of-signal} (core dumped)\n"}.
+@code{"connection broken by remote peer\n"}.
@end itemize
A sentinel runs only while Emacs is waiting (e.g., for terminal
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index f8685d9312c..8aa4539bd78 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -465,6 +465,7 @@ Representations}.
@code{string-equal} is another name for @code{string=}.
@end defun
+@cindex locale-dependent string equivalence
@defun string-collate-equalp string1 string2 &optional locale ignore-case
This function returns @code{t} if @var{string1} and @var{string2} are
equal with respect to collation rules. A collation rule is not only
@@ -493,6 +494,7 @@ systems.
If @var{ignore-case} is non-@code{nil}, characters are converted to lower-case
before comparing them.
+@vindex w32-collate-ignore-punctuation
To emulate Unicode-compliant collation on MS-Windows systems,
bind @code{w32-collate-ignore-punctuation} to a non-@code{nil} value, since
the codeset part of the locale cannot be @code{"UTF-8"} on MS-Windows.
@@ -518,7 +520,7 @@ optional argument @var{ignore-case} is non-@code{nil}, the comparison
ignores case differences.
@end defun
-@cindex lexical comparison
+@cindex lexical comparison of strings
@defun string< string1 string2
@c (findex string< causes problems for permuted index!!)
This function compares two strings a character at a time. It
@@ -576,6 +578,7 @@ are used.
@code{string-lessp} is another name for @code{string<}.
@end defun
+@cindex locale-dependent string comparison
@defun string-collate-lessp string1 string2 &optional locale ignore-case
This function returns @code{t} if @var{string1} is less than
@var{string2} in collation order. A collation order is not only
@@ -594,15 +597,15 @@ for sorting (@pxref{Sequence Functions}):
@end group
@end example
-This behavior is system-dependent; punctuation and whitespace are
-never ignored on Cygwin, regardless of locale.
+This behavior is system-dependent; e.g., punctuation and whitespace
+are never ignored on Cygwin, regardless of locale.
The optional argument @var{locale}, a string, overrides the setting of
your current locale identifier for collation. The value is system
dependent; a @var{locale} @code{"en_US.UTF-8"} is applicable on POSIX
systems, while it would be, e.g., @code{"enu_USA.1252"} on MS-Windows
-systems. The @var{locale} @code{"POSIX"} lets @code{string-collate-lessp}
-behave like @code{string-lessp}:
+systems. The @var{locale} value of @code{"POSIX"} or @code{"C"} lets
+@code{string-collate-lessp} behave like @code{string-lessp}:
@example
@group
diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi
index 7a984e3d87b..831ebd12f55 100644
--- a/doc/lispref/syntax.texi
+++ b/doc/lispref/syntax.texi
@@ -945,6 +945,14 @@ whitespace by the functions in this section and by @code{forward-sexp},
The behavior of @code{parse-partial-sexp} is also affected by
@code{parse-sexp-lookup-properties} (@pxref{Syntax Properties}).
+@defvar comment-end-can-be-escaped
+If this buffer local variable is non-@code{nil}, a single character
+which usually terminates a comment doesn't do so when that character
+is escaped. This is used in C and C++ Modes, where line comments
+starting with @samp{//} can be continued onto the next line by
+escaping the newline with @samp{\}.
+@end defvar
+
You can use @code{forward-comment} to move forward or backward over
one comment or several comments.
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 6d9d26f0ad1..f3679a88f74 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -899,13 +899,25 @@ adds it to the most recent element. It determines automatically (using
@code{last-command}) whether the previous command was a kill command,
and if so appends the killed text to the most recent entry.
-@deffn Command kill-region start end
-This function kills the text in the region defined by @var{start} and
-@var{end}. The text is deleted but saved in the kill ring, along with
-its text properties. The value is always @code{nil}.
+@cindex filtering killed text
+ The commands described below can filter the killed text before they
+save it in the kill ring. They call @code{filter-buffer-substring}
+(@pxref{Buffer Contents}) to perform the filtering. By default,
+there's no filtering, but major and minor modes and hook functions can
+set up filtering, so that text saved in the kill ring is different
+from what was in the buffer.
+
+@deffn Command kill-region start end &optional region
+This function kills the stretch of text between @var{start} and
+@var{end}; but if the optional argument @var{region} is
+non-@code{nil}, it ignores @var{start} and @var{end}, and kills the
+text in the current region instead. The text is deleted but saved in
+the kill ring, along with its text properties. The value is always
+@code{nil}.
In an interactive call, @var{start} and @var{end} are point and
-the mark.
+the mark, and @var{region} is always non-@code{nil}, so the command
+always kills the text in the current region.
If the buffer or text is read-only, @code{kill-region} modifies the kill
ring just the same, then signals an error without modifying the buffer.
@@ -919,18 +931,20 @@ error if the buffer or text is read-only. Instead, it simply returns,
updating the kill ring but not changing the buffer.
@end defopt
-@deffn Command copy-region-as-kill start end
-This command saves the region defined by @var{start} and @var{end} on
-the kill ring (including text properties), but does not delete the text
-from the buffer. It returns @code{nil}.
+@deffn Command copy-region-as-kill start end &optional region
+This function saves the stretch of text between @var{start} and
+@var{end} on the kill ring (including text properties), but does not
+delete the text from the buffer. However, if the optional argument
+@var{region} is non-@code{nil}, the function ignores @var{start} and
+@var{end}, and saves the current region instead. It always returns
+@code{nil}.
+
+In an interactive call, @var{start} and @var{end} are point and
+the mark, and @var{region} is always non-@code{nil}, so the command
+always saves the text in the current region.
The command does not set @code{this-command} to @code{kill-region}, so a
subsequent kill command does not append to the same kill ring entry.
-
-@c FIXME Why is it better? Why isn't copy-region-as-kill obsolete then?
-@c Why is it used in many places in Emacs?
-In Lisp programs, it is better to use @code{kill-new} or
-@code{kill-append} instead of this command. @xref{Low-Level Kill Ring}.
@end deffn
@node Yanking
@@ -1343,27 +1357,39 @@ This function places a boundary element in the undo list. The undo
command stops at such a boundary, and successive undo commands undo
to earlier and earlier boundaries. This function returns @code{nil}.
-The editor command loop automatically calls @code{undo-boundary} just
-before executing each key sequence, so that each undo normally undoes
-the effects of one command. As an exception, the command
-@code{self-insert-command}, which produces self-inserting input
-characters (@pxref{Commands for Insertion}), may remove the boundary
-inserted by the command loop: a boundary is accepted for the first
-such character, the next 19 consecutive self-inserting input
-characters do not have boundaries, and then the 20th does; and so on
-as long as the self-inserting characters continue. Hence, sequences
-of consecutive character insertions can be undone as a group.
-
-All buffer modifications add a boundary whenever the previous undoable
-change was made in some other buffer. This is to ensure that
-each command makes a boundary in each buffer where it makes changes.
-
Calling this function explicitly is useful for splitting the effects of
a command into more than one unit. For example, @code{query-replace}
calls @code{undo-boundary} after each replacement, so that the user can
undo individual replacements one by one.
+
+Mostly, however, this function is called automatically at an
+appropriate time.
+@end defun
+
+@defun undo-auto-amalgamate
+@cindex amalgamating commands, and undo
+The editor command loop automatically calls @code{undo-boundary} just
+before executing each key sequence, so that each undo normally undoes
+the effects of one command. A few exceptional commands are
+@dfn{amalgamating}: these commands generally cause small changes to
+buffers, so with these a boundary is inserted only every 20th command,
+allowing to undo them as a group. By default, commands
+@code{self-insert-command}, which produces self-inserting input
+characters (@pxref{Commands for Insertion}), and @code{delete-char}
+which deletes characters (@pxref{Deletion}) are amalgamating.
+Where a command affects the contents of several buffers, as may happen,
+for example, when a function on the @code{post-command-hook} affects a
+buffer other than the @code{current-buffer}, then @code{undo-boundary}
+will be called in each of the affected buffers.
@end defun
+@defvar undo-auto-current-boundary-timer
+Some buffers, such as process buffers, can change even when no
+commands are executing. In these cases, @code{undo-boundary} is
+normally called periodically by the timer in this variable. Setting
+this variable to non-@code{nil} prevents this behavior.
+@end defvar
+
@defvar undo-in-progress
This variable is normally @code{nil}, but the undo commands bind it to
@code{t}. This is so that various kinds of change hooks can tell when
@@ -2336,6 +2362,84 @@ already indented, it calls @code{completion-at-point} to complete the
text at point (@pxref{Completion in Buffers}).
@end defopt
+@cindex literate programming
+@cindex multi-mode indentation
+ Some major modes need to support embedded regions of text whose
+syntax belongs to a different major mode. Examples include
+@dfn{literate programming} source files that combine documentation and
+snippets of source code, Yacc/Bison programs that include snippets of
+plain C code, etc. To correctly indent the embedded chunks, the major
+mode needs to delegate the indentation to another mode's indentation
+engine (e.g., call @code{c-indent-defun} for C code or
+@code{python-indent-line} for Python), while providing it with some
+context to guide the indentation. The following facilities support
+such multi-mode indentation.
+
+@defvar prog-indentation-context
+This variable, when non-@code{nil}, holds the indentation context for
+the sub-mode's indentation engine provided by the superior major mode.
+The value should be a list of the form @code{(@var{first-column}
+@w{(@var{start} . @var{end})} @code{prev-chunk})}. The members of the
+list have the following meaning:
+
+@table @var
+@item first-column
+The column to be used for top-level constructs. This replaces the
+default value of the top-level column used by the sub-mode, usually
+zero.
+@item start
+@itemx end
+The region of the code chunk to be indented by the sub-mode. The
+value of @var{end} can be @code{nil}, which stands for the value of
+@code{point-max}.
+@item prev-chunk
+If this is non-@code{nil}, it should provide the sub-mode's
+indentation engine with a virtual context of the code chunk. Valid
+values include:
+
+@itemize @minus
+@item
+A string whose contents is the text the sub-mode's indentation engine
+should consider to precede the code chunk. The sub-mode's indentation
+engine can add text properties to that string, to be reused in
+repeated calls with the same string, thus using it as a cache. An
+example where this is useful is code chunks that need to be indented
+as function bodies, but lack the function's preamble---the string
+could then include that missing preamble.
+@item
+A function. It is expected to be called with the start position of
+the current chunk, and should return a cons cell
+@w{@code{(@var{prev-start} . @var{prev-end})}} that specifies the
+region of the previous code chunk, or @code{nil} if there is no previous
+chunk. This is useful in literate-programming sources, where code is
+split into chunks, and correct indentation needs to access previous
+chunks.
+@end itemize
+@end table
+@end defvar
+
+The following convenience functions should be used by major mode's
+indentation engine in support of invocations as sub-modes of another
+major mode.
+
+@defun prog-first-column
+Call this function instead of using a literal value (usually, zero) of
+the column number for indenting top-level program constructs. The
+function's value is the column number to use for top-level constructs.
+When no superior mode is in effect, this function returns zero.
+@end defun
+
+@defun prog-widen
+Call this function instead of @code{widen} to remove any restrictions
+imposed by the mode's indentation engine and restore the restrictions
+recorded in @code{prog-indentation-context}. This prevents the
+indentation engine of a sub-mode from inadvertently operating on text
+outside of the chunk it was supposed to indent, and preserves the
+restriction imposed by the superior mode. When no superior mode is in
+effect, this function just calls @code{widen}.
+@end defun
+
+
@node Region Indent
@subsection Indenting an Entire Region
@@ -3256,8 +3360,8 @@ and then remove the property. @xref{Read Only Buffers}.
@item inhibit-read-only
@kindex inhibit-read-only @r{(text property)}
-If a character has the property @code{inhibit-read-only}, and the
-buffer is read-only, editing the character in question is allowed.
+Characters that have the property @code{inhibit-read-only} can be
+edited even in read-only buffers. @xref{Read Only Buffers}.
@item invisible
@kindex invisible @r{(text property)}
diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index d9cbf473306..ffce920bf4e 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -14,11 +14,17 @@ it gives advice on making effective use of the features described in the
previous chapters, and describes conventions Emacs Lisp programmers
should follow.
+@findex checkdoc
+@findex checkdoc-current-buffer
+@findex checkdoc-file
You can automatically check some of the conventions described below by
running the command @kbd{M-x checkdoc RET} when visiting a Lisp file.
It cannot check all of the conventions, and not all the warnings it
gives necessarily correspond to problems, but it is worth examining them
-all.
+all. Alternatively, use the command @kbd{M-x checkdoc-current-buffer RET}
+to check the conventions in the current buffer, or @code{checkdoc-file}
+when you want to check a file in batch mode, e.g., with a command run by
+@kbd{@w{M-x compile RET}}.
@menu
* Coding Conventions:: Conventions for clean and robust programs.
@@ -1007,8 +1013,14 @@ of multiple files, we recommend not writing the version in every file,
but only the main one.
@item Keywords
+@vindex checkdoc-package-keywords-flag
+@findex checkdoc-package-keywords
This line lists keywords for the @code{finder-by-keyword} help command.
-Please use that command to see a list of the meaningful keywords.
+Please use that command to see a list of the meaningful keywords. The
+command @kbd{M-x checkdoc-package-keywords RET} will find and display
+any keywords that are not in @code{finder-known-keywords}. If you set
+the variable @code{checkdoc-package-keywords-flag} non-@code{nil},
+checkdoc commands will include the keyword verification in its checks.
This field is how people will find your package when they're looking
for things by topic. To separate the keywords, you can use spaces,
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 357247ef433..e45201b0570 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -133,6 +133,30 @@ This function returns the selected window (which is always a live
window).
@end defun
+@anchor{Window Group}Sometimes several windows collectively and
+cooperatively display a buffer, for example, under the management of
+Follow Mode (@pxref{Follow Mode,,, emacs}), where the windows together
+display a bigger portion of the buffer than one window could alone.
+It is often useful to consider such a @dfn{window group} as a single
+entity. Several functions such as @code{window-group-start}
+(@pxref{Window Start and End}) allow you to do this by supplying, as
+an argument, one of the windows as a stand in for the whole group.
+
+@defun selected-window-group
+@vindex selected-window-group-function
+When the selected window is a member of a group of windows, this
+function returns a list of the windows in the group, ordered such that
+the first window in the list is displaying the earliest part of the
+buffer, and so on. Otherwise the function returns a list containing
+just the selected window.
+
+The selected window is considered part of a group when the buffer
+local variable @code{selected-window-group-function} is set to a
+function. In this case, @code{selected-window-group} calls it with no
+arguments and returns its result (which should be the list of windows
+in the group).
+@end defun
+
@node Windows and Frames
@section Windows and Frames
@@ -521,9 +545,9 @@ its pixel height is the pixel height of the screen areas spanned by its
children.
@end defun
-@cindex window pixel height
-@cindex pixel height of a window
-@cindex total pixel height of a window
+@cindex window pixel width
+@cindex pixel width of a window
+@cindex total pixel width of a window
@defun window-pixel-width &optional Lisp_Object &optional window
This function returns the width of window @var{window} in pixels.
@@ -558,7 +582,6 @@ that of the root window on that frame. If @var{window} is omitted or
@cindex window body height
@cindex body height of a window
-@cindex window body width
The @dfn{body height} of a window is the height of its text area, which
does not include a mode or header line, a horizontal scroll bar, or a
bottom divider.
@@ -578,9 +601,8 @@ counted. It also means that the height of a window's body can never
exceed its total height as returned by @code{window-total-height}.
@end defun
+@cindex window body width
@cindex body width of a window
-@cindex body size of a window
-@cindex window body size
The @dfn{body width} of a window is the width of its text area, which
does not include the scroll bar, fringes, margins or a right divider.
@@ -599,6 +621,8 @@ counted. It also means that the width of a window's body can never
exceed its total width as returned by @code{window-total-width}.
@end defun
+@cindex window body size
+@cindex body size of a window
@defun window-body-size &optional window horizontal pixelwise
This function returns the body height or body width of @var{window}. If
@var{horizontal} is omitted or @code{nil}, it is equivalent to calling
@@ -607,7 +631,7 @@ to calling @code{window-body-width}. In either case, the optional
argument @var{pixelwise} is passed to the function called.
@end defun
- For compatibility with previous versions of Emacs,
+For compatibility with previous versions of Emacs,
@code{window-height} is an alias for @code{window-total-height}, and
@code{window-width} is an alias for @code{window-body-width}. These
aliases are considered obsolete and will be removed in the future.
@@ -635,6 +659,22 @@ Functions for retrieving the height and/or width of window dividers
(@pxref{Scroll Bars}), and display margins (@pxref{Display Margins}) are
described in the corresponding sections.
+If your Lisp program needs to make layout decisions, you will find the
+following function useful:
+
+@defun window-max-chars-per-line &optional window face
+This function returns the number of characters displayed in the
+specified @var{face} in the specified @var{window} (which must be a
+live window). If @var{face} was remapped (@pxref{Face Remapping}),
+the information is returned for the remapped face. If omitted or
+@code{nil}, @var{face} defaults to the default face, and @var{window}
+defaults to the selected window. Unlike @code{window-body-width},
+this function accounts for the actual size of the @var{face}'s font,
+instead of working in units of frame's canonical character width. It
+also accounts for space used by the continuation glyph, if
+@var{window} lacks one or both of its fringes.
+@end defun
+
@cindex fixed-size window
@vindex window-min-height
@vindex window-min-width
@@ -643,7 +683,7 @@ or split them (@pxref{Splitting Windows}), obey the variables
@code{window-min-height} and @code{window-min-width}, which specify the
smallest allowable window height and width. They also obey the variable
@code{window-size-fixed}, with which a window can be @dfn{fixed} in
-size:
+size (@pxref{Preserving Window Sizes}).
@defopt window-min-height
This option specifies the minimum total height, in lines, of any window.
@@ -3082,6 +3122,17 @@ window-start position; if you move point, do not expect the window-start
position to change in response until after the next redisplay.
@end defun
+@defun window-group-start &optional window
+@vindex window-group-start-function
+This function is like @code{window-start}, except that when
+@var{window} is a part of a group of windows (@pxref{Window Group}),
+@code{window-group-start} returns the start position of the entire
+group. This condition holds when the buffer local variable
+@code{window-group-start-function} is set to a function. In this
+case, @code{window-group-start} calls the function with the single
+argument @var{window}, then returns its result.
+@end defun
+
@cindex window end position
@defun window-end &optional window update
This function returns the position where display of its buffer ends in
@@ -3108,6 +3159,18 @@ way real redisplay would do. It does not alter the
text will end if scrolling is not required.
@end defun
+@vindex window-group-end-function
+@defun window-group-end window update
+This function is like @code{window-end}, except that when @var{window}
+is a part of a group of windows (@pxref{Window Group}),
+@code{window-group-end} returns the end position of the entire group.
+This condition holds when the buffer local variable
+@code{window-group-end-function} is set to a function. In this case,
+@code{window-group-end} calls the function with the two arguments
+@var{window} and @var{update}, then returns its result. The argument
+@var{update} has the same meaning as in @code{window-end}.
+@end defun
+
@defun set-window-start window position &optional noforce
This function sets the display-start position of @var{window} to
@var{position} in @var{window}'s buffer. It returns @var{position}.
@@ -3171,6 +3234,19 @@ off screen at the next redisplay, then redisplay computes a new window-start
position that works well with point, and thus @var{position} is not used.
@end defun
+@vindex set-window-group-start-function
+@defun set-window-group-start window position &optional noforce
+This function is like @code{set-window-start}, except that when
+@var{window} is a part of a group of windows (@pxref{Window Group}),
+@code{set-window-group-start} sets the start position of the entire
+group. This condition holds when the buffer local variable
+@code{set-window-group-start-function} is set to a function. In this
+case, @code{set-window-group-start} calls the function with the three
+arguments @var{window}, @var{position}, and @var{noforce}, then
+returns its result. The arguments @var{position} and @var{noforce} in
+this function have the same meaning as in @code{set-window-start}.
+@end defun
+
@defun pos-visible-in-window-p &optional position window partially
This function returns non-@code{nil} if @var{position} is within the
range of text currently visible on the screen in @var{window}. It
@@ -3212,6 +3288,21 @@ Here is an example:
@end example
@end defun
+@vindex pos-visible-in-window-group-p-function
+@defun pos-visible-in-window-group-p &optional position window partially
+This function is like @code{pos-visible-in-window-p}, except that when
+@var{window} is a part of a group of windows (@pxref{Window Group}),
+@code{pos-visible-in-window-group-p} tests the visibility of @var{pos}
+in the entire group, not just in the single @var{window}. This
+condition holds when the buffer local variable
+@code{pos-visible-in-window-group-p-function} is set to a function.
+In this case @code{pos-visible-in-window-group-p} calls the function
+with the three arguments @var{position}, @var{window}, and
+@var{partially}, then returns its result. The arguments
+@var{position} and @var{partially} have the same meaning as in
+@code{pos-visible-in-window-p}.
+@end defun
+
@defun window-line-height &optional line window
This function returns the height of text line @var{line} in
@var{window}. If @var{line} is one of @code{header-line} or
@@ -3455,6 +3546,19 @@ the top of the window. The command @code{recenter-top-bottom} offers
a more convenient way to achieve this.
@end deffn
+@vindex recenter-window-group-function
+@defun recenter-window-group &optional count
+This function is like @code{recenter}, except that when the selected
+window is part of a group of windows (@pxref{Window Group}),
+@code{recenter-window-group} scrolls the entire group. This condition
+holds when the buffer local variable
+@code{recenter-window-group-function} is set to a function. In this
+case, @code{recenter-window-group} calls the function with the
+argument @var{count}, then returns its result. The argument
+@var{count} has the same meaning as in @code{recenter}, but with
+respect to the entire window group.
+@end defun
+
@defopt recenter-redisplay
If this variable is non-@code{nil}, calling @code{recenter} with a
@code{nil} argument redraws the frame. The default value is
@@ -4264,10 +4368,10 @@ work.
@end defvar
@defvar window-size-change-functions
-This variable holds a list of functions to be called if the size of any
-window changes for any reason. The functions are called just once per
-redisplay, and just once for each frame on which size changes have
-occurred.
+This variable holds a list of functions to be called if the size of
+any window changes for any reason. The functions are called at the
+beginning of a redisplay cycle, and just once for each frame on which
+size changes have occurred.
Each function receives the frame as its sole argument. There is no
direct way to find out which windows on that frame have changed size, or
View Lorry Controller Status