11 files changed, 72 insertions, 52 deletions
diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index e56d77c7b92..1f7f263fb21 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -755,10 +755,14 @@ When disabling Read Only mode, it disables View mode if View mode was
 enabled.
 @end deffn
 
-@defun barf-if-buffer-read-only
+@defun barf-if-buffer-read-only &optional position
 This function signals a @code{buffer-read-only} error if the current
-buffer is read-only.  @xref{Using Interactive}, for another way to
-signal an error if the current buffer is read-only.
+buffer is read-only.  If the text at @var{position} (which defaults to
+point) has the @code{inhibit-read-only} text property set, the error
+will not be raised.
+
+@xref{Using Interactive}, for another way to signal an error if the
+current buffer is read-only.
 @end defun
 
 @node Buffer List
diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi
index 3f1574fac6c..98c47052cb0 100644
--- a/doc/lispref/debugging.texi
+++ b/doc/lispref/debugging.texi
@@ -141,7 +141,7 @@ If @code{eval-expression-debug-on-error} is @code{nil}, then the value
 of @code{debug-on-error} is not changed during @code{eval-expression}.
 @end defopt
 
-@defvar debug-on-signal
+@defopt debug-on-signal
 Normally, errors caught by @code{condition-case} never invoke the
 debugger.  The @code{condition-case} gets a chance to handle the error
 before the debugger gets a chance.
@@ -158,7 +158,7 @@ course of affairs, and you may not even realize that errors happen
 there.  If you need to debug code wrapped in @code{condition-case},
 consider using @code{condition-case-unless-debug} (@pxref{Handling
 Errors}).
