]> git.eshelyaron.com Git - emacs.git/commitdiff
Some corrections in Elisp manual
authorMartin Rudalics <rudalics@gmx.at>
Mon, 1 Feb 2016 18:01:34 +0000 (19:01 +0100)
committerMartin Rudalics <rudalics@gmx.at>
Mon, 1 Feb 2016 18:01:34 +0000 (19:01 +0100)
* 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
doc/lispref/debugging.texi
doc/lispref/display.texi
doc/lispref/frames.texi
doc/lispref/keymaps.texi
doc/lispref/minibuf.texi
doc/lispref/modes.texi
doc/lispref/strings.texi
doc/lispref/text.texi
doc/lispref/windows.texi
src/buffer.c

index e56d77c7b92ac0980b2b426f815f6098703a1ad5..1f7f263fb21183304b82a9cdf1518d1f2bac045d 100644 (file)
@@ -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
index 3f1574fac6c0da2a33fd7672f53e9a7cfea46b14..98c47052cb0a8445babb9a4f6fabbb8971d523c0 100644 (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}.
 @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
index aa98ed40ee587da552f2897612987b138a4c6534..323895927a9933c18521f5a3e62833eb6620f704 100644 (file)
@@ -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
index b98e3a5cdd1290cd5c54d16c7529626529000401..15a9bd911ffc3533f1f1f1b23b61937e4e8119d4 100644 (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.
 @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
index 354be3cdd927c785588c8c846f60365ee6f6f9ac..0ea30283d7d1c51d342f523c894f3e882c8fda62 100644 (file)
@@ -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
index e24d2cd643a3cdcaabd521279d6a8d1ece1c5bbd..6f41090ebea2ab7442c14d3270aa5f5578392312 100644 (file)
@@ -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
index 2b621e4337bcff6eaefbf3e6aba5b4de34e62ae8..66f7a352023bf1b6ef9b5b8fa99a02675f602e3e 100644 (file)
@@ -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
index 091db5e4ebb53471867bf3209abc15d8e73ab2b1..9d6613c522cfde999ffb8cb983398d87b2d82dcf 100644 (file)
@@ -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
index 41991c9482cb46298d96e2271cb6dee6648ab1a4..4c3a1a01e7d1ff9a212070998ee0e5e4399d4e69 100644 (file)
@@ -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
 
index 771bd4eeb2978d6b0dabeb39569118071b77c7d4..f61f08a7f240cbc54fcec865109f38a9ab9d8c45 100644 (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}
 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.
index 74b6fb6a47f6915f6102e62ab7f17c4df9ded39d..653e3fe05f868947ce723fb254cbd81275e440df 100644 (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.
 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;
 }