Commit e639e10a authored by Martin Rudalics's avatar Martin Rudalics

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
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.
parent d766ca8f
......@@ -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
......
......@@ -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
......
......@@ -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
......
......@@ -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
......
......@@ -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
......
......@@ -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
......
......@@ -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
......
......@@ -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
......
......@@ -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
......
......@@ -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.
......
......@@ -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;
}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment