new repository

1 files changed, 10 insertions, 0 deletions

diff --git a/devdocs/elisp/swapping-text.html b/devdocs/elisp/swapping-text.html
new file mode 100644
index 00000000..891ac89f
--- /dev/null
+++ b/devdocs/elisp/swapping-text.html
@@ -0,0 +1,10 @@
+ <h3 class="section">Swapping Text Between Two Buffers</h3>   <p>Specialized modes sometimes need to let the user access from the same buffer several vastly different types of text. For example, you may need to display a summary of the buffer text, in addition to letting the user access the text itself. </p> <p>This could be implemented with multiple buffers (kept in sync when the user edits the text), or with narrowing (see <a href="narrowing">Narrowing</a>). But these alternatives might sometimes become tedious or prohibitively expensive, especially if each type of text requires expensive buffer-global operations in order to provide correct display and editing commands. </p> <p>Emacs provides another facility for such modes: you can quickly swap buffer text between two buffers with <code>buffer-swap-text</code>. This function is very fast because it doesn’t move any text, it only changes the internal data structures of the buffer object to point to a different chunk of text. Using it, you can pretend that a group of two or more buffers are actually a single virtual buffer that holds the contents of all the individual buffers together. </p> <dl> <dt id="buffer-swap-text">Function: <strong>buffer-swap-text</strong> <em>buffer</em>
+</dt> <dd>
+<p>This function swaps the text of the current buffer and that of its argument <var>buffer</var>. It signals an error if one of the two buffers is an indirect buffer (see <a href="indirect-buffers">Indirect Buffers</a>) or is a base buffer of an indirect buffer. </p> <p>All the buffer properties that are related to the buffer text are swapped as well: the positions of point and mark, all the markers, the overlays, the text properties, the undo list, the value of the <code>enable-multibyte-characters</code> flag (see <a href="text-representations">enable-multibyte-characters</a>), etc. </p> <p><strong>Warning:</strong> If this function is called from within a <code>save-excursion</code> form, the current buffer will be set to <var>buffer</var> upon leaving the form, since the marker used by <code>save-excursion</code> to save the position and buffer will be swapped as well. </p>
+</dd>
+</dl> <p>If you use <code>buffer-swap-text</code> on a file-visiting buffer, you should set up a hook to save the buffer’s original text rather than what it was swapped with. <code>write-region-annotate-functions</code> works for this purpose. You should probably set <code>buffer-saved-size</code> to -2 in the buffer, so that changes in the text it is swapped with will not interfere with auto-saving. </p><div class="_attribution">
+  <p class="_attribution-p">
+    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
+    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Swapping-Text.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Swapping-Text.html</a>
+  </p>
+</div>