From: Richard M. Stallman Date: Mon, 18 Sep 2006 21:56:30 +0000 (+0000) Subject: (Fields): Clarify explanation of constrain-to-field. X-Git-Tag: emacs-pretest-22.0.90~472 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=a0c489f163dc4c90a2b5bb5477d57490e5741473;p=emacs.git (Fields): Clarify explanation of constrain-to-field. --- diff --git a/lispref/ChangeLog b/lispref/ChangeLog index f517868bc80..740313c0393 100644 --- a/lispref/ChangeLog +++ b/lispref/ChangeLog @@ -1,3 +1,7 @@ +2006-09-18 Richard Stallman + + * text.texi (Fields): Clarify explanation of constrain-to-field. + 2006-09-16 Eli Zaretskii * variables.texi (Tips for Defining): Fix a typo. diff --git a/lispref/text.texi b/lispref/text.texi index 4d2f278bee8..8d513b7f6bd 100644 --- a/lispref/text.texi +++ b/lispref/text.texi @@ -3783,20 +3783,25 @@ This function ``constrains'' @var{new-pos} to the field that closest to @var{new-pos} that is in the same field as @var{old-pos}. If @var{new-pos} is @code{nil}, then @code{constrain-to-field} uses -the value of point instead, and moves point to the resulting position. +the value of point instead, and moves point to the resulting position +as well as returning it. If @var{old-pos} is at the boundary of two fields, then the acceptable -positions for @var{new-pos} depend on the value of the optional argument -@var{escape-from-edge}. If @var{escape-from-edge} is @code{nil}, then -@var{new-pos} is constrained to the field that has the same @code{field} -property (either a text-property or an overlay property) that new -characters inserted at @var{old-pos} would get. (This depends on the +final positions depend on the argument @var{escape-from-edge}. If +@var{escape-from-edge} is @code{nil}, then @var{new-pos} must be in +the field whose @code{field} property equals what new characters +inserted at @var{old-pos} would inherit. (This depends on the stickiness of the @code{field} property for the characters before and after @var{old-pos}.) If @var{escape-from-edge} is non-@code{nil}, -@var{new-pos} is constrained to the union of the two adjacent fields. +@var{new-pos} can be anywhere in the two adjacent fields. Additionally, if two fields are separated by another field with the -special value @code{boundary}, then any point within this special field -is also considered to be ``on the boundary.'' +special value @code{boundary}, then any point within this special +field is also considered to be ``on the boundary.'' + +Commands like @kbd{C-a} with no argumemt, that normally move backward +to a specific kind of location and stay there once there, probably +should specify @code{nil} for @var{escape-from-edge}. Other motion +commands that check fields should probably pass @code{t}. If the optional argument @var{only-in-line} is non-@code{nil}, and constraining @var{new-pos} in the usual way would move it to a different