Document 'replace-buffer-contents' in the manual.

* doc/lispref/text.texi (Replacing): New node.

2 files changed, 24 insertions, 1 deletions

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index a7d10797cd0..baa3c708e90 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -54,6 +54,8 @@ the character after point.
 * Registers::        How registers are implemented.  Accessing the text or
                        position stored in a register.
 * Transposition::    Swapping two portions of a buffer.
+* Replacing::        Replacing the text of one buffer with the text
+                       of another buffer.
 * Decompression::    Dealing with compressed data.
 * Base 64::          Conversion to or from base 64 encoding.
 * Checksum/Hash::    Computing cryptographic hashes.
@@ -4328,6 +4330,28 @@ is non-@code{nil}, @code{transpose-regions} does not do this---it leaves
 all markers unrelocated.
 @end defun
 
+@node Replacing
+@section Replacing Buffer Text
+
+  You can use the following function to replace the text of one buffer
+with the text of another buffer:
+
+@deffn Command replace-buffer-contents source
+This function replaces the accessible portion of the current buffer
+with the accessible portion of the buffer @var{source}.  @var{source}
+may either be a buffer object or the name of a buffer.  When
+@code{replace-buffer-contents} succeeds, the text of the accessible
+portion of the current buffer will be equal to the text of the
+accessible portion of the @var{source} buffer.  This function attempts
+to keep point, markers, text properties, and overlays in the current
+buffer intact.  One potential case where this behavior is useful is
+external code formatting programs: they typically write the
+reformatted text into a temporary buffer or file, and using
+@code{delete-region} and @code{insert-buffer-substring} would destroy
+these properties.  However, the latter combination is typically
+faster.  @xref{Deletion}, and @ref{Insertion}.
+@end deffn
+
 @node Decompression
 @section Dealing With Compressed Data
 
diff --git a/etc/NEWS b/etc/NEWS
index 34561acae56..fc4531f0e85 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -578,7 +578,6 @@ Negative prefix arg flips the direction of selection.  Also,
 defun are selected unless they are separated from the defun by a blank
 line.
 
----
 ** New command 'replace-buffer-contents'.
 This command replaces the contents of the accessible portion of the
 current buffer with the contents of the accessible portion of a