[Emacs-diffs] /srv/bzr/emacs/trunk r110141: Misc doc fixes.

[Chong Yidong]

------------------------------------------------------------
revno: 110141
fixes bugs: http://debbugs.gnu.org/12325 http://debbugs.gnu.org/12391 
http://debbugs.gnu.org/12416 http://debbugs.gnu.org/12414 
http://debbugs.gnu.org/10909 http://debbugs.gnu.org/12348
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sat 2012-09-22 23:24:26 +0800
message:
  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.
modified:
  doc/lispref/ChangeLog
  doc/lispref/searching.texi
  lisp/ChangeLog
  lisp/emacs-lisp/easy-mmode.el
  lisp/repeat.el
  lisp/simple.el
  src/ChangeLog
  src/cmds.c
  src/editfns.c
  src/minibuf.c
  src/search.c

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-09-22 13:24:58 +0000
+++ b/doc/lispref/ChangeLog     2012-09-22 15:24:26 +0000
@@ -1,3 +1,7 @@
+2012-09-22  Chong Yidong  <address@hidden>
+
+       * searching.texi (Replacing Match): Minor clarification.
+
 2012-09-22  Eli Zaretskii  <address@hidden>
 
        * edebug.texi (Instrumenting): Improve indexing.

=== modified file 'doc/lispref/searching.texi'
--- a/doc/lispref/searching.texi        2012-09-09 06:43:47 +0000
+++ b/doc/lispref/searching.texi        2012-09-22 15:24:26 +0000
@@ -1278,20 +1278,18 @@
 
 @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
address@hidden
-
-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
address@hidden 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
address@hidden 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
address@hidden  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
address@hidden  Then this function returns a new string, in which the
+matched text is replaced by @var{replacement}.
 
 If @var{fixedcase} is address@hidden, then @code{replace-match} uses
 the replacement text without case conversion; otherwise, it converts

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2012-09-22 13:16:03 +0000
+++ b/lisp/ChangeLog    2012-09-22 15:24:26 +0000
@@ -1,3 +1,12 @@
+2012-09-22  Chong Yidong  <address@hidden>
+
+       * 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  <address@hidden>
 
        * emacs-lisp/timer.el (run-with-idle-timer)

=== modified file 'lisp/emacs-lisp/easy-mmode.el'
--- a/lisp/emacs-lisp/easy-mmode.el     2012-06-27 14:05:24 +0000
+++ b/lisp/emacs-lisp/easy-mmode.el     2012-09-22 15:24:26 +0000
@@ -90,12 +90,17 @@
 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.

=== modified file 'lisp/repeat.el'
--- a/lisp/repeat.el    2012-05-05 02:50:20 +0000
+++ b/lisp/repeat.el    2012-09-22 15:24:26 +0000
@@ -193,9 +193,9 @@
 ;;;###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

=== modified file 'lisp/simple.el'
--- a/lisp/simple.el    2012-09-22 03:07:39 +0000
+++ b/lisp/simple.el    2012-09-22 15:24:26 +0000
@@ -2604,8 +2604,6 @@
 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 @@
 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"))

=== modified file 'src/ChangeLog'
--- a/src/ChangeLog     2012-09-22 14:10:24 +0000
+++ b/src/ChangeLog     2012-09-22 15:24:26 +0000
@@ -1,5 +1,16 @@
 2012-09-22  Chong Yidong  <address@hidden>
 
+       * 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  <address@hidden>
+
        * dispextern.h (struct image_type): Add new slot, storing a type
        initialization function.
 

=== modified file 'src/cmds.c'
--- a/src/cmds.c        2012-09-15 07:06:56 +0000
+++ b/src/cmds.c        2012-09-22 15:24:26 +0000
@@ -85,6 +85,7 @@
 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 @@
 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

=== modified file 'src/editfns.c'
--- a/src/editfns.c     2012-09-15 07:06:56 +0000
+++ b/src/editfns.c     2012-09-22 15:24:26 +0000
@@ -738,17 +738,18 @@
 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 @@
 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,

=== modified file 'src/minibuf.c'
--- a/src/minibuf.c     2012-09-15 07:06:56 +0000
+++ b/src/minibuf.c     2012-09-22 15:24:26 +0000
@@ -1862,11 +1862,11 @@
 
 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))

=== modified file 'src/search.c'
--- a/src/search.c      2012-09-17 20:11:34 +0000
+++ b/src/search.c      2012-09-22 15:24:26 +0000
@@ -2220,15 +2220,14 @@
        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 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 third arg LITERAL is non-nil, insert NEWTEXT literally.
+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 @@
   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,