Doc fixes.

lisp/replace.el

@@ -45,9 +45,9 @@
 As each match is found, the user must type a character saying
 what to do with it.  For directions, type \\[help-command] at that time.
 
-Preserves case in each replacement if  case-replace  and  case-fold-search
+Preserves case in each replacement if `case-replace' and `case-fold-search'
 are non-nil and FROM-STRING has no uppercase letters.
-Third arg DELIMITED (prefix arg if interactive) non-nil means replace
+Third arg DELIMITED (prefix arg if interactive), if non-nil, means replace
 only matches surrounded by word boundaries.
 
 To customize possible responses, change the \"bindings\" in `query-replace-map'."
@@ -61,12 +61,13 @@ To customize possible responses, change the \"bindings\" in `query-replace-map'.
 As each match is found, the user must type a character saying
 what to do with it.  For directions, type \\[help-command] at that time.
 
-Preserves case in each replacement if  case-replace  and  case-fold-search
+Preserves case in each replacement if `case-replace' and `case-fold-search'
 are non-nil and REGEXP has no uppercase letters.
-Third arg DELIMITED (prefix arg if interactive) non-nil means replace
+Third arg DELIMITED (prefix arg if interactive), if non-nil, means replace
 only matches surrounded by word boundaries.
-In TO-STRING, \\& means insert what matched REGEXP,
-and \\=\\<n> means insert what matched <n>th \\(...\\) in REGEXP."
+In TO-STRING, `\\&' stands for whatever matched the whole of REGEXP,
+and `\\=\\N' (where N is a digit) stands for
+ whatever what matched the Nth `\\(...\\)' in REGEXP."
   (interactive (query-replace-read-args "Query replace regexp"))
   (perform-replace regexp to-string t t arg)
   (or unread-command-events (message "Done")))
@@ -113,13 +114,13 @@ before rotating to the next."
   "Replace occurrences of FROM-STRING with TO-STRING.
 Preserve case in each match if `case-replace' and `case-fold-search'
 are non-nil and FROM-STRING has no uppercase letters.
-Third arg DELIMITED (prefix arg if interactive) non-nil means replace
+Third arg DELIMITED (prefix arg if interactive), if non-nil, means replace
 only matches surrounded by word boundaries.
 
 This function is usually the wrong thing to use in a Lisp program.
 What you probably want is a loop like this:
-  (while (search-forward OLD-STRING nil t)
-    (replace-match REPLACEMENT nil t))
+  (while (search-forward FROM-STRING nil t)
+    (replace-match TO-STRING nil t))
 which will run faster and will not set the mark or print anything."
   (interactive (query-replace-read-args "Replace string"))
   (perform-replace from-string to-string nil nil delimited)
@@ -127,17 +128,18 @@ which will run faster and will not set the mark or print anything."
 
 (defun replace-regexp (regexp to-string &optional delimited)
   "Replace things after point matching REGEXP with TO-STRING.
-Preserve case in each match if case-replace and case-fold-search
+Preserve case in each match if `case-replace' and `case-fold-search'
 are non-nil and REGEXP has no uppercase letters.
-Third arg DELIMITED (prefix arg if interactive) non-nil means replace
+Third arg DELIMITED (prefix arg if interactive), if non-nil, means replace
 only matches surrounded by word boundaries.
-In TO-STRING, \\& means insert what matched REGEXP,
-and \\=\\<n> means insert what matched <n>th \\(...\\) in REGEXP.
+In TO-STRING, `\\&' stands for whatever matched the whole of REGEXP,
+and `\\=\\N' (where N is a digit) stands for
+ whatever what matched the Nth `\\(...\\)' in REGEXP."
 
 This function is usually the wrong thing to use in a Lisp program.
 What you probably want is a loop like this:
   (while (re-search-forward REGEXP nil t)
-    (replace-match REPLACEMENT nil nil))
+    (replace-match TO-STRING nil nil))
 which will run faster and will not set the mark or print anything."
   (interactive (query-replace-read-args "Replace regexp"))
   (perform-replace regexp to-string nil t delimited)