procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Some corrections in Elisp manual

Browse source 
* 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
non-@code{nil} instead of non-nil.
(Choosing Window Options): The WINDOW arg of
`split-window-sensibly' is optional.
(Choosing Window Options): Write non-@code{nil} 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.
This commit is contained in:
Martin Rudalics 2016-02-01 19:01:34 +01:00
parent d766ca8ff1
commit e639e10a63
11 changed files with 72 additions and 52 deletions
Download patch file Download diff file Expand all files Collapse all files

10
doc/lispref/buffers.texi
View file

@ -755,10 +755,14 @@ When disabling Read Only mode, it disables View mode if View mode was
enabled. enabled.
@end deffn @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 This function signals a @code{buffer-read-only} error if the current
buffer is read-only. @xref{Using Interactive}, for another way to buffer is read-only. If the text at @var{position} (which defaults to
signal an error if the current buffer is read-only. 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 @end defun
@node Buffer List @node Buffer List

4
doc/lispref/debugging.texi
View file

@ -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}. of @code{debug-on-error} is not changed during @code{eval-expression}.
@end defopt @end defopt
@defvar debug-on-signal @defopt debug-on-signal
Normally, errors caught by @code{condition-case} never invoke the Normally, errors caught by @code{condition-case} never invoke the
debugger. The @code{condition-case} gets a chance to handle the error debugger. The @code{condition-case} gets a chance to handle the error
before the debugger gets a chance. 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}, there. If you need to debug code wrapped in @code{condition-case},
consider using @code{condition-case-unless-debug} (@pxref{Handling consider using @code{condition-case-unless-debug} (@pxref{Handling
Errors}). Errors}).
@end defvar @end defopt
@defopt debug-on-event @defopt debug-on-event
If you set @code{debug-on-event} to a special event (@pxref{Special If you set @code{debug-on-event} to a special event (@pxref{Special

21
doc/lispref/display.texi
View file

@ -47,8 +47,9 @@ that Emacs presents to the user.
contents of a given frame (@pxref{Frames}). This is useful if the contents of a given frame (@pxref{Frames}). This is useful if the
screen is corrupted. screen is corrupted.
@defun redraw-frame frame @defun redraw-frame &optional frame
This function clears and redisplays frame @var{frame}. This function clears and redisplays frame @var{frame}. If @var{frame}
is omitted or nil, it redraws the selected frame.
@end defun @end defun
Even more powerful is @code{redraw-display}: 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 return value is always specified, use a value of @code{default} for
@var{inherit}. @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}. 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 @end defun
@defun face-foreground face &optional frame inherit @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}. The image is looked for in @code{image-load-path}.
@end defun @end defun
@defvar image-load-path @defopt image-load-path
This variable's value is a list of locations in which to search for 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 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 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 @example
(defimage foo-image '((:type xpm :file "foo/bar.xpm"))) (defimage foo-image '((:type xpm :file "foo/bar.xpm")))
@end example @end example
@end defvar @end defopt
@defun image-load-path-for-library library image &optional path no-error @defun image-load-path-for-library library image &optional path no-error
This function returns a suitable search path for images used by the 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}). capability (@samp{vb}).
@end defopt @end defopt
@defvar ring-bell-function @defopt ring-bell-function
If this is non-@code{nil}, it specifies how Emacs should ring the 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 bell. Its value should be a function of no arguments. If this is
non-@code{nil}, it takes precedence over the @code{visible-bell} non-@code{nil}, it takes precedence over the @code{visible-bell}
variable. variable.
@end defvar @end defopt
@node Window Systems @node Window Systems
@section Window Systems @section Window Systems

4
doc/lispref/frames.texi
View file

@ -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. order to make a frame appear truly maximized or full-screen.
@end defopt @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 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} terms of the canonical height and width of a character on @var{frame}
(@pxref{Frame Font}). (@pxref{Frame Font}).
@ -2236,7 +2236,7 @@ parameters. @xref{Management Parameters}.
terminal frames. On each text terminal, only the top frame is terminal frames. On each text terminal, only the top frame is
displayed at any one time. 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} This function returns the top frame on @var{terminal}. @var{terminal}
should be a terminal object, a frame (meaning that frame's 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 or @code{nil} (meaning the selected frame's terminal). If it does not

19
doc/lispref/keymaps.texi
View file

@ -950,22 +950,25 @@ are used before @code{minor-mode-map-alist} and
@end defvar @end defvar
@cindex transient keymap @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 This function adds @var{keymap} as a @dfn{transient} keymap, which
takes precedence over other keymaps for one (or more) subsequent keys. takes precedence over other keymaps for one (or more) subsequent keys.
Normally, @var{keymap} is used just once, to look up the very next Normally, @var{keymap} is used just once, to look up the very next key.
key. If the optional argument @var{pred} is @code{t}, the map stays 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 active as long as the user types keys defined in @var{keymap}; when the
the user types a key that is not in @var{keymap}, the transient keymap user types a key that is not in @var{keymap}, the transient keymap is
is deactivated and normal key lookup continues for that key. 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, function is called with no arguments, prior to running each command,
while @var{keymap} is active; it should return non-@code{nil} if while @var{keymap} is active; it should return non-@code{nil} if
@var{keymap} should stay active. @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 variable @code{overriding-terminal-local-map}, which takes precedence
over all other active keymaps (@pxref{Searching Keymaps}). over all other active keymaps (@pxref{Searching Keymaps}).
@end defun @end defun

10
doc/lispref/minibuf.texi
View file

@ -272,7 +272,7 @@ History}). If it is omitted or @code{nil}, the history list defaults
to @code{regexp-history}. to @code{regexp-history}.
@end defun @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 The function @code{read-regexp} may use the value of this variable to
determine its list of default regular expressions. If non-@code{nil}, determine its list of default regular expressions. If non-@code{nil},
the value of this variable should be either: the value of this variable should be either:
@ -288,7 +288,7 @@ or a list of strings.
@noindent @noindent
See @code{read-regexp} above for details of how these values are used. See @code{read-regexp} above for details of how these values are used.
@end defvar @end defopt
@defvar minibuffer-allow-text-properties @defvar minibuffer-allow-text-properties
If this variable is @code{nil}, then @code{read-from-minibuffer} 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}. properties, just the characters themselves. @xref{Text Properties}.
@end defun @end defun
@defun delete-minibuffer-contents @deffn Command delete-minibuffer-contents
This function erases the editable contents of the minibuffer (that is, This command erases the editable contents of the minibuffer (that is,
everything except the prompt), if a minibuffer is current. Otherwise, everything except the prompt), if a minibuffer is current. Otherwise,
it erases the entire current buffer. it erases the entire current buffer.
@end defun @end deffn
@node Recursive Mini @node Recursive Mini
@section Recursive Minibuffers @section Recursive Minibuffers

8
doc/lispref/modes.texi
View file

@ -1943,11 +1943,11 @@ Its default value displays the buffer name, padded with spaces to at
least 12 columns. least 12 columns.
@end defvar @end defvar
@defopt mode-line-position @defvar mode-line-position
This variable indicates the position in the buffer. Its default value This variable indicates the position in the buffer. Its default value
displays the buffer percentage and, optionally, the buffer size, the displays the buffer percentage and, optionally, the buffer size, the
line number and the column number. line number and the column number.
@end defopt @end defvar
@defvar vc-mode @defvar vc-mode
The variable @code{vc-mode}, buffer-local in each buffer, records 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. line, or @code{nil} for no version control.
@end defvar @end defvar
@defopt mode-line-modes @defvar mode-line-modes
This variable displays the buffer's major and minor modes. Its This variable displays the buffer's major and minor modes. Its
default value also displays the recursive editing level, information default value also displays the recursive editing level, information
on the process status, and whether narrowing is in effect. on the process status, and whether narrowing is in effect.
@end defopt @end defvar
@defvar mode-line-remote @defvar mode-line-remote
This variable is used to show whether @code{default-directory} for the This variable is used to show whether @code{default-directory} for the

5
doc/lispref/strings.texi
View file

@ -145,11 +145,12 @@ This returns a string containing the characters @var{characters}.
@end example @end example
@end defun @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 This function returns a new string which consists of those characters
from @var{string} in the range from (and including) the character at the 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 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 @example
@group @group

9
doc/lispref/text.texi
View file

@ -303,7 +303,7 @@ there, the function returns @code{nil}. Otherwise, a nearby symbol or
word on the same line is acceptable. word on the same line is acceptable.
@end defun @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. 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 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{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence},
@code{whitespace}, @code{line}, @code{page}, and others. @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 @example
---------- Buffer: foo ---------- ---------- Buffer: foo ----------
Gentlemen may cry ``Pea@point{}ce! Peace!,'' 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}. @code{delete-blank-lines} returns @code{nil}.
@end deffn @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 Delete trailing whitespace in the region defined by @var{start} and
@var{end}. @var{end}.
@ -1763,7 +1766,7 @@ is value of @code{indent-line-function} in Paragraph-Indent Text mode.
@defopt left-margin @defopt left-margin
This variable specifies the base left margin column. In Fundamental 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. becomes buffer-local when set in any fashion.
@end defopt @end defopt

24
doc/lispref/windows.texi
View file

@ -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} visible and, unless @var{alist} contains an @code{inhibit-switch-frame}
entry (@pxref{Choosing Window Options}), raises that frame if necessary. 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 If @var{alist} has a non-@code{nil} @code{frame-predicate} entry, its
function taking one argument (a frame), returning non-nil if the value is a function taking one argument (a frame), returning
frame is a candidate; this function replaces the default predicate. 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, 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 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). desired buffer) or @code{nil} (which means the splitting failed).
@end defopt @end defopt
@defun split-window-sensibly window @defun split-window-sensibly &optional window
This function tries to split @var{window}, and return the newly This function tries to split @var{window}, and return the newly created
created window. If @var{window} cannot be split, it returns window. If @var{window} cannot be split, it returns @code{nil}. If
@code{nil}. @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 This function obeys the usual rules that determine when a window may
be split (@pxref{Splitting Windows}). It first tries to split by be split (@pxref{Splitting Windows}). It first tries to split by
@ -2671,9 +2673,9 @@ to split this way.
@end defopt @end defopt
@defopt even-window-sizes @defopt even-window-sizes
This variable, if non-nil, causes @code{display-buffer} to even window This variable, if non-@code{nil}, causes @code{display-buffer} to even
sizes whenever it reuses an existing window and that window is adjacent window sizes whenever it reuses an existing window and that window is
to the selected one. adjacent to the selected one.
If its value is @code{width-only}, sizes are evened only if the reused 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 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 @end defun
@vindex window-group-end-function @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} This function is like @code{window-end}, except that when @var{window}
is a part of a group of windows (@pxref{Window Group}), is a part of a group of windows (@pxref{Window Group}),
@code{window-group-end} returns the end position of the entire group. @code{window-group-end} returns the end position of the entire group.

10
src/buffer.c
View file

@ -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. 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 If the text under POSITION (which defaults to point) has the
`inhibit-read-only' text property set, the error will not be raised. */) `inhibit-read-only' text property set, the error will not be raised. */)
(Lisp_Object pos) (Lisp_Object position)
{ {
if (NILP (pos)) if (NILP (position))
XSETFASTINT (pos, PT); XSETFASTINT (position, PT);
else else
CHECK_NUMBER (pos); CHECK_NUMBER (position);
if (!NILP (BVAR (current_buffer, read_only)) if (!NILP (BVAR (current_buffer, read_only))
&& NILP (Vinhibit_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 ()); xsignal1 (Qbuffer_read_only, Fcurrent_buffer ());
return Qnil; return Qnil;
} }