summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--lispref/anti.texi2
-rw-r--r--lispref/commands.texi66
-rw-r--r--lispref/display.texi122
-rw-r--r--lispref/files.texi121
-rw-r--r--lispref/front-cover-1.texi8
-rw-r--r--lispref/locals.texi5
-rw-r--r--lispref/minibuf.texi45
-rw-r--r--lispref/modes.texi37
-rw-r--r--lispref/nonascii.texi34
-rw-r--r--lispref/os.texi7
-rw-r--r--lispref/positions.texi33
-rw-r--r--lispref/syntax.texi23
-rw-r--r--lispref/text.texi219
-rw-r--r--lispref/tips.texi108
-rw-r--r--lispref/windows.texi6
15 files changed, 635 insertions, 201 deletions
diff --git a/lispref/anti.texi b/lispref/anti.texi
index ff216bb514f..776bac1d339 100644
--- a/lispref/anti.texi
+++ b/lispref/anti.texi
@@ -2,7 +2,7 @@
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1999 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@node Antinews, Tips, System Interface, Top
+@node Antinews, Tips, Calendar, Top
@appendix Emacs 20 Antinews
For those users who live backwards in time, here is information about
diff --git a/lispref/commands.texi b/lispref/commands.texi
index 758ffccc1c2..cc8eb5f1f98 100644
--- a/lispref/commands.texi
+++ b/lispref/commands.texi
@@ -18,6 +18,7 @@ are done, and the subroutines that allow Lisp programs to do them.
* Defining Commands:: Specifying how a function should read arguments.
* Interactive Call:: Calling a command, so that it will read arguments.
* Command Loop Info:: Variables set by the command loop for you to examine.
+* Adjusting Point:: Adjustment of point after a command.
* Input Events:: What input looks like when you read it.
* Reading Input:: How to read input events from the keyboard or mouse.
* Special Events:: Events processed immediately and individually.
@@ -726,9 +727,9 @@ if all those events were characters. @xref{Input Events}.
@end defun
@defun this-command-keys-vector
-Like @code{this-command-keys}, except that it always returns
-the events in a vector, so you do never need to deal with the complexities
-of storing input events in a string (@pxref{Strings of Events}).
+Like @code{this-command-keys}, except that it always returns the events
+in a vector, so you don't need to deal with the complexities of storing
+input events in a string (@pxref{Strings of Events}).
@end defun
@tindex clear-this-command-keys
@@ -779,6 +780,35 @@ frame, the value is the frame to which the event was redirected.
@xref{Input Focus}.
@end defvar
+@node Adjusting Point
+@section Adjusting Point After Commands
+
+ It is not easy to display a value of point in the middle of a sequence
+of text that has the @code{display} or @code{composition} property. So
+after a command finishes and returns to the command loop, if point is
+within such a sequence, the command loop normally moves point to the
+edge of the sequence.
+
+ A command can inhibit this feature by setting the variable
+@code{disable-point-adjustment}:
+
+@defvar disable-point-adjustment
+@tindex disable-point-adjustment
+If this variable is non-@code{nil} when a command returns to the command
+loop, then the command loop does not check for text properties such as
+@code{display} and @code{composition}, and does not move point out of
+sequences that have these properties.
+
+The command loop sets this variable to @code{nil} before each command,
+so if a command sets it, the effect applies only to that command.
+@end defvar
+
+@defvar global-disable-point-adjustment
+@tindex global-disable-point-adjustment
+If you set this variable to a non-@code{nil} value, the feature of
+moving point out of these sequences is completely turned off.
+@end defvar
+
@node Input Events
@section Input Events
@cindex events
@@ -1192,6 +1222,7 @@ motion (by reading motion events) until the button is released.
@cindex repeat events
@cindex double-click events
@cindex triple-click events
+@cindex mouse events, repeated
If you press the same mouse button more than once in quick succession
without moving the mouse, Emacs generates special @dfn{repeat} mouse
@@ -1529,6 +1560,8 @@ to an event type which specifies all of them. For example,
@node Accessing Events
@subsection Accessing Events
+@cindex mouse events, accessing the data
+@cindex accessing data of mouse events
This section describes convenient functions for accessing the data in
a mouse button or motion event.
@@ -1557,6 +1590,7 @@ event, the value is actually the starting position, which is the only
position such events have.
@end defun
+@cindex mouse position list, accessing
These five functions take a position list as described above, and
return various parts of it.
@@ -1579,6 +1613,8 @@ a cons cell @code{(@var{col} . @var{row})}. These are computed from the
@var{x} and @var{y} values actually found in @var{position}.
@end defun
+@cindex mouse event, timestamp
+@cindex timestamp of a mouse event
@defun posn-timestamp position
Return the timestamp in @var{position}.
@end defun
@@ -1614,6 +1650,8 @@ of a pair of x and y coordinates.
@node Strings of Events
@subsection Putting Keyboard Events in Strings
+@cindex keyboard events in strings
+@cindex strings with keyboard events
In most of the places where strings are used, we conceptualize the
string as containing text characters---the same kind of characters found
@@ -1818,17 +1856,24 @@ button-down events entirely. It also reshuffles focus events and
miscellaneous window events so that they never appear in a key sequence
with any other events.
+@cindex @code{header-line} prefix key
+@cindex @code{mode-line} prefix key
+@cindex @code{vertical-line} prefix key
+@cindex @code{horizontal-scroll-bar} prefix key
+@cindex @code{vertical-scroll-bar} prefix key
+@cindex @code{menu-bar} prefix key
+@cindex mouse events, in special parts of frame
When mouse events occur in special parts of a window, such as a mode
line or a scroll bar, the event type shows nothing special---it is the
same symbol that would normally represent that combination of mouse
button and modifier keys. The information about the window part is kept
elsewhere in the event---in the coordinates. But
@code{read-key-sequence} translates this information into imaginary
-``prefix keys'', all of which are symbols: @code{mode-line},
-@code{vertical-line}, @code{horizontal-scroll-bar} and
-@code{vertical-scroll-bar}. You can define meanings for mouse clicks in
-special window parts by defining key sequences using these imaginary
-prefix keys.
+``prefix keys'', all of which are symbols: @code{heder-line},
+@code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line},
+@code{vertical-line}, and @code{vertical-scroll-bar}. You can define
+meanings for mouse clicks in special window parts by defining key
+sequences using these imaginary prefix keys.
For example, if you call @code{read-key-sequence} and then click the
mouse on the window's mode line, you get two events, like this:
@@ -1856,6 +1901,8 @@ from the terminal---not counting those generated by keyboard macros.
@node Reading One Event
@subsection Reading One Event
+@cindex reading a single event
+@cindex event, reading only one
The lowest level functions for command input are those that read a
single event.
@@ -1960,7 +2007,8 @@ buffer.
The input method function should return a list of events which should
be used as input. (If the list is @code{nil}, that means there is no
input, so @code{read-event} waits for another event.) These events are
-processed before the events in @code{unread-command-events}. Events
+processed before the events in @code{unread-command-events}
+(@pxref{Event Input Misc}). Events
returned by the input method function are not passed to the input method
function again, even if they are printing characters with no modifier
bits.
diff --git a/lispref/display.texi b/lispref/display.texi
index 4c25880d4b7..c60d137f740 100644
--- a/lispref/display.texi
+++ b/lispref/display.texi
@@ -919,7 +919,7 @@ current buffer.
The arguments @var{front-advance} and @var{rear-advance} specify the
insertion type for the start of the overlay and for the end of the
-overlay. @xref{Marker Insertion Types}.
+overlay, respectively. @xref{Marker Insertion Types}.
@end defun
@defun overlay-start overlay
@@ -938,19 +938,22 @@ This function returns the buffer that @var{overlay} belongs to.
@defun delete-overlay overlay
This function deletes @var{overlay}. The overlay continues to exist as
-a Lisp object, but ceases to be attached to the buffer it belonged to,
-and ceases to have any effect on display.
+a Lisp object, and its property list is unchanged, but it ceases to be
+attached to the buffer it belonged to, and ceases to have any effect on
+display.
-A deleted overlay is not permanently useless. You can give it
-a position in a buffer again by calling @code{move-overlay}.
+A deleted overlay is not permanently disconnected. You can give it a
+position in a buffer again by calling @code{move-overlay}.
@end defun
@defun move-overlay overlay start end &optional buffer
This function moves @var{overlay} to @var{buffer}, and places its bounds
at @var{start} and @var{end}. Both arguments @var{start} and @var{end}
-must specify buffer positions; they may be integers or markers. If
-@var{buffer} is omitted, @var{overlay} stays in the same buffer;
-if @var{overlay} was deleted, it goes into the current buffer.
+must specify buffer positions; they may be integers or markers.
+
+If @var{buffer} is omitted, @var{overlay} stays in the same buffer it
+was already associated with; if @var{overlay} was deleted, it goes into
+the current buffer.
The return value is @var{overlay}.
@@ -960,11 +963,82 @@ update other vital data structures and can cause some overlays to be
``lost''.
@end defun
+ Here are some examples:
+
+@example
+;; @r{Create an overlay.}
+(setq foo (make-overlay 1 10))
+ @result{} #<overlay from 1 to 10 in display.texi>
+(overlay-start foo)
+ @result{} 1
+(overlay-end foo)
+ @result{} 10
+(overlay-buffer foo)
+ @result{} #<buffer display.texi>
+;; @r{Give it a property we can check later.}
+(overlay-put foo 'happy t)
+ @result{} t
+;; @r{Verify the property is present.}
+(overlay-get foo 'happy)
+ @result{} t
+;; @r{Move the overlay.}
+(move-overlay foo 5 20)
+ @result{} #<overlay from 5 to 20 in display.texi>
+(overlay-start foo)
+ @result{} 5
+(overlay-end foo)
+ @result{} 20
+;; @r{Delete the overlay.}
+(delete-overlay foo)
+ @result{} nil
+;; @r{Verify it is deleted.}
+foo
+ @result{} #<overlay in no buffer>
+;; @r{A deleted overlay has no position.}
+(overlay-start foo)
+ @result{} nil
+(overlay-end foo)
+ @result{} nil
+(overlay-buffer foo)
+ @result{} nil
+;; @r{Undelete the overlay.}
+(move-overlay foo 1 20)
+ @result{} #<overlay from 1 to 20 in display.texi>
+;; @r{Verify the results.}
+(overlay-start foo)
+ @result{} 1
+(overlay-end foo)
+ @result{} 20
+(overlay-buffer foo)
+ @result{} #<buffer display.texi>
+;; @r{Moving and deleting the overlay don't change its properties.}
+(overlay-get foo 'happy)
+ @result{} t
+@end example
+
+@node Finding Overlays
+@subsection Searching for Overlays
+
@defun overlays-at pos
-This function returns a list of all the overlays that contain position
-@var{pos} in the current buffer. The list is in no particular order.
-An overlay contains position @var{pos} if it begins at or before
-@var{pos}, and ends after @var{pos}.
+This function returns a list of all the overlays that cover the
+character at position @var{pos} in the current buffer. The list is in
+no particular order. An overlay contains position @var{pos} if it
+begins at or before @var{pos}, and ends after @var{pos}.
+
+To illustrate usage, here is a Lisp function that returns a list of the
+overlays that specify property @var{prop} for the character at point:
+
+@smallexample
+(defun find-overlays-specifying (prop)
+ (let ((overlays (overlays-at (point)))
+ found)
+ (while overlays
+ (let ((overlay (cdr overlays)))
+ (if (overlay-get overlay prop)
+ (setq found (cons overlay found))))
+ (setq overlays (cdr overlays)))
+ found))
+@end smallexample
@end defun
@defun overlays-in beg end
@@ -973,7 +1047,7 @@ This function returns a list of the overlays that overlap the region
@var{beg} through @var{end}. ``Overlap'' means that at least one
character is contained within the overlay and also contained within the
specified region; however, empty overlays are included in the result if
-they are located at @var{beg} or between @var{beg} and @var{end}.
+they are located at @var{beg}, or strictly between @var{beg} and @var{end}.
@end defun
@defun next-overlay-change pos
@@ -986,6 +1060,20 @@ This function returns the buffer position of the previous beginning or
end of an overlay, before @var{pos}.
@end defun
+ Here's an easy way to use @code{next-overlay-change} to search for the
+next character which gets a non-@code{nil} @code{happy} property from
+either its overlays or its text properties (@pxref{Property Search}):
+
+@smallexample
+(defun find-overlay-prop (prop)
+ (save-excursion
+ (while (and (not (eobp))
+ (not (get-char-property (point) 'happy)))
+ (goto-char (min (next-overlay-change (point))
+ (next-single-property-change (point) 'happy))))
+ (point)))
+@end smallexample
+
@node Width
@section Width
@@ -1782,7 +1870,6 @@ expression in the list. For example,
@noindent
allows the use of scalable fonts with registry @code{muleindian-2}.
@end example
-@end defvar
@defun clear-face-cache &optional unload-p
@tindex clear-face-cache
@@ -2809,6 +2896,13 @@ The value of this variable is the default value for @code{ctl-arrow} in
buffers that do not override it. @xref{Default Value}.
@end defvar
+@defopt indicate-empty-lines
+@tindex indicate-empty-lines
+When this is non-@code{nil}, Emacs displays a special glyph in
+each empty line at the end of the buffer, on terminals that
+support it (window systems).
+@end defopt
+
@defopt tab-width
The value of this variable is the spacing between tab stops used for
displaying tab characters in Emacs buffers. The value is in units of
diff --git a/lispref/files.texi b/lispref/files.texi
index f82e724e4da..369c3d090c9 100644
--- a/lispref/files.texi
+++ b/lispref/files.texi
@@ -20,6 +20,12 @@ expand file name arguments by calling @code{expand-file-name}, so that
@samp{../}). These functions don't recognize environment variable
substitutions such as @samp{$HOME}. @xref{File Name Expansion}.
+ When file I/O functions signal Lisp errors, they usually use the
+condition @code{file-error} (@pxref{Handling Errors}). The error
+message is in most cases obtained from the operating system, according
+to locale @code{system-message-locale}, and decoded using coding system
+@code{locale-coding-system} (@pxref{Locales}).
+
@menu
* Visiting Files:: Reading files into Emacs buffers for editing.
* Saving Buffers:: Writing changed buffers back into files.
@@ -250,7 +256,7 @@ This function is used by @code{find-file-noselect}.
It uses @code{generate-new-buffer} (@pxref{Creating Buffers}).
@end defun
-@defun after-find-file &optional error warn
+@defun after-find-file &optional error warn noauto after-find-file-from-revert-buffer nomodes
This function sets the buffer major mode, and parses local variables
(@pxref{Auto Major Mode}). It is called by @code{find-file-noselect}
and by the default revert function (@pxref{Reverting}).
@@ -266,6 +272,19 @@ call @code{after-find-file}.
If @var{warn} is non-@code{nil}, then this function issues a warning
if an auto-save file exists and is more recent than the visited file.
+If @var{noauto} is non-@code{nil}, that says not to enable or disable
+Auto-Save mode. The mode remains enabled if it was enabled before.
+
+If @var{after-find-file-from-revert-buffer} is non-@code{nil}, that
+means this call was from @code{revert-buffer}. This has no direct
+effect, but some mode functions and hook functions check the value
+of this variable.
+
+If @var{nomodes} is non-@code{nil}, that means don't alter the buffer's
+major mode, don't process local variables specifications in the file,
+and don't run @code{find-file-hooks}. This feature is used by
+@code{revert-buffer} in some cases.
+
The last thing @code{after-find-file} does is call all the functions
in the list @code{find-file-hooks}.
@end defun
@@ -318,13 +337,16 @@ saving one of these is asked to specify a file name to use.) The
for this argument.
@end deffn
-@deffn Command write-file filename
+@deffn Command write-file filename &optional confirm
This function writes the current buffer into file @var{filename}, makes
the buffer visit that file, and marks it not modified. Then it renames
the buffer based on @var{filename}, appending a string like @samp{<2>}
if necessary to make a unique buffer name. It does most of this work by
calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and
@code{save-buffer}.
+
+If @var{confirm} is non-@code{nil}, that means to ask for confirmation
+before overwriting an existing file.
@end deffn
Saving a buffer runs several hooks. It also performs format
@@ -512,7 +534,7 @@ An error is signaled if @var{filename} specifies a nonwritable file,
or a nonexistent file in a directory where files cannot be created.
@end deffn
-@deffn Command write-region start end filename &optional append visit mustbenew
+@deffn Command write-region start end filename &optional append visit lockname mustbenew
This function writes the region delimited by @var{start} and @var{end}
in the current buffer into the file specified by @var{filename}.
@@ -552,6 +574,10 @@ the buffer as visiting another file (@var{visit}). The argument
to implement @code{file-precious-flag}; don't use it yourself unless you
really know what you're doing.
+The optional argument @var{lockname}, if non-@code{nil}, specifies the
+file name to use for purposes of locking and unlocking, overriding
+@var{filename} and @var{visit} for that purpose.
+
The function @code{write-region} converts the data which it writes to
the appropriate file formats specified by @code{buffer-file-format}.
@xref{Format Conversion}. It also calls the functions in the list
@@ -692,10 +718,10 @@ or directories unless otherwise noted.
These functions test for permission to access a file in specific ways.
@defun file-exists-p filename
-This function returns @code{t} if a file named @var{filename} appears
-to exist. This does not mean you can necessarily read the file, only
-that you can find out its attributes. (On Unix, this is true if the
-file exists and you have execute permission on the containing
+This function returns @code{t} if a file named @var{filename} appears to
+exist. This does not mean you can necessarily read the file, only that
+you can find out its attributes. (On Unix and GNU/Linux, this is true
+if the file exists and you have execute permission on the containing
directories, regardless of the protection of the file itself.)
If the file does not exist, or if fascist access control policies
@@ -726,10 +752,10 @@ and you can read it. It returns @code{nil} otherwise.
@c Emacs 19 feature
@defun file-executable-p filename
This function returns @code{t} if a file named @var{filename} exists and
-you can execute it. It returns @code{nil} otherwise. On Unix, if the
-file is a directory, execute permission means you can check the
-existence and attributes of files inside the directory, and open those
-files if their modes permit.
+you can execute it. It returns @code{nil} otherwise. On Unix and
+GNU/Linux, if the file is a directory, execute permission means you can
+check the existence and attributes of files inside the directory, and
+open those files if their modes permit.
@end defun
@defun file-writable-p filename
@@ -906,19 +932,39 @@ other I/O device).
@c Emacs 19 features
The @dfn{truename} of a file is the name that you get by following
-symbolic links until none remain, then simplifying away @samp{.}@: and
-@samp{..}@: appearing as components. Strictly speaking, a file need not
-have a unique truename; the number of distinct truenames a file has is
-equal to the number of hard links to the file. However, truenames are
-useful because they eliminate symbolic links as a cause of name
-variation.
+symbolic links at all levels until none remain, then simplifying away
+@samp{.}@: and @samp{..}@: appearing as name components. This results
+in a sort of canonical name for the file. A file does not always have a
+unique truename; the number of distinct truenames a file has is equal to
+the number of hard links to the file. However, truenames are useful
+because they eliminate symbolic links as a cause of name variation.
@defun file-truename filename
-The function @code{file-truename} returns the true name of the file
-@var{filename}. This is the name that you get by following symbolic
-links until none remain. The argument must be an absolute file name.
+The function @code{file-truename} returns the truename of the file
+@var{filename}. The argument must be an absolute file name.
@end defun
+@defun file-chase-links filename
+This function follows symbolic links, starting with @var{filename},
+until it finds a file name which is not the name of a symbolic link.
+Then it returns that file name.
+@end defun
+
+ To illustrate the difference between @code{file-chase-links} and
+@code{file-truename}, suppose that @file{/usr/foo} is a symbolic link to
+the directory @file{/home/foo}, and @file{/home/foo/hello} is an
+ordinary file (or at least, not a symbolic link) or nonexistent. Then
+we would have:
+
+@example
+(file-chase-links "/usr/foo/hello")
+ ;; @r{This does not follow the links in the parent directories.}
+ @result{} "/usr/foo/hello"
+(file-truename "/usr/foo/hello")
+ ;; @r{Assuming that @file{/home} is not a symbolic link.}
+ @result{} "/home/foo/hello"
+@end example
+
@xref{Buffer File Name}, for related information.
@node File Attributes
@@ -1242,9 +1288,9 @@ This command deletes the file @var{filename}, like the shell command
@samp{rm @var{filename}}. If the file has multiple names, it continues
to exist under the other names.
-A suitable kind of @code{file-error} error is signaled if the file
-does not exist, or is not deletable. (On Unix, a file is deletable if
-its directory is writable.)
+A suitable kind of @code{file-error} error is signaled if the file does
+not exist, or is not deletable. (On Unix and GNU/Linux, a file is
+deletable if its directory is writable.)
See also @code{delete-directory} in @ref{Create/Delete Dirs}.
@end deffn
@@ -1278,8 +1324,8 @@ be an integer). Only the low 12 bits of @var{mode} are used.
@defun set-default-file-modes mode
This function sets the default file protection for new files created by
Emacs and its subprocesses. Every file created with Emacs initially has
-this protection. On Unix, the default protection is the bitwise
-complement of the ``umask'' value.
+this protection. On Unix and GNU/Linux, the default protection is the
+bitwise complement of the ``umask'' value.
The argument @var{mode} must be an integer. On most systems, only the
low 9 bits of @var{mode} are meaningful.
@@ -1406,9 +1452,13 @@ This function returns the nondirectory part of @var{filename}.
@end example
@end defun
-@defun file-name-sans-versions filename
+@defun file-name-sans-versions filename &optional keep-backup-version
This function returns @var{filename} with any file version numbers,
-backup version numbers, or trailing tildes deleted.
+backup version numbers, or trailing tildes discarded.
+
+If @var{keep-backup-version} is non-@code{nil}, then true file version
+numbers understood as such by the file system are discarded from the
+return value, but backup version numbers are kept.
@example
@group
@@ -1545,12 +1595,12 @@ directory.
root directory. A file name can specify all the directory names
starting from the root of the tree; then it is called an @dfn{absolute}
file name. Or it can specify the position of the file in the tree
-relative to a default directory; then it is called a @dfn{relative}
-file name. On Unix, an absolute file name starts with a slash or a
-tilde (@samp{~}), and a relative one does not. On MS-DOS and
+relative to a default directory; then it is called a @dfn{relative} file
+name. On Unix and GNU/Linux, an absolute file name starts with a slash
+or a tilde (@samp{~}), and a relative one does not. On MS-DOS and
MS-Windows, an absolute file name starts with a slash or a backslash, or
with a drive specification @samp{@var{x}:/}, where @var{x} is the
-@dfn{drive letter}. The rules on VMS are complicated.
+@dfn{drive letter}. The rules on VMS are complicated.
@defun file-name-absolute-p filename
This function returns @code{t} if file @var{filename} is an absolute
@@ -1625,10 +1675,11 @@ variables; only @code{substitute-in-file-name} does that.
@end defun
@c Emacs 19 feature
-@defun file-relative-name filename directory
+@defun file-relative-name filename &optional directory
This function does the inverse of expansion---it tries to return a
relative name that is equivalent to @var{filename} when interpreted
-relative to @var{directory}.
+relative to @var{directory}. If @var{directory} is omitted or
+@code{nil}, it defaults to the current buffer's default directory.
On some operating systems, an absolute file name begins with a device
name. On such systems, @var{filename} has no relative equivalent based
@@ -2053,8 +2104,10 @@ files that are directories. For example, you cannot delete a directory
with @code{delete-file}. These special functions exist to create and
delete directories.
-@defun make-directory dirname
+@defun make-directory dirname &optional parents
This function creates a directory named @var{dirname}.
+If @var{parents} is non-@code{nil}, that means to create
+the parent directories first, if they don't already exist.
@end defun
@defun delete-directory dirname
diff --git a/lispref/front-cover-1.texi b/lispref/front-cover-1.texi
index cde9f952e9a..71ecd6a35da 100644
--- a/lispref/front-cover-1.texi
+++ b/lispref/front-cover-1.texi
@@ -18,9 +18,9 @@
@sp 1
@center @titlefont{Manual}
@sp 2
-@center GNU Emacs Version 19
+@center GNU Emacs Version 19.29
@center for Unix Users
-@center Edition 2.3, June 1994
+@center Edition 2.4, June 1995
@sp 2
@center @titlefont{Volume 1}
@sp 2
@@ -39,9 +39,9 @@
@sp 1
@center @titlefont{Manual}
@sp 2
-@center GNU Emacs Version 19
+@center GNU Emacs Version 19.29
@center for Unix Users
-@center Edition 2.3, June 1994
+@center Edition 2.4, June 1995
@sp 2
@center @titlefont{Volume 2}
@sp 2
diff --git a/lispref/locals.texi b/lispref/locals.texi
index 1334b71f9ca..f6943df6f41 100644
--- a/lispref/locals.texi
+++ b/lispref/locals.texi
@@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1999 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/locals
@node Standard Buffer-Local Variables, Standard Keymaps, Standard Errors, Top
@@ -148,7 +148,7 @@ use, but we don't try to list them all here.
@xref{Standard Regexps}.
@item point-before-scroll
-Used for communication between mouse commands and scroll-bar commands..
+Used for communication between mouse commands and scroll-bar commands.
@item require-final-newline
@xref{Insertion}.
@@ -177,4 +177,3 @@ Used for communication between mouse commands and scroll-bar commands..
@item vc-mode
@xref{Mode Line Variables}.
@end table
-
diff --git a/lispref/minibuf.texi b/lispref/minibuf.texi
index 7eacbc64279..f0adf00035a 100644
--- a/lispref/minibuf.texi
+++ b/lispref/minibuf.texi
@@ -45,15 +45,14 @@ nothing but a minibuffer window; see @ref{Minibuffers and Frames}.)
The text in the minibuffer always starts with the @dfn{prompt string},
the text that was specified by the program that is using the minibuffer
to tell the user what sort of input to type. This text is marked
-read-only so you won't accidentally delete or change it. In other
-respects, it is an ordinary part of the buffer contents, but certain
-functions such as @code{erase-buffer}, @code{buffer-string},
-@code{beginning-of-line}, @code{forward-word}, @code{forward-sentence},
-and @code{forward-paragraph}, treat it a little bit specially. (In
-older Emacs versions, the prompt was displayed using a special mechanism
-and was not part of the buffer contents.)
-
-@c ???
+read-only so you won't accidentally delete or change it. It is also
+marked as a field (@pxref{Fields}), so that certain motion functions,
+including @code{beginning-of-line}, @code{forward-word},
+@code{forward-sentence}, and @code{forward-paragraph}, stop at the
+boundary between the prompt and the actual text. (In older Emacs
+versions, the prompt was displayed using a special mechanism and was not
+part of the buffer contents.)
+
The minibuffer's window is normally a single line; it grows
automatically if necessary if the contents require more space. You can
explicitly resize it temporarily with the window sizing commands; it
@@ -94,6 +93,10 @@ just like @key{RET}. This is used mainly for Mocklisp compatibility.
for cautious completion.
@end itemize
+ When Emacs is running in batch mode, any request to read from the
+minibuffer actually reads a line from the standard input descriptor that
+was supplied when Emacs was started.
+
@node Text from Minibuffer
@section Reading Text Strings with the Minibuffer
@@ -1350,7 +1353,7 @@ asking each question individually. This gives the user certain
convenient facilities such as the ability to answer the whole series at
once.
-@defun map-y-or-n-p prompter actor list &optional help action-alist
+@defun map-y-or-n-p prompter actor list &optional help action-alist no-cursor-in-echo-area
This function asks the user a series of questions, reading a
single-character answer in the echo area for each one.
@@ -1419,6 +1422,10 @@ When the user responds with @var{char}, @code{map-y-or-n-p} calls
@var{list}. If it returns @code{nil}, the prompt is repeated for the
same object.
+Normally, @code{map-y-or-n-p} binds @code{cursor-in-echo-area} while
+prompting. But if @var{no-cursor-in-echo-area} is non-@code{nil}, it
+does not do that.
+
If @code{map-y-or-n-p} is called in a command that was invoked using the
mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command
Loop Info}) is either @code{nil} or a list---then it uses a dialog box
@@ -1480,16 +1487,16 @@ This command replaces the minibuffer contents with the value of the
@var{n}th more recent history element.
@end deffn
-@deffn Command previous-matching-history-element pattern
+@deffn Command previous-matching-history-element pattern n
This command replaces the minibuffer contents with the value of the
-previous (older) history element that matches @var{pattern} (a regular
-expression).
+@var{n}th previous (older) history element that matches @var{pattern} (a
+regular expression).
@end deffn
-@deffn Command next-matching-history-element pattern
-This command replaces the minibuffer contents with the value of the next
-(newer) history element that matches @var{pattern} (a regular
-expression).
+@deffn Command next-matching-history-element pattern n
+This command replaces the minibuffer contents with the value of the
+@var{n}th next (newer) history element that matches @var{pattern} (a
+regular expression).
@end deffn
@defun minibuffer-prompt
@@ -1497,8 +1504,8 @@ This function returns the prompt string of the currently active
minibuffer. If no minibuffer is active, it returns @code{nil}.
@end defun
-@tindex minubuffer-prompt-end
-@defun minubuffer-prompt-end
+@tindex minibuffer-prompt-end
+@defun minibuffer-prompt-end
This function, available starting in Emacs 21, returns the current
position of the end of the minibuffer prompt, if a minibuffer is
current. Otherwise, it returns zero.
diff --git a/lispref/modes.texi b/lispref/modes.texi
index d6c14e521ca..0276f20e538 100644
--- a/lispref/modes.texi
+++ b/lispref/modes.texi
@@ -810,7 +810,7 @@ keymaps make this easier than it used to be.
@menu
* Minor Mode Conventions:: Tips for writing a minor mode.
* Keymaps and Minor Modes:: How a minor mode can have its own keymap.
-* Easy-Mmode:: A convenient facility for defining minor modes.
+* Defining Minor Modes:: A convenient facility for defining minor modes.
@end menu
@node Minor Mode Conventions
@@ -961,23 +961,25 @@ followed by a punctuation character @emph{other than} @kbd{@{},
@kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:}, and @kbd{;}. (Those few punctuation
characters are reserved for major modes.)
-@node Easy-Mmode
-@subsection Easy-Mmode
+@node Defining Minor Modes
+@subsection Defining Minor Modes
- The easy-mmode package provides a convenient way of implementing a
-mode in one self-contained definition. It currently supports only
+ The macro @code{define-minor-mode} offers a convenient way of
+implementing a mode in one self-contained definition. It supports only
buffer-local minor modes, not global ones.
-@defmac easy-mmode-define-minor-mode mode doc &optional init-value mode-indicator keymap
-@tindex easy-mmode-define-minor-mode
+@defmac define-minor-mode mode doc &optional init-value mode-indicator keymap body...
+@tindex define-minor-mode
This macro defines a new minor mode whose name is @var{mode} (a symbol).
+It defines a command named @var{mode} to toggle the minor
+mode, with @var{doc} as its documentation string. It also defines a
+variable named @var{mode}, which is set to @code{t} or @code{nil} by
+enabling or disabling the mode. The variable is initialized to
+@var{init-value}.
-This macro defines a command named @var{mode} which toggles the minor
-mode, and has @var{doc} as its documentation string.
-
-It also defines a variable named @var{mode}, which is set to @code{t} or
-@code{nil} by enabling or disabling the mode. The variable is
-initialized to @var{init-value}.
+The command named @var{mode} finishes by executing the @var{body} forms,
+if any, after it has performed the standard actions such as setting
+the variable named @var{mode}.
The string @var{mode-indicator} says what to display in the mode line
when the mode is enabled; if it is @code{nil}, the mode is not displayed
@@ -992,10 +994,10 @@ specifying bindings in this form:
@end example
@end defmac
- Here is an example of using @code{easy-mmode-define-minor-mode}:
+ Here is an example of using @code{define-minor-mode}:
@smallexample
-(easy-mmode-define-minor-mode hungry-mode
+(define-minor-mode hungry-mode
"Toggle Hungry mode.
With no argument, this command toggles the mode.
Non-null prefix argument turns on the mode.
@@ -1024,6 +1026,11 @@ which indicates whether the mode is enabled, and a variable named
mode is enabled. It initializes the keymap with key bindings for
@kbd{C-@key{DEL}} and @kbd{C-M-@key{DEL}}.
+
+@findex easy-mmode-define-minor-mode
+ The name @code{easy-mmode-define-minor-mode} is an alias
+for this macro.
+
@node Mode Line Format
@section Mode Line Format
@cindex mode line
diff --git a/lispref/nonascii.texi b/lispref/nonascii.texi
index 053bdbe4f50..1f3bf589860 100644
--- a/lispref/nonascii.texi
+++ b/lispref/nonascii.texi
@@ -23,6 +23,7 @@ characters and how they are stored in strings and buffers.
* Translation of Characters::
* Coding Systems::
* Input Methods::
+* Locales:: Interacting with the POSIX locale.
@end menu
@node Text Representations
@@ -1219,3 +1220,36 @@ the @var{args}.
The fundamental interface to input methods is through the
variable @code{input-method-function}. @xref{Reading One Event}.
+
+@node Locales
+@section Locales
+@cindex locale
+
+ POSIX defines a concept of ``locales'' which control which language
+to use in language-related features. These Emacs variables control
+how Emacs interacts with these features.
+
+@defvar locale-coding-system
+@tindex locale-coding-system
+This variable specifies the coding system to use for decoding system
+error messages, for encoding the format argument to
+@code{format-time-string}, and for decoding the return value of
+@code{format-time-string}.
+@end defvar
+
+@defvar system-messages-locale
+@tindex system-messages-locale
+This variable specifies the locale to use for generating system error
+messages. Changing the locale can cause messages to come out in a
+different language or in a different orthorgraphy. If the variable is
+@code{nil}, the locale is specified by environment variables in the
+usual POSIX fashion.
+@end defvar
+
+@defvar system-time-locale
+@tindex system-time-locale
+This variable specifies the locale to use for formatting time values.
+Changing the locale can cause messages to appear according to the
+conventions of a different language. If the variable is @code{nil}, the
+locale is specified by environment variables in the usual POSIX fashion.
+@end defvar
diff --git a/lispref/os.texi b/lispref/os.texi
index 406979553e0..6600f45da00 100644
--- a/lispref/os.texi
+++ b/lispref/os.texi
@@ -1090,6 +1090,13 @@ is allowed with most letters, all the ones that output numbers.
If @var{universal} is non-@code{nil}, that means to describe the time as
Universal Time; @code{nil} means describe it using what Emacs believes
is the local time zone (see @code{current-time-zone}).
+
+This function uses the C library function @code{strftime} to do most of
+the work. In order to communicate with that function, it first encodes
+its argument using the coding system specified by
+@code{locale-coding-system} (@pxref{Locales}); after @code{strftime}
+returns the resulting string, @code{format-time-string} decodes the
+string using that same coding system.
@end defun
@defun decode-time time
diff --git a/lispref/positions.texi b/lispref/positions.texi
index 49c42bc1d3c..54d6ed543e4 100644
--- a/lispref/positions.texi
+++ b/lispref/positions.texi
@@ -19,6 +19,9 @@ also be represented as @dfn{markers}---special objects that relocate
automatically when text is inserted or deleted so they stay with the
surrounding characters. @xref{Markers}.
+ See also the ``field'' feature (@pxref{Fields}), which provides
+functions that are used by many cursur-motion commands.
+
@menu
* Point:: The special position where editing takes place.
* Motion:: Changing point.
@@ -185,18 +188,17 @@ whether a given character is part of a word. @xref{Syntax Tables}.
This function moves point forward @var{count} words (or backward if
@var{count} is negative). ``Moving one word'' means moving until point
crosses a word-constituent character and then encounters a
-word-separator character (or the boundary of the accessible part of the
-buffer).
-
-If it is possible to move @var{count} words, without being stopped by
-the buffer boundary (except perhaps after the last word), the value is
-@code{t}. Otherwise, the return value is @code{nil} and point stops
-at the buffer boundary.
+word-separator character. However, this function cannot move point past
+the boundary of the accessible part of the buffer, or across a field
+boundary (@pxref{Fields}). The most common case of a field boundary is
+the end of the prompt in the minibuffer.
-In the minibuffer, the end of the prompt always acts as a word boundary,
-regardless of what characters appear before and after it.
+If it is possible to move @var{count} words, without being stopped
+prematurely by the buffer boundary or a field boundary, the value is
+@code{t}. Otherwise, the return value is @code{nil} and point stops at
+the buffer boundary or field boundary.
-In an interactive call, @var{count} is set to the numeric prefix
+In an interactive call, @var{count} is specified by the numeric prefix
argument.
@end deffn
@@ -317,8 +319,10 @@ If this function reaches the end of the buffer (or of the accessible
portion, if narrowing is in effect), it positions point there. No error
is signaled.
-As a special feature, in the minibuffer, this command will not
-move back into the prompt, if it starts from after the prompt.
+This function does not move across a field boundary (@pxref{Fields}),
+unless it moves to another line beyond the one that contains the field
+boundary. If @var{count} is zero, and point starts at a field boundary,
+then point does not move.
@end deffn
@defun line-beginning-position &optional count
@@ -335,6 +339,11 @@ argument @var{count} not @code{nil} or 1, it moves forward
If this function reaches the end of the buffer (or of the accessible
portion, if narrowing is in effect), it positions point there. No error
is signaled.
+
+This function does not move across a field boundary, unless it moves to
+another line beyond the one that contains the field boundary. If
+@var{count} is zero, and point starts at a field boundary, then point
+does not move.
@end deffn
@defun line-end-position &optional count
diff --git a/lispref/syntax.texi b/lispref/syntax.texi
index 55713e7ef50..34f591784f3 100644
--- a/lispref/syntax.texi
+++ b/lispref/syntax.texi
@@ -507,6 +507,18 @@ This function returns the current syntax table, which is the table for
the current buffer.
@end defun
+@defmac with-syntax-table @var{table} @var{body}...
+@tindex with-syntax-table
+This macro executes @var{body} using @var{table} as the current syntax
+table. It returns the value of the last form in @var{body}, after
+restoring the old current syntax table.
+
+Since each buffer has its own current syntax table, we should make that
+more precise: @code{with-syntax-table} temporarily alters the current
+syntax table of whichever buffer is current at the time the macro
+execution starts. Other buffers are not affected.
+@end defmac
+
@node Syntax Properties
@section Syntax Properties
@kindex syntax-table @r{(text property)}
@@ -939,6 +951,14 @@ This function makes @var{table} the category table for the current
buffer. It returns @var{table}.
@end defun
+@defun make-category-table &optional default-set
+@tindex make-category-table
+This creates and returns an empty category table, using
+@var{default-set} as the default (for characters that don't specify
+their own sets). Initially no characters specify their own sets in this
+new table; that is what we mean by ``empty.''
+@end defun
+
@defun make-category-set categories
This function returns a new category set---a bool-vector---whose initial
contents are the categories listed in the string @var{categories}. The
@@ -967,7 +987,8 @@ the category table.
@defun category-set-mnemonics category-set
This function converts the category set @var{category-set} into a string
-containing the names of all the categories that are members of the set.
+containing the characters that designate the categories that are members
+of the set.
@example
(category-set-mnemonics (char-category-set ?a))
diff --git a/lispref/text.texi b/lispref/text.texi
index 64f1eab77d7..da1819b171e 100644
--- a/lispref/text.texi
+++ b/lispref/text.texi
@@ -220,9 +220,6 @@ This is the contents of buffer foo
"
@end group
@end example
-
-When this function is used in the minibuffer, the value does not include
-the prompt.
@end defun
@defun thing-at-point thing
@@ -306,7 +303,7 @@ to point after the inserted text, regardless of the markers' insertion
type.
Insertion functions signal an error if the current buffer is
-read-only.
+read-only or if they insert within read-only text.
These functions copy text characters from strings and buffers along
with their properties. The inserted characters have exactly the same
@@ -486,10 +483,9 @@ return a value of @code{nil}.
@deffn Command erase-buffer
This function deletes the entire text of the current buffer, leaving it
empty. If the buffer is read-only, it signals a @code{buffer-read-only}
-error. Otherwise, it deletes the text without asking for any
-confirmation. It returns @code{nil}.
-
-In the minibuffer, @code{erase-buffer} does not delete the prompt.
+error; if some of the text in it is read-only, it signals a
+@code{text-read-only} error. Otherwise, it deletes the text without
+asking for any confirmation. It returns @code{nil}.
Normally, deleting a large amount of text from a buffer inhibits further
auto-saving of that buffer ``because it has shrunk''. However,
@@ -791,16 +787,16 @@ In an interactive call, @var{start} and @var{end} are point and
the mark.
@c Emacs 19 feature
-If the buffer is read-only, @code{kill-region} modifies the kill ring
-just the same, then signals an error without modifying the buffer. This
-is convenient because it lets the user use all the kill commands to copy
-text into the kill ring from a read-only buffer.
+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.
+This is convenient because it lets the user use a series of kill
+commands to copy text from a read-only buffer into the kill ring.
@end deffn
@defopt kill-read-only-ok
-If this option is non-@code{nil}, @code{kill-region} does not get an
-error if the buffer is read-only. Instead, it simply returns, updating
-the kill ring but not changing the buffer.
+If this option is non-@code{nil}, @code{kill-region} does not signal an
+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
@@ -1219,7 +1215,7 @@ The variable @code{paragraph-separate} controls how to distinguish
paragraphs. @xref{Standard Regexps}.
@end deffn
-@deffn Command fill-individual-paragraphs start end &optional justify mail-flag
+@deffn Command fill-individual-paragraphs start end &optional justify citation-regexp
This command fills each paragraph in the region according to its
individual fill prefix. Thus, if the lines of a paragraph were indented
with spaces, the filled paragraph will remain indented in the same
@@ -1227,11 +1223,13 @@ fashion.
The first two arguments, @var{start} and @var{end}, are the beginning
and end of the region to be filled. The third and fourth arguments,
-@var{justify} and @var{mail-flag}, are optional. If
+@var{justify} and @var{citation-regexp}, are optional. If
@var{justify} is non-@code{nil}, the paragraphs are justified as
-well as filled. If @var{mail-flag} is non-@code{nil}, it means the
+well as filled. If @var{citation-regexp} is non-@code{nil}, it means the
function is operating on a mail message and therefore should not fill
-the header lines.
+the header lines. If @var{citation-regexp} is a string, it is used as
+a regular expression; if it matches the beginning of a line, that line
+is treated as a citation marker.
Ordinarily, @code{fill-individual-paragraphs} regards each change in
indentation as starting a new paragraph. If
@@ -1262,7 +1260,7 @@ In Adaptive Fill mode, this command calls @code{fill-context-prefix} to
choose a fill prefix by default. @xref{Adaptive Fill}.
@end deffn
-@deffn Command justify-current-line how eop nosqueeze
+@deffn Command justify-current-line &optional how eop nosqueeze
This command inserts spaces between the words of the current line so
that the line ends exactly at @code{fill-column}. It returns
@code{nil}.
@@ -1395,11 +1393,12 @@ If @var{force} is non-@code{nil}, that says to fix the line's
indentation if that doesn't match the left margin value.
@end deffn
-@defun delete-to-left-margin from to
-This function removes left margin indentation from the text
-between @var{from} and @var{to}. The amount of indentation
-to delete is determined by calling @code{current-left-margin}.
-In no case does this function delete non-whitespace.
+@defun delete-to-left-margin &optional from to
+This function removes left margin indentation from the text between
+@var{from} and @var{to}. The amount of indentation to delete is
+determined by calling @code{current-left-margin}. In no case does this
+function delete non-whitespace. If @var{from} and @var{to} are omitted,
+they default to the whole buffer.
@end defun
@defun indent-to-left-margin
@@ -1442,6 +1441,9 @@ This function implements the heart of Adaptive Fill mode; it chooses a
fill prefix based on the text between @var{from} and @var{to}. It does
this by looking at the first two lines of the paragraph, based on the
variables described below.
+@c The optional argument first-line-regexp is not documented
+@c because it exists for internal purposes and might be eliminated
+@c in the future.
@end defun
@defopt adaptive-fill-regexp
@@ -2255,6 +2257,8 @@ along with the characters; this includes such diverse functions as
only when text is examined.
* Clickable Text:: Using text properties to make regions of text
do something when you click on them.
+* Fields:: The @code{field} property defines
+ fields within the buffer.
* Not Intervals:: Why text properties do not use
Lisp-visible text intervals.
@end menu
@@ -2329,7 +2333,7 @@ properties specified by name.
Since text properties are considered part of the contents of the
buffer (or string), and can affect how a buffer looks on the screen, any
-change in buffer text properties mark the buffer as modified. Buffer
+change in buffer text properties marks the buffer as modified. Buffer
text property changes are undoable also (@pxref{Undo}).
@defun put-text-property start end prop value &optional object
@@ -2658,7 +2662,8 @@ about this particular character. @xref{Syntax Properties}.
@cindex read-only character
@kindex read-only @r{(text property)}
If a character has the property @code{read-only}, then modifying that
-character is not allowed. Any command that would do so gets an error.
+character is not allowed. Any command that would do so gets an error,
+@code{text-read-only}.
Insertion next to a read-only character is an error if inserting
ordinary text there would inherit the @code{read-only} property due to
@@ -2686,6 +2691,13 @@ point actually moves to the start of the group.
When the variable @code{inhibit-point-motion-hooks} is non-@code{nil},
the @code{intangible} property is ignored.
+@item field
+@kindex field @r{(text property)}
+Consecutive characters with the same @code{field} property constitute a
+@dfn{field}. Some motion functions including @code{forward-word} and
+@code{beginning-of-line} stop moving at a field boundary.
+@xref{Fields}.
+
@item modification-hooks
@cindex change hooks for a character
@cindex hooks for changing a character
@@ -2799,16 +2811,23 @@ section. Self-inserting characters inherit properties because they work
using these primitives.
When you do insertion with inheritance, @emph{which} properties are
-inherited depends on two specific properties: @code{front-sticky} and
-@code{rear-nonsticky}.
-
- Insertion after a character inherits those of its properties that are
+inherited, and from where, depends on which properties are @dfn{sticky}.
+Insertion after a character inherits those of its properties that are
@dfn{rear-sticky}. Insertion before a character inherits those of its
-properties that are @dfn{front-sticky}. By default, a text property is
-rear-sticky but not front-sticky. Thus, the default is to inherit all
-the properties of the preceding character, and nothing from the
-following character. You can request different behavior by specifying
-the stickiness of certain properties.
+properties that are @dfn{front-sticky}. When both sides offer different
+sticky values for the same property, the previous character's value
+takes precedence.
+
+ By default, a text property is rear-sticky but not front-sticky; thus,
+the default is to inherit all the properties of the preceding character,
+and nothing from the following character.
+
+ You can control the stickiness of various text properties with two
+specific text properties, @code{front-sticky} and @code{rear-nonsticky},
+and with the variable @code{text-property-default-nonsticky}. You can
+use the variable to specify a different default for a given property.
+You can use those two text properties to make any specific properties
+sticky or nonsticky in any particular part of the text.
If a character's @code{front-sticky} property is @code{t}, then all
its properties are front-sticky. If the @code{front-sticky} property is
@@ -2818,18 +2837,29 @@ names are in the list. For example, if a character has a
then insertion before the character can inherit its @code{face} property
and its @code{read-only} property, but no others.
- The @code{rear-nonsticky} works the opposite way. Every property is
-rear-sticky by default, so the @code{rear-nonsticky} property says which
-properties are @emph{not} rear-sticky. If a character's
+ The @code{rear-nonsticky} works the opposite way. A property is
+normally rear-sticky by default, so the @code{rear-nonsticky} property
+says which properties are @emph{not} rear-sticky. If a character's
@code{rear-nonsticky} property is @code{t}, then none of its properties
are rear-sticky. If the @code{rear-nonsticky} property is a list,
properties are rear-sticky @emph{unless} their names are in the list.
- When you insert text with inheritance, it inherits all the rear-sticky
-properties of the preceding character, and all the front-sticky
-properties of the following character. The previous character's
-properties take precedence when both sides offer different sticky values
-for the same property.
+@defvar text-property-default-nonsticky
+@tindex text-property-default-nonsticky
+This variable holds an alist which defines the default rear-stickiness
+of various text properties. Each element has the form
+@code{(@var{property} . @var{nonstickiness})}, and it defines the
+stickiness of a particular text property, @var{property}.
+
+If @var{nonstickiness} is non-@code{nil}, this means that the property
+@var{property} is rear-nonsticky by default. Since all properties are
+front-nonsticky by default, this makes @var{property} nonsticky in both
+directions by default.
+
+The text properties @code{front-sticky} and @code{rear-nonsticky}, when
+used, take precedence over the default @var{nonstickiness} specifed in
+@code{text-property-default-nonsticky}.
+@end defvar
Here are the functions that insert text with inheritance of properties:
@@ -3034,6 +3064,102 @@ clickable pieces of text. Also, the major mode definition (or the
global definition) remains available for the rest of the text in the
buffer.
+@node Fields
+@subsection Defining and Using Fields
+@cindex fields
+
+ A field is a range of consecutive characters in the buffer that are
+identified by having the same value (comparing with @code{eq}) of the
+@code{field} property. This section describes special functions that
+are available for operating on fields.
+
+ You specify a field with a buffer position, @var{pos}. We think of
+each field as containing a range of buffer positions, so the position
+you specify stands for the field containing that position.
+
+ When the characters before and after @var{pos} are part of the same
+field, there is no doubt which field contains @var{pos}: the one those
+characters both belong to. When @var{pos} is at a boundary between
+fields, which field it belongs to depends on the stickiness of the
+@code{field} properties of the two surrounding characters (@pxref{Sticky
+Properties}). The field whose property would be inherited by text
+inserted at @var{pos} is the field that contains @var{pos}.
+
+ There is an anomalous case where newly inserted text at @var{pos}
+would not inherit the @code{field} property from either side. This
+happens if the previous character's @code{field} property is not
+rear-sticky, and the following character's @code{field} property is not
+front-sticky. In this case, @var{pos} belongs to neither the preceding
+field nor the following field; the field functions treat it as belonging
+to an empty field whose beginning and end are both at @var{pos}.
+
+ In all of these functions, if @var{pos} is omitted or @code{nil}, the
+value of point is used by default.
+
+@defun field-beginning &optional pos escape-from-edge
+@tindex field-beginning
+This function returns the beginning of the field specified by @var{pos}.
+
+If @var{pos} is at the end of a field, and @var{escape-from-edge} is
+non-@code{nil}, then the return value is always the beginning of the
+field that @emph{ends} at @var{pos}, regardless of the stickiness of the
+@code{field} properties around @var{pos}.
+@end defun
+
+@defun field-end &optional pos escape-from-edge
+@tindex field-end
+This function returns the end of the field specified by @var{pos}.
+
+If @var{pos} is at the beginning of a field, and @var{escape-from-edge}
+is non-@code{nil}, then the return value is always the end of the field
+that @emph{begins} at @var{pos}, regardless of the stickiness of the
+@code{field} properties around @var{pos}.
+@end defun
+
+@defun field-string &optional pos
+@tindex field-string
+This function returns the contents of the field specified by @var{pos},
+as a string.
+@end defun
+
+@defun field-string-no-properties &optional pos
+@tindex field-string-no-properties
+This function returns the contents of the field specified by @var{pos},
+as a string, discarding text properties.
+@end defun
+
+@defun delete-field &optional pos
+@tindex delete-field
+This function deletes the text of the field specified by @var{pos}.
+@end defun
+
+@defun constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line
+@tindex constrain-to-field
+This function ``constrains'' @var{new-pos} to the field that
+@var{old-pos} belongs to---in other words, it returns the position
+closest to @var{new-pos} that is in the same field as @var{old-pos}.
+
+If @var{new-pos} is @code{nil}, then @code{constrain-to-field} uses
+the value of point instead, and moves point to the resulting position.
+
+If @var{old-pos} is at the boundary of two fields, then the allowable
+positions for @var{new-pos} depends on the value of the optional
+argument @var{escape-from-edge}. If @var{escape-from-edge} is
+@code{nil}, then @var{new-pos} is constrained to the field that has the
+same @code{field} text-property that new characters inserted at
+@var{old-pos} would get. (This depends on the stickiness of the
+@code{field} property for the characters before and after
+@var{old-pos}.) If @var{escape-from-edge} is non-@code{nil},
+@var{new-pos} is constrained to the union of the two adjacent fields.
+
+If the optional argument @var{only-in-line} is non-@code{nil}, and
+constraining @var{new-pos} in the usual way would move it to a different
+line, @var{new-pos} is returned unconstrained. This used in commands
+that move by line, such as @code{next-line} and
+@code{beginning-of-line}, so that they respect field boundaries only in
+the case where they can still move to the right line.
+@end defun
+
@node Not Intervals
@subsection Why Text Properties are not Intervals
@cindex intervals
@@ -3094,12 +3220,11 @@ This function replaces all occurrences of the character @var{old-char}
with the character @var{new-char} in the region of the current buffer
defined by @var{start} and @var{end}.
-@cindex Outline mode
@cindex undo avoidance
If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does
not record the change for undo and does not mark the buffer as modified.
-This feature is used for controlling selective display (@pxref{Selective
-Display}).
+This was useful for controlling the old selective display feature
+(@pxref{Selective Display}).
@code{subst-char-in-region} does not move point and returns
@code{nil}.
diff --git a/lispref/tips.texi b/lispref/tips.texi
index 03e767f2f28..3b2398953e2 100644
--- a/lispref/tips.texi
+++ b/lispref/tips.texi
@@ -423,19 +423,19 @@ should have a documentation string.
An internal variable or subroutine of a Lisp program might as well have
a documentation string. In earlier Emacs versions, you could save space
by using a comment instead of a documentation string, but that is no
-longer the case.
+longer the case---documentation strings now take up very little space in
+a running Emacs.
@item
The first line of the documentation string should consist of one or two
complete sentences that stand on their own as a summary. @kbd{M-x
-apropos} displays just the first line, and if it doesn't stand on its
-own, the result looks bad. In particular, start the first line with a
-capital letter and end with a period.
+apropos} displays just the first line, and if that line's contents don't
+stand on their own, the result looks bad. In particular, start the
+first line with a capital letter and end with a period.
-The documentation string can have additional lines that expand on the
-details of how to use the function or variable. The additional lines
-should be made up of complete sentences also, but they may be filled if
-that looks good.
+The documentation string is not limited to one line; use as many lines
+as you need to explain the details of how to use the function or
+variable. Please use complete sentences in the additional lines.
@item
For consistency, phrase the verb in the first sentence of a function's
@@ -457,17 +457,27 @@ Instead of, ``Cause Emacs to display text in boldface,'' write just
``Display text in boldface.''
@item
+When a command is meaningful only in a certain mode or situation,
+do mention that in the documentation string. For example,
+the documentation of @code{dired-find-file} is:
+
+@example
+In Dired, visit the file or directory named on this line.
+@end example
+
+@item
Do not start or end a documentation string with whitespace.
@item
Format the documentation string so that it fits in an Emacs window on an
80-column screen. It is a good idea for most lines to be no wider than
-60 characters. The first line can be wider if necessary to fit the
-information that ought to be there.
+60 characters. The first line should not be wider than 67 characters
+or it will look bad in the output of @code{apropos}.
-However, rather than simply filling the entire documentation string, you
-can make it much more readable by choosing line breaks with care.
-Use blank lines between topics if the documentation string is long.
+You can fill the text if that looks good. However, rather than blindly
+filling the entire documentation string, you can often make it much more
+readable by choosing certain line breaks with care. Use blank lines
+between topics if the documentation string is long.
@item
@strong{Do not} indent subsequent lines of a documentation string so
@@ -499,12 +509,16 @@ all non-@code{nil} values are equivalent and indicate explicitly what
When a function's documentation string mentions the value of an argument
of the function, use the argument name in capital letters as if it were
a name for that value. Thus, the documentation string of the function
-@code{/} refers to its second argument as @samp{DIVISOR}, because the
-actual argument name is @code{divisor}.
+@code{eval} refers to its second argument as @samp{FORM}, because the
+actual argument name is @code{form}:
+
+@example
+Evaluate FORM and return its value.
+@end example
-Also use all caps for metasyntactic variables, such as when you show
-the decomposition of a list or vector into subunits, some of which may
-vary. @samp{KEY} and @samp{VALUE} in the following example
+Also write metasyntactic variables in capital letters, such as when you
+show the decomposition of a list or vector into subunits, some of which
+may vary. @samp{KEY} and @samp{VALUE} in the following example
illustrate this practice:
@example
@@ -513,6 +527,18 @@ have the form (KEY . VALUE). Here, KEY is ...
@end example
@item
+If a line in a documentation string begins with an open-parenthesis,
+write a backslash before the open-parenthesis, like this:
+
+@example
+The argument FOO can be either a number
+\(a buffer position) or a string (a file name).
+@end example
+
+This prevents the open-parenthesis from being treated as the start of a
+defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}).
+
+@item
@iftex
When a documentation string refers to a Lisp symbol, write it as it
would be printed (which usually means in lower case), with single-quotes
@@ -634,29 +660,31 @@ at that point. For example:
@end group
@end smallexample
-Every function that has no documentation string (presumably one that is
-used only internally within the package it belongs to), should have
-instead a two-semicolon comment right before the function, explaining
-what the function does and how to call it properly. Explain precisely
-what each argument means and how the function interprets its possible
-values.
-
-@item ;;;
-Comments that start with three semicolons, @samp{;;;}, should start at
-the left margin. Such comments are used outside function definitions to
-make general statements explaining the design principles of the program.
-For example:
+We also normally use two semicolons for comments outside functions.
@smallexample
@group
-;;; This Lisp code is run in Emacs
-;;; when it is to operate as a server
-;;; for other processes.
+;; This Lisp code is run in Emacs
+;; when it is to operate as a server
+;; for other processes.
@end group
@end smallexample
+Every function that has no documentation string (presumably one that is
+used only internally within the package it belongs to), should instead
+have a two-semicolon comment right before the function, explaining what
+the function does and how to call it properly. Explain precisely what
+each argument means and how the function interprets its possible values.
+
+@item ;;;
+Comments that start with three semicolons, @samp{;;;}, should start at
+the left margin. These are used, occasionally, for comments within
+functions that should start at the margin. We also use them sometimes
+for comments that are between functions---whether to use two or three
+semicolons there is a matter of style.
+
Another use for triple-semicolon comments is for commenting out lines
-within a function. We use triple-semicolons for this precisely so that
+within a function. We use three semicolons for this precisely so that
they remain at the left margin.
@smallexample
@@ -799,7 +827,8 @@ appropriate. You can also put in header lines with other header
names---they have no standard meanings, so they can't do any harm.
We use additional stylized comments to subdivide the contents of the
-library file. Here is a table of them:
+library file. These should be separated by blank lines from anything
+else. Here is a table of them:
@table @samp
@item ;;; Commentary:
@@ -815,11 +844,10 @@ but @samp{;;; Commentary:} is preferred.
@item ;;; Change Log:
This begins change log information stored in the library file (if you
-store the change history there). For most of the Lisp
-files distributed with Emacs, the change history is kept in the file
-@file{ChangeLog} and not in the source file at all; these files do
-not have a @samp{;;; Change Log:} line. @samp{History} is an
-alternative to @samp{Change Log}.
+store the change history there). For Lisp files distributed with Emacs,
+the change history is kept in the file @file{ChangeLog} and not in the
+source file at all; these files generally do not have a @samp{;;; Change
+Log:} line. @samp{History} is an alternative to @samp{Change Log}.
@item ;;; Code:
This begins the actual code of the program.
diff --git a/lispref/windows.texi b/lispref/windows.texi
index b8ba56bfff7..d1fcf5d6b96 100644
--- a/lispref/windows.texi
+++ b/lispref/windows.texi
@@ -260,7 +260,7 @@ gets @minus{} @var{size} lines and the upper window gets the rest, but
the upper window is still the one selected.)
@end deffn
-@deffn Command split-window-horizontally size
+@deffn Command split-window-horizontally &optional size
This function splits the selected window into two windows
side-by-side, leaving the selected window with @var{size} columns.
@@ -1320,7 +1320,9 @@ window scrolls up because point is above the window start, the new start
position is chosen to put point @var{f} part of the window height from
the top. The larger @var{f}, the more aggressive the scrolling.
-This variable automatically becomes buffer-local when set in any fashion.
+A value of @code{nil} is equivalent to .5, since its effect is to center
+point. This variable automatically becomes buffer-local when set in any
+fashion.
@end defopt
@defopt scroll-down-aggressively
View Lorry Controller Status