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

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  <cyd@gnu.org>
+
+        * searching.texi (Replacing Match): Minor clarification.
+
 2012-09-22  Eli Zaretskii  <eliz@gnu.org>
 
         * 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  <cyd@gnu.org>
+
+        * 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  <eliz@gnu.org>
 
         * 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,5 +1,16 @@
 2012-09-22  Chong Yidong  <cyd@gnu.org>
 
+        * 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  <cyd@gnu.org>
+
         * dispextern.h (struct image_type): Add new slot, storing a type
         initialization function.
 
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,