From d93301242f38d3d9aaa55899c07496f0bdecf391 Mon Sep 17 00:00:00 2001 From: Philipp Stephani Date: Sun, 24 Sep 2017 19:32:16 +0200 Subject: [PATCH] Document 'replace-buffer-contents' in the manual. * doc/lispref/text.texi (Replacing): New node. --- doc/lispref/text.texi | 24 ++++++++++++++++++++++++ etc/NEWS | 1 - 2 files changed, 24 insertions(+), 1 deletion(-) 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