new repository

1 files changed, 24 insertions, 0 deletions

diff --git a/devdocs/elisp/fields.html b/devdocs/elisp/fields.html
new file mode 100644
index 00000000..12440f15
--- /dev/null
+++ b/devdocs/elisp/fields.html
@@ -0,0 +1,24 @@
+ <h4 class="subsection">Defining and Using Fields</h4>  <p>A field is a range of consecutive characters in the buffer that are identified by having the same value (comparing with <code>eq</code>) of the <code>field</code> property (either a text-property or an overlay property). This section describes special functions that are available for operating on fields. </p> <p>You specify a field with a buffer position, <var>pos</var>. We think of each field as containing a range of buffer positions, so the position you specify stands for the field containing that position. </p> <p>When the characters before and after <var>pos</var> are part of the same field, there is no doubt which field contains <var>pos</var>: the one those characters both belong to. When <var>pos</var> is at a boundary between fields, which field it belongs to depends on the stickiness of the <code>field</code> properties of the two surrounding characters (see <a href="sticky-properties">Sticky Properties</a>). The field whose property would be inherited by text inserted at <var>pos</var> is the field that contains <var>pos</var>. </p> <p>There is an anomalous case where newly inserted text at <var>pos</var> would not inherit the <code>field</code> property from either side. This happens if the previous character’s <code>field</code> property is not rear-sticky, and the following character’s <code>field</code> property is not front-sticky. In this case, <var>pos</var> belongs to neither the preceding field nor the following field; the field functions treat it as belonging to an empty field whose beginning and end are both at <var>pos</var>. </p> <p>In all of these functions, if <var>pos</var> is omitted or <code>nil</code>, the value of point is used by default. If narrowing is in effect, then <var>pos</var> should fall within the accessible portion. See <a href="narrowing">Narrowing</a>. </p> <dl> <dt id="field-beginning">Function: <strong>field-beginning</strong> <em>&amp;optional pos escape-from-edge limit</em>
+</dt> <dd>
+<p>This function returns the beginning of the field specified by <var>pos</var>. </p> <p>If <var>pos</var> is at the beginning of its field, and <var>escape-from-edge</var> is non-<code>nil</code>, then the return value is always the beginning of the preceding field that <em>ends</em> at <var>pos</var>, regardless of the stickiness of the <code>field</code> properties around <var>pos</var>. </p> <p>If <var>limit</var> is non-<code>nil</code>, it is a buffer position; if the beginning of the field is before <var>limit</var>, then <var>limit</var> will be returned instead. </p>
+</dd>
+</dl> <dl> <dt id="field-end">Function: <strong>field-end</strong> <em>&amp;optional pos escape-from-edge limit</em>
+</dt> <dd>
+<p>This function returns the end of the field specified by <var>pos</var>. </p> <p>If <var>pos</var> is at the end of its field, and <var>escape-from-edge</var> is non-<code>nil</code>, then the return value is always the end of the following field that <em>begins</em> at <var>pos</var>, regardless of the stickiness of the <code>field</code> properties around <var>pos</var>. </p> <p>If <var>limit</var> is non-<code>nil</code>, it is a buffer position; if the end of the field is after <var>limit</var>, then <var>limit</var> will be returned instead. </p>
+</dd>
+</dl> <dl> <dt id="field-string">Function: <strong>field-string</strong> <em>&amp;optional pos</em>
+</dt> <dd><p>This function returns the contents of the field specified by <var>pos</var>, as a string. </p></dd>
+</dl> <dl> <dt id="field-string-no-properties">Function: <strong>field-string-no-properties</strong> <em>&amp;optional pos</em>
+</dt> <dd><p>This function returns the contents of the field specified by <var>pos</var>, as a string, discarding text properties. </p></dd>
+</dl> <dl> <dt id="delete-field">Function: <strong>delete-field</strong> <em>&amp;optional pos</em>
+</dt> <dd><p>This function deletes the text of the field specified by <var>pos</var>. </p></dd>
+</dl> <dl> <dt id="constrain-to-field">Function: <strong>constrain-to-field</strong> <em>new-pos old-pos &amp;optional escape-from-edge only-in-line inhibit-capture-property</em>
+</dt> <dd>
+<p>This function constrains <var>new-pos</var> to the field that <var>old-pos</var> belongs to—in other words, it returns the position closest to <var>new-pos</var> that is in the same field as <var>old-pos</var>. </p> <p>If <var>new-pos</var> is <code>nil</code>, then <code>constrain-to-field</code> uses the value of point instead, and moves point to the resulting position in addition to returning that position. </p> <p>If <var>old-pos</var> is at the boundary of two fields, then the acceptable final positions depend on the argument <var>escape-from-edge</var>. If <var>escape-from-edge</var> is <code>nil</code>, then <var>new-pos</var> must be in the field whose <code>field</code> property equals what new characters inserted at <var>old-pos</var> would inherit. (This depends on the stickiness of the <code>field</code> property for the characters before and after <var>old-pos</var>.) If <var>escape-from-edge</var> is non-<code>nil</code>, <var>new-pos</var> can be anywhere in the two adjacent fields. Additionally, if two fields are separated by another field with the special value <code>boundary</code>, then any point within this special field is also considered to be on the boundary. </p> <p>Commands like <kbd>C-a</kbd> with no argument, that normally move backward to a specific kind of location and stay there once there, probably should specify <code>nil</code> for <var>escape-from-edge</var>. Other motion commands that check fields should probably pass <code>t</code>. </p> <p>If the optional argument <var>only-in-line</var> is non-<code>nil</code>, and constraining <var>new-pos</var> in the usual way would move it to a different line, <var>new-pos</var> is returned unconstrained. This used in commands that move by line, such as <code>next-line</code> and <code>beginning-of-line</code>, so that they respect field boundaries only in the case where they can still move to the right line. </p> <p>If the optional argument <var>inhibit-capture-property</var> is non-<code>nil</code>, and <var>old-pos</var> has a non-<code>nil</code> property of that name, then any field boundaries are ignored. </p> <p>You can cause <code>constrain-to-field</code> to ignore all field boundaries (and so never constrain anything) by binding the variable <code>inhibit-field-text-motion</code> to a non-<code>nil</code> value. </p>
+</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/Fields.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Fields.html</a>
+  </p>
+</div>