[Emacs-diffs] emacs-25 e639e10: Some corrections in Elisp manual

[Martin Rudalics]

branch: emacs-25
commit e639e10a63c574609df3f745c4adb538415d9b1b
Author: Martin Rudalics <address@hidden>
Commit: Martin Rudalics <address@hidden>

    Some corrections in Elisp manual
    
    * doc/lispref/buffers.texi (Read Only Buffers): Describe optional
    argument POSITION.
    * doc/lispref/debugging.texi (Error Debugging): `debug-on-signal'
    is an option.
    * doc/lispref/display.texi (Refresh Screen): Describe optional
    argument FRAME of `redraw-frame'.
    (Attribute Functions): Describe optional argument CHARACTER of
    `face-font'.
    (Defining Images): `image-load-path' is an option.
    (Beeping): `ring-bell-function' is an option.
    * doc/lispref/frames.texi (Size and Position): The PIXELWISE
    argument of `set-frame-size' is optional.
    (Raising and Lowering): The TERMINAL argument of `tty-top-frame'
    is optional.
    * doc/lispref/keymaps.texi (Controlling Active Maps): Fix doc of
    `set-transient-map'.
    * doc/lispref/minibuf.texi (Text from Minibuffer):
    `read-regexp-defaults-function' is an option.
    (Minibuffer Contents): `delete-minibuffer-contents' is a command.
    * doc/lispref/modes.texi (Mode Line Variables):
    `mode-line-position' and `mode-line-modes' are variables, not
    options.
    * doc/lispref/strings.texi (Creating Strings): The START argument
    of `substring' is optional.
    * doc/lispref/text.texi (Buffer Contents): Describe optional
    argument NO-PROPERTIES of `thing-at-point'.
    (User-Level Deletion): Both arguments of
    `delete-trailing-whitespace' are optional.
    (Margins): Use @key{RET} instead of @kbd{RET}.
    * doc/lispref/windows.texi (Display Action Functions): Write
    address@hidden instead of non-nil.
    (Choosing Window Options): The WINDOW arg of
    `split-window-sensibly' is optional.
    (Choosing Window Options): Write address@hidden instead of
    non-nil.
    (Window Start and End): Both args of `window-group-end' are
    optional.
    
    * src/buffer.c (Fbarf_if_buffer_read_only): Rename argument POS
    to POSITION to keep consisteny with doc-string.
---
 doc/lispref/buffers.texi   |   10 +++++++---
 doc/lispref/debugging.texi |    4 ++--
 doc/lispref/display.texi   |   21 ++++++++++++++-------
 doc/lispref/frames.texi    |    4 ++--
 doc/lispref/keymaps.texi   |   19 +++++++++++--------
 doc/lispref/minibuf.texi   |   10 +++++-----
 doc/lispref/modes.texi     |    8 ++++----
 doc/lispref/strings.texi   |    5 +++--
 doc/lispref/text.texi      |    9 ++++++---
 doc/lispref/windows.texi   |   24 +++++++++++++-----------
 src/buffer.c               |   10 +++++-----
 11 files changed, 72 insertions(+), 52 deletions(-)

diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index e56d77c7..1f7f263 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
 
address@hidden barf-if-buffer-read-only
address@hidden 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.
+
address@hidden 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 3f1574f..98c4705 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
 
address@hidden debug-on-signal
address@hidden 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}).
address@hidden defvar
address@hidden 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 aa98ed4..3238959 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.
 
address@hidden redraw-frame frame
-This function clears and redisplays frame @var{frame}.
address@hidden 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}.
 
address@hidden face-font face &optional frame
address@hidden 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
address@hidden, 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
 
address@hidden image-load-path
address@hidden 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
address@hidden defvar
address@hidden 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
 
address@hidden ring-bell-function
address@hidden ring-bell-function
 If this is address@hidden, it specifies how Emacs should ring the
 bell.  Its value should be a function of no arguments.  If this is
 address@hidden, it takes precedence over the @code{visible-bell}
 variable.
address@hidden defvar
address@hidden defopt
 
 @node Window Systems
 @section Window Systems
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index b98e3a5..15a9bd9 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 
address@hidden in
 order to make a frame appear truly maximized or full-screen.
 @end defopt
 
address@hidden set-frame-size frame width height pixelwise
address@hidden 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.
 
address@hidden tty-top-frame terminal
address@hidden 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 354be3c..0ea3028 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
address@hidden set-transient-map keymap &optional keep
address@hidden 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 address@hidden 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 e24d2cd..6f41090 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
 
address@hidden read-regexp-defaults-function
address@hidden 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 address@hidden,
 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.
address@hidden defvar
address@hidden 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
 
address@hidden delete-minibuffer-contents
-This function erases the editable contents of the minibuffer (that is,
address@hidden 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.
address@hidden defun
address@hidden deffn
 
 @node Recursive Mini
 @section Recursive Minibuffers
diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 2b621e4..66f7a35 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
 
address@hidden mode-line-position
address@hidden 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.
address@hidden defopt
address@hidden 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
 
address@hidden mode-line-modes
address@hidden 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.
address@hidden defopt
address@hidden 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 091db5e..9d6613c 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
 
address@hidden substring string start &optional end
address@hidden 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
address@hidden  The first character is at index zero.
address@hidden  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 41991c9..4c3a1a0 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
 
address@hidden thing-at-point thing
address@hidden 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 address@hidden, this
+function strips text properties from the return value.
+
 @example
 ---------- Buffer: foo ----------
 Gentlemen may cry address@hidden 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
 
address@hidden Command delete-trailing-whitespace start end
address@hidden 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 771bd4e..f61f08a 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 address@hidden @code{frame-predicate} entry, its
+value is a function taking one argument (a frame), returning
address@hidden if the frame is a candidate; this function replaces the
+default predicate.
 
 If @var{alist} has a address@hidden @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
 
address@hidden 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
address@hidden
address@hidden 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
address@hidden 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 address@hidden, 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
address@hidden window-group-end window update
address@hidden 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 74b6fb6..653e3fe 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;
 }