From e639e10a63c574609df3f745c4adb538415d9b1b Mon Sep 17 00:00:00 2001 From: Martin Rudalics Date: Mon, 1 Feb 2016 19:01:34 +0100 Subject: [PATCH] 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. --- 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 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; } -- 2.39.2