changeset 26696:ef5e7bbe6f19

Current version from /gd/gnu/elisp.

--- a/lispref/anti.texi	Fri Dec 03 19:08:52 1999 +0000
+++ b/lispref/anti.texi	Fri Dec 03 19:11:12 1999 +0000
@@ -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

--- a/lispref/commands.texi	Fri Dec 03 19:08:52 1999 +0000
+++ b/lispref/commands.texi	Fri Dec 03 19:11:12 1999 +0000
@@ -18,6 +18,7 @@
 * 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 @@
 @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 @@
 @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 @@
 @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 @@
 
 @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 @@
 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 @@
 @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 @@
 
 @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 @@
 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 @@
 
 @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 @@
   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.

--- a/lispref/display.texi	Fri Dec 03 19:08:52 1999 +0000
+++ b/lispref/display.texi	Fri Dec 03 19:11:12 1999 +0000
@@ -919,7 +919,7 @@
 
 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 @@
 
 @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 deleted overlay is not permanently useless.  You can give it
-a position in a buffer again by calling @code{move-overlay}.
+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 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 @@
 ``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 @@
 @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 @@
 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 @@
 @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 @@
 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

--- a/lispref/files.texi	Fri Dec 03 19:08:52 1999 +0000
+++ b/lispref/files.texi	Fri Dec 03 19:11:12 1999 +0000
@@ -20,6 +20,12 @@
 @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 @@
 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 @@
 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 @@
 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 @@
 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 @@
 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 @@
   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 @@
 @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 @@
 
 @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 @@
 @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 @@
 @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 @@
 @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 @@
 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 @@
 @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 @@
 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

--- a/lispref/front-cover-1.texi	Fri Dec 03 19:08:52 1999 +0000
+++ b/lispref/front-cover-1.texi	Fri Dec 03 19:11:12 1999 +0000
@@ -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

--- a/lispref/locals.texi	Fri Dec 03 19:08:52 1999 +0000
+++ b/lispref/locals.texi	Fri Dec 03 19:11:12 1999 +0000
@@ -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 @@
 @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 @@
 @item vc-mode
 @xref{Mode Line Variables}.
 @end table
-

--- a/lispref/minibuf.texi	Fri Dec 03 19:08:52 1999 +0000
+++ b/lispref/minibuf.texi	Fri Dec 03 19:11:12 1999 +0000
@@ -45,15 +45,14 @@
   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.)
+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.)
 
-@c ???
   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 @@
 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 @@
 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 @@
 @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 @@
 @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 @@
 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.

--- a/lispref/modes.texi	Fri Dec 03 19:08:52 1999 +0000
+++ b/lispref/modes.texi	Fri Dec 03 19:11:12 1999 +0000
@@ -810,7 +810,7 @@
 @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 @@
 @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 @@
 @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 @@
 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

--- a/lispref/nonascii.texi	Fri Dec 03 19:08:52 1999 +0000
+++ b/lispref/nonascii.texi	Fri Dec 03 19:11:12 1999 +0000
@@ -23,6 +23,7 @@
 * Translation of Characters::
 * Coding Systems::
 * Input Methods::
+* Locales::             Interacting with the POSIX locale.
 @end menu
 
 @node Text Representations
@@ -1219,3 +1220,36 @@
 
   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

--- a/lispref/os.texi	Fri Dec 03 19:08:52 1999 +0000
+++ b/lispref/os.texi	Fri Dec 03 19:11:12 1999 +0000
@@ -1090,6 +1090,13 @@
 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

--- a/lispref/positions.texi	Fri Dec 03 19:08:52 1999 +0000
+++ b/lispref/positions.texi	Fri Dec 03 19:11:12 1999 +0000
@@ -19,6 +19,9 @@
 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 @@
 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).
+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.
 
-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.
+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 the minibuffer, the end of the prompt always acts as a word boundary,
-regardless of what characters appear before and after it.
-
-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 @@
 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 @@
 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

--- a/lispref/syntax.texi	Fri Dec 03 19:08:52 1999 +0000
+++ b/lispref/syntax.texi	Fri Dec 03 19:11:12 1999 +0000
@@ -507,6 +507,18 @@
 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 @@
 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 @@
 
 @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))

--- a/lispref/text.texi	Fri Dec 03 19:08:52 1999 +0000
+++ b/lispref/text.texi	Fri Dec 03 19:11:12 1999 +0000
@@ -220,9 +220,6 @@
 "
 @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 @@
 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 @@
 @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 @@
 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 @@
 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 @@
 
 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 @@
 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 @@
 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 @@
 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 @@
                                   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 @@
 
   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 @@
 @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 @@
 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 @@
 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 @@
 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 @@
 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 @@
 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}.

--- a/lispref/tips.texi	Fri Dec 03 19:08:52 1999 +0000
+++ b/lispref/tips.texi	Fri Dec 03 19:11:12 1999 +0000
@@ -423,19 +423,19 @@
 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 @@
 ``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 @@
 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}:
 
-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
+@example
+Evaluate FORM and return its value.
+@end 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 @@
 @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 @@
 @end group
 @end smallexample
 
+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.
+@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.
+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.  Such comments are used outside function definitions to
-make general statements explaining the design principles of the program.
-For example:
-
-@smallexample
-@group
-;;; This Lisp code is run in Emacs
-;;; when it is to operate as a server
-;;; for other processes.
-@end group
-@end smallexample
+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 @@
 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 @@
 
 @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.

--- a/lispref/windows.texi	Fri Dec 03 19:08:52 1999 +0000
+++ b/lispref/windows.texi	Fri Dec 03 19:11:12 1999 +0000
@@ -260,7 +260,7 @@
 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 @@
 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