+@node Clickable Text
+@subsection Defining Clickable Text
+@cindex clickable text
+
+ There are two ways to set up @dfn{clickable text} in a buffer.
+There are typically two parts of this: to make the text highlight
+when the mouse is over it, and to make a mouse button do something
+when you click it on that part of the text.
+
+ Highlighting is done with the @code{mouse-face} text property.
+Here is an example of how Dired does it:
+
+@smallexample
+(condition-case nil
+ (if (dired-move-to-filename)
+ (put-text-property (point)
+ (save-excursion
+ (dired-move-to-end-of-filename)
+ (point))
+ 'mouse-face 'highlight))
+ (error nil))
+@end smallexample
+
+@noindent
+The first two arguments to @code{put-text-property} specify the
+beginning and end of the text.
+
+ The usual way to make the mouse do something when you click it
+on this text is to define @code{mouse-2} in the major mode's
+keymap. The job of checking whether the click was on clickable text
+is done by the command definition. Here is how Dired does it:
+
+@smallexample
+(defun dired-mouse-find-file-other-window (event)
+ "In dired, visit the file or directory name you click on."
+ (interactive "e")
+ (let (file)
+ (save-excursion
+ (set-buffer (window-buffer (posn-window (event-end event))))
+ (save-excursion
+ (goto-char (posn-point (event-end event)))
+ (setq file (dired-get-filename))))
+ (select-window (posn-window (event-end event)))
+ (find-file-other-window (file-name-sans-versions file t))))
+@end smallexample
+
+@noindent
+The reason for the outer @code{save-excursion} construct is to avoid
+changing the current buffer; the reason for the inner one is to avoid
+permanently altering point in the buffer you click on. In this case,
+Dired uses the function @code{dired-get-filename} to determine which
+file to visit, based on the position found in the event.
+
+ Instead of defining a mouse command for the major mode, you can define
+a key binding for the clickable text itself, using the @code{keymap}
+text property:
+
+@example
+(let ((map (make-sparse-keymap)))
+ (define-key map [mouse-2] 'operate-this-button)
+ (put-text-property (point)
+ (save-excursion
+ (dired-move-to-end-of-filename)
+ (point))
+ 'keymap map))
+@end example
+
+@noindent
+This method makes it possible to define different commands for various
+clickable pieces of text. Also, the major mode definition (or the
+global definition) remains available for the rest of the text in the
+buffer.
+
+@node Links and Mouse-1
+@subsection Links and Mouse-1
+@cindex follow links
+@cindex mouse-1
+
+ The normal Emacs command for activating text in read-only buffers is
+@key{Mouse-2}, which includes following textual links. However, most
+graphical applications use @key{Mouse-1} for following links. For
+compatibility, @key{Mouse-1} follows links in Emacs too, when you
+click on a link quickly without moving the mouse. The user can
+customize this behavior through the variable
+@code{mouse-1-click-follows-link}.
+
+ To define text as a link at the Lisp level, you should bind the
+@code{mouse-2} event to a command to follow the link. Then, to indicate that
+@key{Mouse-1} should also follow the link, you should specify a
+@code{follow-link} condition either as a text property or as a key
+binding:
+
+@table @asis
+@item @code{follow-link} property
+If the clickable text has a non-@code{nil} @code{follow-link} text or overlay
+property, that specifies the condition.
+
+@item @code{follow-link} event
+If there is a binding for the @code{follow-link} event, either on the
+clickable text or in the local keymap, the binding is the condition.
+@end table
+
+ Regardless of how you set the @code{follow-link} condition, its
+value is used as follows to determine whether the given position is
+inside a link, and (if so) to compute an @dfn{action code} saying how
+@key{Mouse-1} should handle the link.
+
+@table @asis
+@item @code{mouse-face}
+If the condition is @code{mouse-face}, a position is inside a link if
+there is a non-@code{nil} @code{mouse-face} property at that position.
+The action code is always @code{t}.
+
+For example, here is how Info mode handles @key{Mouse-1}:
+
+@smallexample
+(define-key Info-mode-map [follow-link] 'mouse-face)
+@end smallexample
+
+@item a function
+If the condition is a valid function, @var{func}, then a position
+@var{pos} is inside a link if @code{(@var{func} @var{pos})} evaluates
+to non-@code{nil}. The value returned by @var{func} serves as the
+action code.
+
+For example, here is how pcvs enables @key{Mouse-1} to follow links on
+file names only:
+
+@smallexample
+(define-key map [follow-link]
+ (lambda (pos)
+ (eq (get-char-property pos 'face) 'cvs-filename-face)))
+@end smallexample
+
+@item anything else
+If the condition value is anything else, then the position is inside a
+link and the condition itself is the action code. Clearly you should
+only specify this kind of condition on the text that constitutes a
+link.
+@end table
+
+@noindent
+The action code tells @key{Mouse-1} how to follow the link:
+
+@table @asis
+@item a string or vector
+If the action code is a string or vector, the @key{Mouse-1} event is
+translated into the first element of the string or vector; i.e., the
+action of the @key{Mouse-1} click is the local or global binding of
+that character or symbol. Thus, if the action code is @code{"foo"},
+@key{Mouse-1} translates into @kbd{f}. If it is @code{[foo]},
+@key{Mouse-1} translates into @key{foo}.
+
+@item anything else
+For any other non-@code{nil} action code, the @code{mouse-1} event is
+translated into a @code{mouse-2} event at the same position.
+@end table
+
+ To define @key{Mouse-1} to activate a button defined with
+@code{define-button-type}, give the button a @code{follow-link}
+property with a value as specified above to determine how to follow
+the link. For example, here is how Help mode handles @key{Mouse-1}:
+
+@smallexample
+(define-button-type 'help-xref
+ 'follow-link t
+ 'action #'help-button-action)
+@end smallexample
+
+ To define @key{Mouse-1} on a widget defined with
+@code{define-widget}, give the widget a @code{:follow-link} property
+with a value as specified above to determine how to follow the link.
+
+For example, here is how the @code{link} widget specifies that
+a @key{Mouse-1} click shall be translated to @key{RET}:
+
+@smallexample
+(define-widget 'link 'item
+ "An embedded link."
+ :button-prefix 'widget-link-prefix
+ :button-suffix 'widget-link-suffix
+ :follow-link "\C-m"
+ :help-echo "Follow the link."
+ :format "%[%t%]")
+@end smallexample
+
+@defun mouse-on-link-p pos
+@tindex mouse-on-link-p
+This function returns non-@code{nil} if position @var{pos} in the
+current buffer is on a link.
+@end defun
+
+@node Fields
+@subsection Defining and Using Fields
+@cindex fields
+
+ A field is a range of consecutive characters in the buffer that are
+identified by having the same value (comparing with @code{eq}) of the
+@code{field} property (either a text-property or an overlay property).
+This section describes special functions that are available for
+operating on fields.
+
+ You specify a field with a buffer position, @var{pos}. We think of
+each field as containing a range of buffer positions, so the position
+you specify stands for the field containing that position.
+
+ When the characters before and after @var{pos} are part of the same
+field, there is no doubt which field contains @var{pos}: the one those
+characters both belong to. When @var{pos} is at a boundary between
+fields, which field it belongs to depends on the stickiness of the
+@code{field} properties of the two surrounding characters (@pxref{Sticky
+Properties}). The field whose property would be inherited by text
+inserted at @var{pos} is the field that contains @var{pos}.
+
+ There is an anomalous case where newly inserted text at @var{pos}
+would not inherit the @code{field} property from either side. This
+happens if the previous character's @code{field} property is not
+rear-sticky, and the following character's @code{field} property is not
+front-sticky. In this case, @var{pos} 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}.
+
+ In all of these functions, if @var{pos} is omitted or @code{nil}, the
+value of point is used by default.
+
+@defun field-beginning &optional pos escape-from-edge limit
+@tindex field-beginning
+This function returns the beginning of the field specified by @var{pos}.
+
+If @var{pos} is at the beginning of its field, and
+@var{escape-from-edge} is non-@code{nil}, then the return value is
+always the beginning of the preceding field that @emph{ends} at @var{pos},
+regardless of the stickiness of the @code{field} properties around
+@var{pos}.
+
+If @var{limit} is non-@code{nil}, it is a buffer position; if the
+beginning of the field is before @var{limit}, then @var{limit} will be
+returned instead.
+@end defun
+
+@defun field-end &optional pos escape-from-edge limit
+@tindex field-end
+This function returns the end of the field specified by @var{pos}.
+
+If @var{pos} is at the end of its field, and @var{escape-from-edge} is
+non-@code{nil}, then the return value is always the end of the following
+field that @emph{begins} at @var{pos}, regardless of the stickiness of
+the @code{field} properties around @var{pos}.
+
+If @var{limit} is non-@code{nil}, it is a buffer position; if the end
+of the field is after @var{limit}, then @var{limit} will be returned
+instead.
+@end defun
+
+@defun field-string &optional pos
+@tindex field-string
+This function returns the contents of the field specified by @var{pos},
+as a string.
+@end defun
+
+@defun field-string-no-properties &optional pos
+@tindex field-string-no-properties
+This function returns the contents of the field specified by @var{pos},
+as a string, discarding text properties.
+@end defun
+
+@defun delete-field &optional pos
+@tindex delete-field
+This function deletes the text of the field specified by @var{pos}.
+@end defun
+
+@defun constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line inhibit-capture-property
+@tindex constrain-to-field
+This function ``constrains'' @var{new-pos} to the field that
+@var{old-pos} belongs to---in other words, it returns the position
+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.
+
+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
+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.
+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.''
+
+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
+line, @var{new-pos} is returned unconstrained. This used in commands
+that move by line, such as @code{next-line} and
+@code{beginning-of-line}, so that they respect field boundaries only in
+the case where they can still move to the right line.
+
+If the optional argument @var{inhibit-capture-property} is
+non-@code{nil}, and @var{old-pos} has a non-@code{nil} property of that
+name, then any field boundaries are ignored.
+
+You can cause @code{constrain-to-field} to ignore all field boundaries
+(and so never constrain anything) by binding the variable
+@code{inhibit-field-text-motion} to a non-@code{nil} value.
+@end defun
+