new repository

1 files changed, 45 insertions, 0 deletions

diff --git a/devdocs/elisp/narrowing.html b/devdocs/elisp/narrowing.html
new file mode 100644
index 00000000..e8b9a3cf
--- /dev/null
+++ b/devdocs/elisp/narrowing.html
@@ -0,0 +1,45 @@
+ <h3 class="section">Narrowing</h3>    <p><em>Narrowing</em> means limiting the text addressable by Emacs editing commands to a limited range of characters in a buffer. The text that remains addressable is called the <em>accessible portion</em> of the buffer. </p> <p>Narrowing is specified with two buffer positions, which become the beginning and end of the accessible portion. For most editing commands and primitives, these positions replace the values of the beginning and end of the buffer. While narrowing is in effect, no text outside the accessible portion is displayed, and point cannot move outside the accessible portion. Note that narrowing does not alter actual buffer positions (see <a href="point">Point</a>); it only determines which positions are considered the accessible portion of the buffer. Most functions refuse to operate on text that is outside the accessible portion. </p> <p>Commands for saving buffers are unaffected by narrowing; they save the entire buffer regardless of any narrowing. </p> <p>If you need to display in a single buffer several very different types of text, consider using an alternative facility described in <a href="swapping-text">Swapping Text</a>. </p> <dl> <dt id="narrow-to-region">Command: <strong>narrow-to-region</strong> <em>start end</em>
+</dt> <dd>
+<p>This function sets the accessible portion of the current buffer to start at <var>start</var> and end at <var>end</var>. Both arguments should be character positions. </p> <p>In an interactive call, <var>start</var> and <var>end</var> are set to the bounds of the current region (point and the mark, with the smallest first). </p>
+</dd>
+</dl> <dl> <dt id="narrow-to-page">Command: <strong>narrow-to-page</strong> <em>&amp;optional move-count</em>
+</dt> <dd>
+<p>This function sets the accessible portion of the current buffer to include just the current page. An optional first argument <var>move-count</var> non-<code>nil</code> means to move forward or backward by <var>move-count</var> pages and then narrow to one page. The variable <code>page-delimiter</code> specifies where pages start and end (see <a href="standard-regexps">Standard Regexps</a>). </p> <p>In an interactive call, <var>move-count</var> is set to the numeric prefix argument. </p>
+</dd>
+</dl> <dl> <dt id="widen">Command: <strong>widen</strong>
+</dt> <dd>
+ <p>This function cancels any narrowing in the current buffer, so that the entire contents are accessible. This is called <em>widening</em>. It is equivalent to the following expression: </p> <div class="example"> <pre class="example">(narrow-to-region 1 (1+ (buffer-size)))
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="buffer-narrowed-p">Function: <strong>buffer-narrowed-p</strong>
+</dt> <dd><p>This function returns non-<code>nil</code> if the buffer is narrowed, and <code>nil</code> otherwise. </p></dd>
+</dl> <dl> <dt id="save-restriction">Special Form: <strong>save-restriction</strong> <em>body…</em>
+</dt> <dd>
+<p>This special form saves the current bounds of the accessible portion, evaluates the <var>body</var> forms, and finally restores the saved bounds, thus restoring the same state of narrowing (or absence thereof) formerly in effect. The state of narrowing is restored even in the event of an abnormal exit via <code>throw</code> or error (see <a href="nonlocal-exits">Nonlocal Exits</a>). Therefore, this construct is a clean way to narrow a buffer temporarily. </p> <p>The value returned by <code>save-restriction</code> is that returned by the last form in <var>body</var>, or <code>nil</code> if no body forms were given. </p> <p><strong>Caution:</strong> it is easy to make a mistake when using the <code>save-restriction</code> construct. Read the entire description here before you try it. </p> <p>If <var>body</var> changes the current buffer, <code>save-restriction</code> still restores the restrictions on the original buffer (the buffer whose restrictions it saved from), but it does not restore the identity of the current buffer. </p> <p><code>save-restriction</code> does <em>not</em> restore point; use <code>save-excursion</code> for that. If you use both <code>save-restriction</code> and <code>save-excursion</code> together, <code>save-excursion</code> should come first (on the outside). Otherwise, the old point value would be restored with temporary narrowing still in effect. If the old point value were outside the limits of the temporary narrowing, this would fail to restore it accurately. </p> <p>Here is a simple example of correct use of <code>save-restriction</code>: </p> <div class="example"> <pre class="example">---------- Buffer: foo ----------
+This is the contents of foo
+This is the contents of foo
+This is the contents of foo∗
+---------- Buffer: foo ----------
+</pre>
+
+<pre class="example">(save-excursion
+  (save-restriction
+    (goto-char 1)
+    (forward-line 2)
+    (narrow-to-region 1 (point))
+    (goto-char (point-min))
+    (replace-string "foo" "bar")))
+
+---------- Buffer: foo ----------
+This is the contents of bar
+This is the contents of bar
+This is the contents of foo∗
+---------- Buffer: foo ----------
+</pre>
+</div> </dd>
+</dl><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/Narrowing.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Narrowing.html</a>
+  </p>
+</div>