new repository

1 files changed, 33 insertions, 0 deletions

diff --git a/devdocs/elisp/invisible-text.html b/devdocs/elisp/invisible-text.html
new file mode 100644
index 00000000..8fd3e08e
--- /dev/null
+++ b/devdocs/elisp/invisible-text.html
@@ -0,0 +1,33 @@
+ <h3 class="section">Invisible Text</h3>  <p>You can make characters <em>invisible</em>, so that they do not appear on the screen, with the <code>invisible</code> property. This can be either a text property (see <a href="text-properties">Text Properties</a>) or an overlay property (see <a href="overlays">Overlays</a>). Cursor motion also partly ignores these characters; if the command loop finds that point is inside a range of invisible text after a command, it relocates point to the other side of the text. </p> <p>In the simplest case, any non-<code>nil</code> <code>invisible</code> property makes a character invisible. This is the default case—if you don’t alter the default value of <code>buffer-invisibility-spec</code>, this is how the <code>invisible</code> property works. You should normally use <code>t</code> as the value of the <code>invisible</code> property if you don’t plan to set <code>buffer-invisibility-spec</code> yourself. </p> <p>More generally, you can use the variable <code>buffer-invisibility-spec</code> to control which values of the <code>invisible</code> property make text invisible. This permits you to classify the text into different subsets in advance, by giving them different <code>invisible</code> values, and subsequently make various subsets visible or invisible by changing the value of <code>buffer-invisibility-spec</code>. </p> <p>Controlling visibility with <code>buffer-invisibility-spec</code> is especially useful in a program to display the list of entries in a database. It permits the implementation of convenient filtering commands to view just a part of the entries in the database. Setting this variable is very fast, much faster than scanning all the text in the buffer looking for properties to change. </p> <dl> <dt id="buffer-invisibility-spec">Variable: <strong>buffer-invisibility-spec</strong>
+</dt> <dd>
+<p>This variable specifies which kinds of <code>invisible</code> properties actually make a character invisible. Setting this variable makes it buffer-local. </p> <dl compact> <dt><code>t</code></dt> <dd>
+<p>A character is invisible if its <code>invisible</code> property is non-<code>nil</code>. This is the default. </p> </dd> <dt>a list</dt> <dd>
+<p>Each element of the list specifies a criterion for invisibility; if a character’s <code>invisible</code> property fits any one of these criteria, the character is invisible. The list can have two kinds of elements: </p> <dl compact> <dt><code><var>atom</var></code></dt> <dd>
+<p>A character is invisible if its <code>invisible</code> property value is <var>atom</var> or if it is a list with <var>atom</var> as a member; comparison is done with <code>eq</code>. </p> </dd> <dt><code>(<var>atom</var> . t)</code></dt> <dd><p>A character is invisible if its <code>invisible</code> property value is <var>atom</var> or if it is a list with <var>atom</var> as a member; comparison is done with <code>eq</code>. Moreover, a sequence of such characters displays as an ellipsis. </p></dd> </dl> </dd> </dl> </dd>
+</dl> <p>Two functions are specifically provided for adding elements to <code>buffer-invisibility-spec</code> and removing elements from it. </p> <dl> <dt id="add-to-invisibility-spec">Function: <strong>add-to-invisibility-spec</strong> <em>element</em>
+</dt> <dd><p>This function adds the element <var>element</var> to <code>buffer-invisibility-spec</code>. If <code>buffer-invisibility-spec</code> was <code>t</code>, it changes to a list, <code>(t)</code>, so that text whose <code>invisible</code> property is <code>t</code> remains invisible. </p></dd>
+</dl> <dl> <dt id="remove-from-invisibility-spec">Function: <strong>remove-from-invisibility-spec</strong> <em>element</em>
+</dt> <dd><p>This removes the element <var>element</var> from <code>buffer-invisibility-spec</code>. This does nothing if <var>element</var> is not in the list. </p></dd>
+</dl> <p>A convention for use of <code>buffer-invisibility-spec</code> is that a major mode should use the mode’s own name as an element of <code>buffer-invisibility-spec</code> and as the value of the <code>invisible</code> property: </p> <div class="example"> <pre class="example">;; <span class="roman">If you want to display an ellipsis:</span>
+(add-to-invisibility-spec '(my-symbol . t))
+;; <span class="roman">If you don’t want ellipsis:</span>
+(add-to-invisibility-spec 'my-symbol)
+
+(overlay-put (make-overlay beginning end)
+             'invisible 'my-symbol)
+
+;; <span class="roman">When done with the invisibility:</span>
+(remove-from-invisibility-spec '(my-symbol . t))
+;; <span class="roman">Or respectively:</span>
+(remove-from-invisibility-spec 'my-symbol)
+</pre>
+</div> <p>You can check for invisibility using the following function: </p> <dl> <dt id="invisible-p">Function: <strong>invisible-p</strong> <em>pos-or-prop</em>
+</dt> <dd>
+<p>If <var>pos-or-prop</var> is a marker or number, this function returns a non-<code>nil</code> value if the text at that position is currently invisible. </p> <p>If <var>pos-or-prop</var> is any other kind of Lisp object, that is taken to mean a possible value of the <code>invisible</code> text or overlay property. In that case, this function returns a non-<code>nil</code> value if that value would cause text to become invisible, based on the current value of <code>buffer-invisibility-spec</code>. </p> <p>The return value of this function is <code>t</code> if the text would be completely hidden on display, or a non-<code>nil</code>, non-<code>t</code> value if the text would be replaced by an ellipsis. </p>
+</dd>
+</dl>  <p>Ordinarily, functions that operate on text or move point do not care whether the text is invisible, they process invisible characters and visible characters alike. The user-level line motion commands, such as <code>next-line</code>, <code>previous-line</code>, ignore invisible newlines if <code>line-move-ignore-invisible</code> is non-<code>nil</code> (the default), i.e., behave like these invisible newlines didn’t exist in the buffer, but only because they are explicitly programmed to do so. </p> <p>If a command ends with point inside or at the boundary of invisible text, the main editing loop relocates point to one of the two ends of the invisible text. Emacs chooses the direction of relocation so that it is the same as the overall movement direction of the command; if in doubt, it prefers a position where an inserted char would not inherit the <code>invisible</code> property. Additionally, if the text is not replaced by an ellipsis and the command only moved within the invisible text, then point is moved one extra character so as to try and reflect the command’s movement by a visible movement of the cursor. </p> <p>Thus, if the command moved point back to an invisible range (with the usual stickiness), Emacs moves point back to the beginning of that range. If the command moved point forward into an invisible range, Emacs moves point forward to the first visible character that follows the invisible text and then forward one more character. </p> <p>These <em>adjustments</em> of point that ended up in the middle of invisible text can be disabled by setting <code>disable-point-adjustment</code> to a non-<code>nil</code> value. See <a href="adjusting-point">Adjusting Point</a>. </p> <p>Incremental search can make invisible overlays visible temporarily and/or permanently when a match includes invisible text. To enable this, the overlay should have a non-<code>nil</code> <code>isearch-open-invisible</code> property. The property value should be a function to be called with the overlay as an argument. This function should make the overlay visible permanently; it is used when the match overlaps the overlay on exit from the search. </p> <p>During the search, such overlays are made temporarily visible by temporarily modifying their invisible and intangible properties. If you want this to be done differently for a certain overlay, give it an <code>isearch-open-invisible-temporary</code> property which is a function. The function is called with two arguments: the first is the overlay, and the second is <code>nil</code> to make the overlay visible, or <code>t</code> to make it invisible again. </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/Invisible-Text.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Invisible-Text.html</a>
+  </p>
+</div>