-@end defvar
+@end defopt
 
 @defopt debug-on-event
 If you set @code{debug-on-event} to a special event (@pxref{Special
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index aa98ed40ee5..323895927a9 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -47,8 +47,9 @@ that Emacs presents to the user.
 contents of a given frame (@pxref{Frames}).  This is useful if the
 screen is corrupted.
 
-@defun redraw-frame frame
-This function clears and redisplays frame @var{frame}.
+@defun redraw-frame &optional frame
+This function clears and redisplays frame @var{frame}.  If @var{frame}
+is omitted or nil, it redraws the selected frame.
 @end defun
 
   Even more powerful is @code{redraw-display}:
@@ -2686,8 +2687,14 @@ considered, until a specified attribute is found.  To ensure that the
 return value is always specified, use a value of @code{default} for
 @var{inherit}.
 
-@defun face-font face &optional frame
+@defun face-font face &optional frame character
 This function returns the name of the font of face @var{face}.
+
+If the optional argument @var{frame} is specified, it returns the name
+of the font of @var{face} for that frame.  If @var{frame} is omitted or
+@code{nil}, the selected frame is used.  And, in this case, if the
+optional third argument @var{character} is supplied, it returns the font
+name used for @var{character}.
 @end defun
 
 @defun face-foreground face &optional frame inherit
@@ -5324,7 +5331,7 @@ returned.  If no specification is satisfied, @code{nil} is returned.
 The image is looked for in @code{image-load-path}.
 @end defun
 
-@defvar image-load-path
+@defopt image-load-path
 This variable's value is a list of locations in which to search for
 image files.  If an element is a string or a variable symbol whose
 value is a string, the string is taken to be the name of a directory
@@ -5343,7 +5350,7 @@ should specify the image as follows:
 @example
 (defimage foo-image '((:type xpm :file "foo/bar.xpm")))
 @end example
-@end defvar
+@end defopt
 
 @defun image-load-path-for-library library image &optional path no-error
 This function returns a suitable search path for images used by the
@@ -6899,12 +6906,12 @@ provided the terminal's Termcap entry defines the visible bell
 capability (@samp{vb}).
 @end defopt
 
-@defvar ring-bell-function
+@defopt ring-bell-function
 If this is non-@code{nil}, it specifies how Emacs should ring the
 bell.  Its value should be a function of no arguments.  If this is
 non-@code{nil}, it takes precedence over the @code{visible-bell}
 variable.
-@end defvar
+@end defopt
 
 @node Window Systems
 @section Window Systems
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index b98e3a5cdd1..15a9bd911ff 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -847,7 +847,7 @@ With some window managers you may have to set this to non-@code{nil} in
 order to make a frame appear truly maximized or full-screen.
 @end defopt
 
-@defun set-frame-size frame width height pixelwise
+@defun set-frame-size frame width height &optional pixelwise
 This function sets the size of the text area of @var{frame}, measured in
 terms of the canonical height and width of a character on @var{frame}
 (@pxref{Frame Font}).
@@ -2236,7 +2236,7 @@ parameters.  @xref{Management Parameters}.
 terminal frames.  On each text terminal, only the top frame is
 displayed at any one time.
 
-@defun tty-top-frame terminal
+@defun tty-top-frame &optional terminal
 This function returns the top frame on @var{terminal}.  @var{terminal}
 should be a terminal object, a frame (meaning that frame's terminal),
 or @code{nil} (meaning the selected frame's terminal).  If it does not
diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi
index 354be3cdd92..0ea30283d7d 100644
--- a/doc/lispref/keymaps.texi
+++ b/doc/lispref/keymaps.texi
@@ -950,22 +950,25 @@ are used before @code{minor-mode-map-alist} and
 @end defvar
 
 @cindex transient keymap
-@defun set-transient-map keymap &optional keep
+@defun set-transient-map keymap &optional keep-pred on-exit
 This function adds @var{keymap} as a @dfn{transient} keymap, which
 takes precedence over other keymaps for one (or more) subsequent keys.
 
-Normally, @var{keymap} is used just once, to look up the very next
-key.  If the optional argument @var{pred} is @code{t}, the map stays
-active as long as the user types keys defined in @var{keymap}; when
-the user types a key that is not in @var{keymap}, the transient keymap
-is deactivated and normal key lookup continues for that key.
+Normally, @var{keymap} is used just once, to look up the very next key.
+If the optional argument @var{keep-pred} is @code{t}, the map stays
+active as long as the user types keys defined in @var{keymap}; when the
+user types a key that is not in @var{keymap}, the transient keymap is
+deactivated and normal key lookup continues for that key.
 
-The @var{pred} argument can also be a function.  In that case, the
+The @var{keep-pred} argument can also be a function.  In that case, the
 function is called with no arguments, prior to running each command,
 while @var{keymap} is active; it should return non-@code{nil} if
 @var{keymap} should stay active.
 
-This function works by adding and removing @code{keymap} from the
+The optional argument @var{on-exit}, if non-nil, specifies a function
+that is called, with no arguments, after @var{keymap} is deactivated.
+
+This function works by adding and removing @var{keymap} from the
 variable @code{overriding-terminal-local-map}, which takes precedence
 over all other active keymaps (@pxref{Searching Keymaps}).
 @end defun
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index e24d2cd643a..6f41090ebea 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -272,7 +272,7 @@ History}).  If it is omitted or @code{nil}, the history list defaults
 to @code{regexp-history}.
 @end defun
 
-@defvar read-regexp-defaults-function
+@defopt read-regexp-defaults-function
 The function @code{read-regexp} may use the value of this variable to
 determine its list of default regular expressions.  If non-@code{nil},
 the value of this variable should be either:
@@ -288,7 +288,7 @@ or a list of strings.
 
 @noindent
 See @code{read-regexp} above for details of how these values are used.
-@end defvar
+@end defopt
 
 @defvar minibuffer-allow-text-properties
 If this variable is @code{nil}, then @code{read-from-minibuffer}
@@ -2336,11 +2336,11 @@ This is like @code{minibuffer-contents}, except that it does not copy text
 properties, just the characters themselves.  @xref{Text Properties}.
 @end defun
 
-@defun delete-minibuffer-contents
-This function erases the editable contents of the minibuffer (that is,
+@deffn Command delete-minibuffer-contents
+This command erases the editable contents of the minibuffer (that is,
 everything except the prompt), if a minibuffer is current.  Otherwise,
 it erases the entire current buffer.
-@end defun
+@end deffn
 
 @node Recursive Mini
 @section Recursive Minibuffers
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 2b621e4337b..66f7a352023 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -1943,11 +1943,11 @@ Its default value displays the buffer name, padded with spaces to at
 least 12 columns.
 @end defvar
 
-@defopt mode-line-position
+@defvar mode-line-position
 This variable indicates the position in the buffer.  Its default value
 displays the buffer percentage and, optionally, the buffer size, the
 line number and the column number.
-@end defopt
+@end defvar
 
 @defvar vc-mode
 The variable @code{vc-mode}, buffer-local in each buffer, records
@@ -1956,11 +1956,11 @@ and, if so, which kind.  Its value is a string that appears in the mode
 line, or @code{nil} for no version control.
 @end defvar
 
-@defopt mode-line-modes
+@defvar mode-line-modes
 This variable displays the buffer's major and minor modes.  Its
 default value also displays the recursive editing level, information
 on the process status, and whether narrowing is in effect.
-@end defopt
+@end defvar
 
 @defvar mode-line-remote
 This variable is used to show whether @code{default-directory} for the
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 091db5e4ebb..9d6613c522c 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -145,11 +145,12 @@ This returns a string containing the characters @var{characters}.
 @end example
 @end defun
 
-@defun substring string start &optional end
+@defun substring string &optional start end
 This function returns a new string which consists of those characters
 from @var{string} in the range from (and including) the character at the
 index @var{start} up to (but excluding) the character at the index
-@var{end}.  The first character is at index zero.
+@var{end}.  The first character is at index zero.  With one argument,
+this function just copies @var{string}.
 
 @example
 @group
diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 41991c9482c..4c3a1a01e7d 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -303,7 +303,7 @@ there, the function returns @code{nil}.  Otherwise, a nearby symbol or
 word on the same line is acceptable.
 @end defun
 
-@defun thing-at-point thing
+@defun thing-at-point thing &optional no-properties
 Return the @var{thing} around or next to point, as a string.
 
 The argument @var{thing} is a symbol which specifies a kind of syntactic
@@ -311,6 +311,9 @@ entity.  Possibilities include @code{symbol}, @code{list}, @code{sexp},
 @code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence},
 @code{whitespace}, @code{line}, @code{page}, and others.
 
+When the optional argument @var{no-properties} is non-@code{nil}, this
+function strips text properties from the return value.
+
 @example
 ---------- Buffer: foo ----------
 Gentlemen may cry ``Pea@point{}ce! Peace!,''
@@ -804,7 +807,7 @@ A blank line is defined as a line containing only tabs and spaces.
 @code{delete-blank-lines} returns @code{nil}.
 @end deffn
 
-@deffn Command delete-trailing-whitespace start end
+@deffn Command delete-trailing-whitespace &optional start end
 Delete trailing whitespace in the region defined by @var{start} and
 @var{end}.
 
@@ -1763,7 +1766,7 @@ is value of @code{indent-line-function} in Paragraph-Indent Text mode.
 
 @defopt left-margin
 This variable specifies the base left margin column.  In Fundamental
-mode, @kbd{RET} indents to this column.  This variable automatically
+mode, @key{RET} indents to this column.  This variable automatically
 becomes buffer-local when set in any fashion.
 @end defopt
 
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 771bd4eeb29..f61f08a7f24 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -2415,9 +2415,10 @@ If this function chooses a window on another frame, it makes that frame
 visible and, unless @var{alist} contains an @code{inhibit-switch-frame}
 entry (@pxref{Choosing Window Options}), raises that frame if necessary.
 
-If @var{alist} has a non-nil @code{frame-predicate} entry, its value is a
-function taking one argument (a frame), returning non-nil if the
-frame is a candidate; this function replaces the default predicate.
+If @var{alist} has a non-@code{nil} @code{frame-predicate} entry, its
+value is a function taking one argument (a frame), returning
+non-@code{nil} if the frame is a candidate; this function replaces the
+default predicate.
 
 If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry,
 the selected window is used; thus if the selected frame has a single
@@ -2637,10 +2638,11 @@ and return either a new window (which will be used to display the
 desired buffer) or @code{nil} (which means the splitting failed).
 @end defopt
 
-@defun split-window-sensibly window
-This function tries to split @var{window}, and return the newly
-created window.  If @var{window} cannot be split, it returns
-@code{nil}.
+@defun split-window-sensibly &optional window
+This function tries to split @var{window}, and return the newly created
+window.  If @var{window} cannot be split, it returns @code{nil}.  If
+@var{window} is omitted or @code{nil}, it defaults to the selected
+window.
 
 This function obeys the usual rules that determine when a window may
 be split (@pxref{Splitting Windows}).  It first tries to split by
@@ -2671,9 +2673,9 @@ to split this way.
 @end defopt
 
 @defopt even-window-sizes
-This variable, if non-nil, causes @code{display-buffer} to even window
-sizes whenever it reuses an existing window and that window is adjacent
-to the selected one.
+This variable, if non-@code{nil}, causes @code{display-buffer} to even
+window sizes whenever it reuses an existing window and that window is
+adjacent to the selected one.
 
 If its value is @code{width-only}, sizes are evened only if the reused
 window is on the left or right of the selected one and the selected
@@ -3161,7 +3163,7 @@ text will end if scrolling is not required.
 @end defun
 
 @vindex window-group-end-function
-@defun window-group-end window update
+@defun window-group-end &optional window update
 This function is like @code{window-end}, except that when @var{window}
 is a part of a group of windows (@pxref{Window Group}),
 @code{window-group-end} returns the end position of the entire group.
diff --git a/src/buffer.c b/src/buffer.c
index 74b6fb6a47f..653e3fe05f8 100644
--- a/src/buffer.c
+++ b/src/buffer.c
@@ -2145,16 +2145,16 @@ DEFUN ("barf-if-buffer-read-only", Fbarf_if_buffer_read_only,
        doc: /* Signal a `buffer-read-only' error if the current buffer is read-only.
 If the text under POSITION (which defaults to point) has the
 `inhibit-read-only' text property set, the error will not be raised.  */)
-  (Lisp_Object pos)
+  (Lisp_Object position)
 {
-  if (NILP (pos))
-    XSETFASTINT (pos, PT);
+  if (NILP (position))
+    XSETFASTINT (position, PT);
   else
-    CHECK_NUMBER (pos);
+    CHECK_NUMBER (position);
 
   if (!NILP (BVAR (current_buffer, read_only))
       && NILP (Vinhibit_read_only)
-      && NILP (Fget_text_property (pos, Qinhibit_read_only, Qnil)))
+      && NILP (Fget_text_property (position, Qinhibit_read_only, Qnil)))
     xsignal1 (Qbuffer_read_only, Fcurrent_buffer ());
   return Qnil;
 }