* 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.
-@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
-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
@end defun
@node Buffer List
of @code{debug-on-error} is not changed during @code{eval-expression}.
@end defopt
of @code{debug-on-error} is not changed during @code{eval-expression}.
@end defopt
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.
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.
there. If you need to debug code wrapped in @code{condition-case},
consider using @code{condition-case-unless-debug} (@pxref{Handling
Errors}).
there. If you need to debug code wrapped in @code{condition-case},
consider using @code{condition-case-unless-debug} (@pxref{Handling
Errors}).
@defopt debug-on-event
If you set @code{debug-on-event} to a special event (@pxref{Special
@defopt debug-on-event
If you set @code{debug-on-event} to a special event (@pxref{Special
contents of a given frame (@pxref{Frames}). This is useful if the
screen is corrupted.
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}:
@end defun
Even more powerful is @code{redraw-display}:
return value is always specified, use a value of @code{default} for
@var{inherit}.
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}.
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
@end defun
@defun face-foreground face &optional frame inherit
The image is looked for in @code{image-load-path}.
@end defun
The image is looked for in @code{image-load-path}.
@end defun
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
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
@example
(defimage foo-image '((:type xpm :file "foo/bar.xpm")))
@end example
@example
(defimage foo-image '((:type xpm :file "foo/bar.xpm")))
@end example
@defun image-load-path-for-library library image &optional path no-error
This function returns a suitable search path for images used by the
@defun image-load-path-for-library library image &optional path no-error
This function returns a suitable search path for images used by the
capability (@samp{vb}).
@end defopt
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.
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.
@node Window Systems
@section Window Systems
@node Window Systems
@section Window Systems
order to make a frame appear truly maximized or full-screen.
@end defopt
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}).
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}).
terminal frames. On each text terminal, only the top frame is
displayed at any one time.
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
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
@end defvar
@cindex transient keymap
@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.
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.
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
variable @code{overriding-terminal-local-map}, which takes precedence
over all other active keymaps (@pxref{Searching Keymaps}).
@end defun
to @code{regexp-history}.
@end defun
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:
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:
@noindent
See @code{read-regexp} above for details of how these values are used.
@noindent
See @code{read-regexp} above for details of how these values are used.
@defvar minibuffer-allow-text-properties
If this variable is @code{nil}, then @code{read-from-minibuffer}
@defvar minibuffer-allow-text-properties
If this variable is @code{nil}, then @code{read-from-minibuffer}
properties, just the characters themselves. @xref{Text Properties}.
@end defun
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.
everything except the prompt), if a minibuffer is current. Otherwise,
it erases the entire current buffer.
@node Recursive Mini
@section Recursive Minibuffers
@node Recursive Mini
@section Recursive Minibuffers
least 12 columns.
@end defvar
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.
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.
@defvar vc-mode
The variable @code{vc-mode}, buffer-local in each buffer, records
@defvar vc-mode
The variable @code{vc-mode}, buffer-local in each buffer, records
line, or @code{nil} for no version control.
@end defvar
line, or @code{nil} for no version control.
@end defvar
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.
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.
@defvar mode-line-remote
This variable is used to show whether @code{default-directory} for the
@defvar mode-line-remote
This variable is used to show whether @code{default-directory} for the
-@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
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}.
word on the same line is acceptable.
@end defun
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
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
@code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence},
@code{whitespace}, @code{line}, @code{page}, and others.
@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!,''
@example
---------- Buffer: foo ----------
Gentlemen may cry ``Pea@point{}ce! Peace!,''
@code{delete-blank-lines} returns @code{nil}.
@end deffn
@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}.
Delete trailing whitespace in the region defined by @var{start} and
@var{end}.
@defopt left-margin
This variable specifies the base left margin column. In Fundamental
@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
becomes buffer-local when set in any fashion.
@end defopt
visible and, unless @var{alist} contains an @code{inhibit-switch-frame}
entry (@pxref{Choosing Window Options}), raises that frame if necessary.
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
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
desired buffer) or @code{nil} (which means the splitting failed).
@end defopt
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
This function obeys the usual rules that determine when a window may
be split (@pxref{Splitting Windows}). It first tries to split by
@end defopt
@defopt even-window-sizes
@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
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
@end defun
@vindex window-group-end-function
@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.
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.
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. */)
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. */)
- if (NILP (pos))
- XSETFASTINT (pos, PT);
+ if (NILP (position))
+ XSETFASTINT (position, PT);
+ CHECK_NUMBER (position);
if (!NILP (BVAR (current_buffer, read_only))
&& NILP (Vinhibit_read_only)
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;
}
xsignal1 (Qbuffer_read_only, Fcurrent_buffer ());
return Qnil;
}