Update `fields' entry.

1 files changed, 21 insertions, 13 deletions

diff --git a/etc/NEWS b/etc/NEWS
index d0117bb5823..bf861e21d28 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2622,7 +2622,7 @@ Otherwise, it returns zero.
 
 There is now code to support an abstraction called `fields' in emacs
 buffers.  A field is a contiguous region of text with the same `field'
-text-property.
+property (which can be a text property or an overlay).
 
 Many emacs functions, such as forward-word, forward-sentence,
 forward-paragraph, beginning-of-line, etc., stop moving when they come
@@ -2639,9 +2639,10 @@ editing commands treat the user's text separately from the prompt.
 
 The following functions are defined for operating on fields:
 
-- Function: constrain-to-field NEW-POS OLD-POS &optional ESCAPE-FROM-EDGE ONLY-IN-LINE
+- Function: constrain-to-field NEW-POS OLD-POS &optional ESCAPE-FROM-EDGE ONLY-IN-LINE INHIBIT-CAPTURE-PROPERTY
 
 Return the position closest to NEW-POS that is in the same field as OLD-POS.
+
 A field is a region of text with the same `field' property.
 If NEW-POS is nil, then the current point is used instead, and set to the
 constrained position if that is is different.
@@ -2649,10 +2650,12 @@ constrained position if that is is different.
 If OLD-POS is at the boundary of two fields, then the allowable
 positions for NEW-POS depends on the value of the optional argument
 ESCAPE-FROM-EDGE: If ESCAPE-FROM-EDGE is nil, then NEW-POS is
-constrained to the field that has the same `field' text-property
+constrained to the field that has the same `field' char-property
 as any new characters inserted at OLD-POS, whereas if ESCAPE-FROM-EDGE
 is non-nil, NEW-POS is constrained to the union of the two adjacent
-fields.
+fields.  Additionally, if two fields are separated by another field with
+the special value `boundary', then any point within this special field is
+also considered to be `on the boundary'.
 
 If the optional argument ONLY-IN-LINE is non-nil and constraining
 NEW-POS would move it to a different line, NEW-POS is returned
@@ -2660,39 +2663,44 @@ unconstrained.  This useful for commands that move by line, like
 C-n or C-a, which should generally respect field boundaries
 only in the case where they can still move to the right line.
 
-- Function: erase-field &optional POS
+If the optional argument INHIBIT-CAPTURE-PROPERTY is non-nil, and OLD-POS has
+a non-nil property of that name, then any field boundaries are ignored.
+
+Field boundaries are not noticed if `inhibit-field-text-motion' is non-nil.
+
+- Function: delete-field &optional POS
 
-Erases the field surrounding POS.
+Delete the field surrounding POS.
 A field is a region of text with the same `field' property.
-If POS is nil, the position of the current buffer's point is used.
+If POS is nil, the value of point is used for POS.
 
 - Function: field-beginning &optional POS ESCAPE-FROM-EDGE
 
 Return the beginning of the field surrounding POS.
 A field is a region of text with the same `field' property.
-If POS is nil, the position of the current buffer's point is used.
-If ESCAPE-FROM-EDGE is non-nil and POS is already at beginning of an
+If POS is nil, the value of point is used for POS.
+If ESCAPE-FROM-EDGE is non-nil and POS is at the beginning of its
 field, then the beginning of the *previous* field is returned.
 
 - Function: field-end &optional POS ESCAPE-FROM-EDGE
 
 Return the end of the field surrounding POS.
 A field is a region of text with the same `field' property.
-If POS is nil, the position of the current buffer's point is used.
-If ESCAPE-FROM-EDGE is non-nil and POS is already at end of a field,
+If POS is nil, the value of point is used for POS.
+If ESCAPE-FROM-EDGE is non-nil and POS is at the end of its field,
 then the end of the *following* field is returned.
 
 - Function: field-string &optional POS
 
 Return the contents of the field surrounding POS as a string.
 A field is a region of text with the same `field' property.
-If POS is nil, the position of the current buffer's point is used.
+If POS is nil, the value of point is used for POS.
 
 - Function: field-string-no-properties &optional POS
 
 Return the contents of the field around POS, without text-properties.
 A field is a region of text with the same `field' property.
-If POS is nil, the position of the current buffer's point is used.
+If POS is nil, the value of point is used for POS.
 
 +++
 ** Image support.