From c88b867fecbd50140b0b41f05599811a8f0e3dfe Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Sat, 22 Sep 2012 23:24:26 +0800 Subject: [PATCH] Misc doc fixes. * searching.texi (Replacing Match): Minor clarification. * lisp/repeat.el (repeat): Doc fix. * lisp/simple.el (shell-command-on-region): Doc fix. * lisp/emacs-lisp/easy-mmode.el (define-minor-mode): Doc fix. * cmds.c (Fforward_char, Fbackward_char): Doc fix. * editfns.c (Fline_beginning_position): Doc fix. (Fline_end_position): Doc fix. * minibuf.c (Finternal_complete_buffer): Doc fix. * search.c (Freplace_match): Doc fix. Fixes: debbugs:12325 debbugs:12391 debbugs:12416 debbugs:12414 debbugs:10909 debbugs:12348 --- doc/lispref/ChangeLog | 4 +++ doc/lispref/searching.texi | 26 +++++++++--------- lisp/ChangeLog | 9 +++++++ lisp/emacs-lisp/easy-mmode.el | 17 +++++++----- lisp/repeat.el | 6 ++--- lisp/simple.el | 50 +++++++++++++++++------------------ src/ChangeLog | 11 ++++++++ src/cmds.c | 2 ++ src/editfns.c | 18 +++++++------ src/minibuf.c | 8 +++--- src/search.c | 29 +++++++++----------- 11 files changed, 103 insertions(+), 77 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index db545f8ec91..b813ac6bb1c 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,7 @@ +2012-09-22 Chong Yidong + + * searching.texi (Replacing Match): Minor clarification. + 2012-09-22 Eli Zaretskii * edebug.texi (Instrumenting): Improve indexing. diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi index edd1d30e28d..56c96363e81 100644 --- a/doc/lispref/searching.texi +++ b/doc/lispref/searching.texi @@ -1278,20 +1278,18 @@ search. It works by means of the match data. @cindex case in replacements @defun replace-match replacement &optional fixedcase literal string subexp -This function replaces the text in the buffer (or in @var{string}) that -was matched by the last search. It replaces that text with -@var{replacement}. - -If you did the last search in a buffer, you should specify @code{nil} -for @var{string} and make sure that the current buffer when you call -@code{replace-match} is the one in which you did the searching or -matching. Then @code{replace-match} does the replacement by editing -the buffer; it leaves point at the end of the replacement text, and -returns @code{t}. - -If you did the search in a string, pass the same string as @var{string}. -Then @code{replace-match} does the replacement by constructing and -returning a new string. +This function performs a replacement operation on a buffer or string. + +If you did the last search in a buffer, you should omit the +@var{string} argument or specify @code{nil} for it, and make sure that +the current buffer is the one in which you performed the last search. +Then this function edits the buffer, replacing the matched text with +@var{replacement}. It leaves point at the end of the replacement +text, and returns @code{t}. + +If you performed the last search on a string, pass the same string as +@var{string}. Then this function returns a new string, in which the +matched text is replaced by @var{replacement}. If @var{fixedcase} is non-@code{nil}, then @code{replace-match} uses the replacement text without case conversion; otherwise, it converts diff --git a/lisp/ChangeLog b/lisp/ChangeLog index b0e91b675a3..813abd506d4 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,12 @@ +2012-09-22 Chong Yidong + + * repeat.el (repeat): Doc fix (Bug#12348). + + * emacs-lisp/easy-mmode.el (define-minor-mode): Doc fix + (Bug#10909). + + * simple.el (shell-command-on-region): Doc fix. + 2012-09-22 Eli Zaretskii * emacs-lisp/timer.el (run-with-idle-timer) diff --git a/lisp/emacs-lisp/easy-mmode.el b/lisp/emacs-lisp/easy-mmode.el index ee4e36a9eba..4951368aebe 100644 --- a/lisp/emacs-lisp/easy-mmode.el +++ b/lisp/emacs-lisp/easy-mmode.el @@ -90,12 +90,17 @@ MODE (you can override this with the :variable keyword, see below). DOC is the documentation for the mode toggle command. The defined mode command takes one optional (prefix) argument. -Interactively with no prefix argument it toggles the mode. -With a prefix argument, it enables the mode if the argument is -positive and otherwise disables it. When called from Lisp, it -enables the mode if the argument is omitted or nil, and toggles -the mode if the argument is `toggle'. If DOC is nil this -function adds a basic doc-string stating these facts. +Interactively with no prefix argument, it toggles the mode. +A prefix argument enables the mode if the argument is positive, +and disables it otherwise. + +When called from Lisp, the mode command toggles the mode if the +argument is `toggle', disables the mode if the argument is a +non-positive integer, and enables the mode otherwise (including +if the argument is omitted or nil or a positive integer). + +If DOC is nil, give the mode command a basic doc-string +documenting what its argument does. Optional INIT-VALUE is the initial value of the mode's variable. Optional LIGHTER is displayed in the mode line when the mode is on. diff --git a/lisp/repeat.el b/lisp/repeat.el index e577c461bc5..e38442a434b 100644 --- a/lisp/repeat.el +++ b/lisp/repeat.el @@ -193,9 +193,9 @@ this function is always whether the value of `this-command' would've been ;;;###autoload (defun repeat (repeat-arg) "Repeat most recently executed command. -With prefix arg, apply new prefix arg to that command; otherwise, -use the prefix arg that was used before (if any). -This command is like the `.' command in the vi editor. +If REPEAT-ARG is non-nil (interactively, with a prefix argument), +supply a prefix argument to that command. Otherwise, give the +command the same prefix argument it was given before, if any. If this command is invoked by a multi-character key sequence, it can then be repeated by repeating the final character of that diff --git a/lisp/simple.el b/lisp/simple.el index 3e11e6838c7..8ddbac33d00 100644 --- a/lisp/simple.el +++ b/lisp/simple.el @@ -2604,8 +2604,6 @@ is encoded using coding-system specified by `process-coding-system-alist', falling back to `default-process-coding-system' if no match for COMMAND is found in `process-coding-system-alist'. -The noninteractive arguments are START, END, COMMAND, -OUTPUT-BUFFER, REPLACE, ERROR-BUFFER, and DISPLAY-ERROR-BUFFER. Noninteractive callers can specify coding systems by binding `coding-system-for-read' and `coding-system-for-write'. @@ -2613,34 +2611,34 @@ If the command generates output, the output may be displayed in the echo area or in a buffer. If the output is short enough to display in the echo area \(determined by the variable `max-mini-window-height' if -`resize-mini-windows' is non-nil), it is shown there. Otherwise -it is displayed in the buffer `*Shell Command Output*'. The output -is available in that buffer in both cases. +`resize-mini-windows' is non-nil), it is shown there. +Otherwise it is displayed in the buffer `*Shell Command Output*'. +The output is available in that buffer in both cases. If there is output and an error, a message about the error -appears at the end of the output. - -If there is no output, or if output is inserted in the current buffer, -then `*Shell Command Output*' is deleted. - -If the optional fourth argument OUTPUT-BUFFER is non-nil, -that says to put the output in some other buffer. -If OUTPUT-BUFFER is a buffer or buffer name, put the output there. -If OUTPUT-BUFFER is not a buffer and not nil, -insert output in the current buffer. -In either case, the output is inserted after point (leaving mark after it). - -If REPLACE, the optional fifth argument, is non-nil, that means insert -the output in place of text from START to END, putting point and mark +appears at the end of the output. If there is no output, or if +output is inserted in the current buffer, the buffer `*Shell +Command Output*' is deleted. + +Optional fourth arg OUTPUT-BUFFER specifies where to put the +command's output. If the value is a buffer or buffer name, put +the output there. Any other value, including nil, means to +insert the output in the current buffer. In either case, the +output is inserted after point (leaving mark after it). + +Optional fifth arg REPLACE, if non-nil, means to insert the +output in place of text from START to END, putting point and mark around it. -If optional sixth argument ERROR-BUFFER is non-nil, it is a buffer -or buffer name to which to direct the command's standard error output. -If it is nil, error output is mingled with regular output. -If DISPLAY-ERROR-BUFFER is non-nil, display the error buffer if there -were any errors. (This is always t, interactively.) -In an interactive call, the variable `shell-command-default-error-buffer' -specifies the value of ERROR-BUFFER." +Optional sixth arg ERROR-BUFFER, if non-nil, specifies a buffer +or buffer name to which to direct the command's standard error +output. If nil, error output is mingled with regular output. +When called interactively, `shell-command-default-error-buffer' +is used for ERROR-BUFFER. + +Optional seventh arg DISPLAY-ERROR-BUFFER, if non-nil, means to +display the error buffer if there were any errors. When called +interactively, this is t." (interactive (let (string) (unless (mark) (error "The mark is not set now, so there is no region")) diff --git a/src/ChangeLog b/src/ChangeLog index b2f33494b7c..9d8bc3a7c00 100644 --- a/src/ChangeLog +++ b/src/ChangeLog @@ -1,3 +1,14 @@ +2012-09-22 Chong Yidong + + * search.c (Freplace_match): Doc fix (Bug#12325). + + * minibuf.c (Finternal_complete_buffer): Doc fix (Bug#12391). + + * editfns.c (Fline_beginning_position): Doc fix (Bug#12416). + (Fline_end_position): Doc fix. + + * cmds.c (Fforward_char, Fbackward_char): Doc fix (Bug#12414). + 2012-09-22 Chong Yidong * dispextern.h (struct image_type): Add new slot, storing a type diff --git a/src/cmds.c b/src/cmds.c index 45f7df948ae..453a4b67e57 100644 --- a/src/cmds.c +++ b/src/cmds.c @@ -85,6 +85,7 @@ move_point (Lisp_Object n, bool forward) DEFUN ("forward-char", Fforward_char, Sforward_char, 0, 1, "^p", doc: /* Move point N characters forward (backward if N is negative). On reaching end or beginning of buffer, stop and signal error. +Interactively, N is the numeric prefix argument. Depending on the bidirectional context, the movement may be to the right or to the left on the screen. This is in contrast with @@ -97,6 +98,7 @@ right or to the left on the screen. This is in contrast with DEFUN ("backward-char", Fbackward_char, Sbackward_char, 0, 1, "^p", doc: /* Move point N characters backward (forward if N is negative). On attempt to pass beginning or end of buffer, stop and signal error. +Interactively, N is the numeric prefix argument. Depending on the bidirectional context, the movement may be to the right or to the left on the screen. This is in contrast with diff --git a/src/editfns.c b/src/editfns.c index c6744648bc5..acf9c48e7a0 100644 --- a/src/editfns.c +++ b/src/editfns.c @@ -738,17 +738,18 @@ Field boundaries are not noticed if `inhibit-field-text-motion' is non-nil. */) DEFUN ("line-beginning-position", Fline_beginning_position, Sline_beginning_position, 0, 1, 0, doc: /* Return the character position of the first character on the current line. -With argument N not nil or 1, move forward N - 1 lines first. -If scan reaches end of buffer, return that position. +With optional argument N, scan forward N - 1 lines first. +If the scan reaches the end of the buffer, return that position. -The returned position is of the first character in the logical order, -i.e. the one that has the smallest character position. +This function ignores text display directionality; it returns the +position of the first character in logical order, i.e. the smallest +character position on the line. This function constrains the returned position to the current field -unless that would be on a different line than the original, +unless that position would be on a different line than the original, unconstrained result. If N is nil or 1, and a front-sticky field starts at point, the scan stops as soon as it starts. To ignore field -boundaries bind `inhibit-field-text-motion' to t. +boundaries, bind `inhibit-field-text-motion' to t. This function does not move point. */) (Lisp_Object n) @@ -782,8 +783,9 @@ DEFUN ("line-end-position", Fline_end_position, Sline_end_position, 0, 1, 0, With argument N not nil or 1, move forward N - 1 lines first. If scan reaches end of buffer, return that position. -The returned position is of the last character in the logical order, -i.e. the character whose buffer position is the largest one. +This function ignores text display directionality; it returns the +position of the last character in logical order, i.e. the largest +character position on the line. This function constrains the returned position to the current field unless that would be on a different line than the original, diff --git a/src/minibuf.c b/src/minibuf.c index 8a1e0ddde86..6f9c61dcfb1 100644 --- a/src/minibuf.c +++ b/src/minibuf.c @@ -1862,11 +1862,11 @@ static Lisp_Object Qmetadata; DEFUN ("internal-complete-buffer", Finternal_complete_buffer, Sinternal_complete_buffer, 3, 3, 0, doc: /* Perform completion on buffer names. -If the argument FLAG is nil, invoke `try-completion', if it's t, invoke -`all-completions', otherwise invoke `test-completion'. +STRING and PREDICATE have the same meanings as in `try-completion', +`all-completions', and `test-completion'. -The arguments STRING and PREDICATE are as in `try-completion', -`all-completions', and `test-completion'. */) +If FLAG is nil, invoke `try-completion'; if it is t, invoke +`all-completions'; otherwise invoke `test-completion'. */) (Lisp_Object string, Lisp_Object predicate, Lisp_Object flag) { if (NILP (flag)) diff --git a/src/search.c b/src/search.c index 1735ade5d8a..5224556fa17 100644 --- a/src/search.c +++ b/src/search.c @@ -2220,15 +2220,14 @@ DEFUN ("replace-match", Freplace_match, Sreplace_match, 1, 5, 0, doc: /* Replace text matched by last search with NEWTEXT. Leave point at the end of the replacement text. -If second arg FIXEDCASE is non-nil, do not alter case of replacement text. -Otherwise maybe capitalize the whole text, or maybe just word initials, -based on the replaced text. -If the replaced text has only capital letters -and has at least one multiletter word, convert NEWTEXT to all caps. -Otherwise if all words are capitalized in the replaced text, -capitalize each word in NEWTEXT. - -If third arg LITERAL is non-nil, insert NEWTEXT literally. +If optional second arg FIXEDCASE is non-nil, do not alter the case of +the replacement text. Otherwise, maybe capitalize the whole text, or +maybe just word initials, based on the replaced text. If the replaced +text has only capital letters and has at least one multiletter word, +convert NEWTEXT to all caps. Otherwise if all words are capitalized +in the replaced text, capitalize each word in NEWTEXT. + +If optional third arg LITERAL is non-nil, insert NEWTEXT literally. Otherwise treat `\\' as special: `\\&' in NEWTEXT means substitute original matched text. `\\N' means substitute what matched the Nth `\\(...\\)'. @@ -2239,13 +2238,11 @@ Otherwise treat `\\' as special: Any other character following `\\' signals an error. Case conversion does not apply to these substitutions. -FIXEDCASE and LITERAL are optional arguments. - -The optional fourth argument STRING can be a string to modify. -This is meaningful when the previous match was done against STRING, -using `string-match'. When used this way, `replace-match' -creates and returns a new string made by copying STRING and replacing -the part of STRING that was matched. +If optional fourth argument STRING is non-nil, it should be a string +to act on; this should be the string on which the previous match was +done via `string-match'. In this case, `replace-match' creates and +returns a new string, made by copying STRING and replacing the part of +STRING that was matched (the original STRING itself is not altered). The optional fifth argument SUBEXP specifies a subexpression; it says to replace just that subexpression with NEWTEXT, -- 2.39.2