new repository

1 files changed, 83 insertions, 0 deletions

diff --git a/devdocs/elisp/managing-overlays.html b/devdocs/elisp/managing-overlays.html
new file mode 100644
index 00000000..9673dd4f
--- /dev/null
+++ b/devdocs/elisp/managing-overlays.html
@@ -0,0 +1,83 @@
+ <h4 class="subsection">Managing Overlays</h4>   <p>This section describes the functions to create, delete and move overlays, and to examine their contents. Overlay changes are not recorded in the buffer’s undo list, since the overlays are not part of the buffer’s contents. </p> <dl> <dt id="overlayp">Function: <strong>overlayp</strong> <em>object</em>
+</dt> <dd><p>This function returns <code>t</code> if <var>object</var> is an overlay. </p></dd>
+</dl> <dl> <dt id="make-overlay">Function: <strong>make-overlay</strong> <em>start end &amp;optional buffer front-advance rear-advance</em>
+</dt> <dd>
+<p>This function creates and returns an overlay that belongs to <var>buffer</var> and ranges from <var>start</var> to <var>end</var>. Both <var>start</var> and <var>end</var> must specify buffer positions; they may be integers or markers. If <var>buffer</var> is omitted, the overlay is created in the current buffer. </p>   <p>An overlay whose <var>start</var> and <var>end</var> specify the same buffer position is known as <em>empty</em>. A non-empty overlay can become empty if the text between its <var>start</var> and <var>end</var> is deleted. When that happens, the overlay is by default not deleted, but you can cause it to be deleted by giving it the ‘<samp>evaporate</samp>’ property (see <a href="overlay-properties">evaporate property</a>). </p> <p>The arguments <var>front-advance</var> and <var>rear-advance</var> specify the marker insertion type for the start of the overlay and for the end of the overlay, respectively. See <a href="marker-insertion-types">Marker Insertion Types</a>. If they are both <code>nil</code>, the default, then the overlay extends to include any text inserted at the beginning, but not text inserted at the end. If <var>front-advance</var> is non-<code>nil</code>, text inserted at the beginning of the overlay is excluded from the overlay. If <var>rear-advance</var> is non-<code>nil</code>, text inserted at the end of the overlay is included in the overlay. </p>
+</dd>
+</dl> <dl> <dt id="overlay-start">Function: <strong>overlay-start</strong> <em>overlay</em>
+</dt> <dd><p>This function returns the position at which <var>overlay</var> starts, as an integer. </p></dd>
+</dl> <dl> <dt id="overlay-end">Function: <strong>overlay-end</strong> <em>overlay</em>
+</dt> <dd><p>This function returns the position at which <var>overlay</var> ends, as an integer. </p></dd>
+</dl> <dl> <dt id="overlay-buffer">Function: <strong>overlay-buffer</strong> <em>overlay</em>
+</dt> <dd><p>This function returns the buffer that <var>overlay</var> belongs to. It returns <code>nil</code> if <var>overlay</var> has been deleted. </p></dd>
+</dl> <dl> <dt id="delete-overlay">Function: <strong>delete-overlay</strong> <em>overlay</em>
+</dt> <dd>
+<p>This function deletes <var>overlay</var>. The overlay continues to exist as a Lisp object, and its property list is unchanged, but it ceases to be attached to the buffer it belonged to, and ceases to have any effect on display. </p> <p>A deleted overlay is not permanently disconnected. You can give it a position in a buffer again by calling <code>move-overlay</code>. </p>
+</dd>
+</dl> <dl> <dt id="move-overlay">Function: <strong>move-overlay</strong> <em>overlay start end &amp;optional buffer</em>
+</dt> <dd>
+<p>This function moves <var>overlay</var> to <var>buffer</var>, and places its bounds at <var>start</var> and <var>end</var>. Both arguments <var>start</var> and <var>end</var> must specify buffer positions; they may be integers or markers. </p> <p>If <var>buffer</var> is omitted, <var>overlay</var> stays in the same buffer it was already associated with; if <var>overlay</var> was deleted, it goes into the current buffer. </p> <p>The return value is <var>overlay</var>. </p> <p>This is the only valid way to change the endpoints of an overlay. Do not try modifying the markers in the overlay by hand, as that fails to update other vital data structures and can cause some overlays to be lost. </p>
+</dd>
+</dl> <dl> <dt id="remove-overlays">Function: <strong>remove-overlays</strong> <em>&amp;optional start end name value</em>
+</dt> <dd>
+<p>This function removes all the overlays between <var>start</var> and <var>end</var> whose property <var>name</var> has the value <var>value</var>. It can move the endpoints of the overlays in the region, or split them. </p> <p>If <var>name</var> is omitted or <code>nil</code>, it means to delete all overlays in the specified region. If <var>start</var> and/or <var>end</var> are omitted or <code>nil</code>, that means the beginning and end of the buffer respectively. Therefore, <code>(remove-overlays)</code> removes all the overlays in the current buffer. </p>
+</dd>
+</dl> <dl> <dt id="copy-overlay">Function: <strong>copy-overlay</strong> <em>overlay</em>
+</dt> <dd><p>This function returns a copy of <var>overlay</var>. The copy has the same endpoints and properties as <var>overlay</var>. However, the marker insertion type for the start of the overlay and for the end of the overlay are set to their default values (see <a href="marker-insertion-types">Marker Insertion Types</a>). </p></dd>
+</dl> <p>Here are some examples: </p> <div class="example"> <pre class="example">;; <span class="roman">Create an overlay.</span>
+(setq foo (make-overlay 1 10))
+     ⇒ #&lt;overlay from 1 to 10 in display.texi&gt;
+(overlay-start foo)
+     ⇒ 1
+(overlay-end foo)
+     ⇒ 10
+(overlay-buffer foo)
+     ⇒ #&lt;buffer display.texi&gt;
+;; <span class="roman">Give it a property we can check later.</span>
+(overlay-put foo 'happy t)
+     ⇒ t
+;; <span class="roman">Verify the property is present.</span>
+(overlay-get foo 'happy)
+     ⇒ t
+;; <span class="roman">Move the overlay.</span>
+(move-overlay foo 5 20)
+     ⇒ #&lt;overlay from 5 to 20 in display.texi&gt;
+(overlay-start foo)
+     ⇒ 5
+(overlay-end foo)
+     ⇒ 20
+;; <span class="roman">Delete the overlay.</span>
+(delete-overlay foo)
+     ⇒ nil
+;; <span class="roman">Verify it is deleted.</span>
+foo
+     ⇒ #&lt;overlay in no buffer&gt;
+;; <span class="roman">A deleted overlay has no position.</span>
+(overlay-start foo)
+     ⇒ nil
+(overlay-end foo)
+     ⇒ nil
+(overlay-buffer foo)
+     ⇒ nil
+;; <span class="roman">Undelete the overlay.</span>
+(move-overlay foo 1 20)
+     ⇒ #&lt;overlay from 1 to 20 in display.texi&gt;
+;; <span class="roman">Verify the results.</span>
+(overlay-start foo)
+     ⇒ 1
+(overlay-end foo)
+     ⇒ 20
+(overlay-buffer foo)
+     ⇒ #&lt;buffer display.texi&gt;
+;; <span class="roman">Moving and deleting the overlay does not change its properties.</span>
+(overlay-get foo 'happy)
+     ⇒ t
+</pre>
+</div> <p>Emacs stores the overlays of each buffer in two lists, divided around an arbitrary center position. One list extends backwards through the buffer from that center position, and the other extends forwards from that center position. The center position can be anywhere in the buffer. </p> <dl> <dt id="overlay-recenter">Function: <strong>overlay-recenter</strong> <em>pos</em>
+</dt> <dd><p>This function recenters the overlays of the current buffer around position <var>pos</var>. That makes overlay lookup faster for positions near <var>pos</var>, but slower for positions far away from <var>pos</var>. </p></dd>
+</dl> <p>A loop that scans the buffer forwards, creating overlays, can run faster if you do <code>(overlay-recenter (point-max))</code> first. </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/Managing-Overlays.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Managing-Overlays.html</a>
+  </p>
+</div>