@deffn Command yank &optional arg
@cindex inserting killed text
-This command inserts before point the text at the front of the
-kill ring. It positions the mark at the beginning of that text, and
-point at the end.
+This command inserts before point the text at the front of the kill
+ring. It sets the mark at the beginning of that text, using
+@code{push-mark} (@pxref{The Mark}), and puts point at the end.
If @var{arg} is a non-@code{nil} list (which occurs interactively when
the user types @kbd{C-u} with no digits), then @code{yank} inserts the
text as described above, but puts point before the yanked text and
-puts the mark after it.
+sets the mark after it.
If @var{arg} is a number, then @code{yank} inserts the @var{arg}th
most recently killed text---the @var{arg}th element of the kill ring
@var{justify} is non-@code{nil}, each line is justified as well.
It uses the ordinary paragraph motion commands to find paragraph
boundaries. @xref{Paragraphs,,, emacs, The GNU Emacs Manual}.
-Interactively, when @var{region} is non-@code{nil} in Transient Mark
-mode and the mark is active, this command calls @code{fill-region}
-on the active region.
+
+When @var{region} is non-@code{nil}, then if Transient Mark mode is
+enabled and the mark is active, this command calls @code{fill-region}
+to fill all the paragraphs in the region, instead of filling only the
+current paragraph. When this command is called interactively,
+@var{region} is @code{t}.
@end deffn
@deffn Command fill-region start end &optional justify nosqueeze to-eop
@end defopt
@defvar fill-paragraph-function
-This variable provides a way for major modes to override the filling of
-paragraphs. If the value is non-@code{nil}, @code{fill-paragraph} calls
-this function to do the work. If the function returns a non-@code{nil}
+This variable provides a way to override the filling of paragraphs.
+If its value is non-@code{nil}, @code{fill-paragraph} calls this
+function to do the work. If the function returns a non-@code{nil}
value, @code{fill-paragraph} assumes the job is done, and immediately
returns that value.
@end example
@end defvar
+@defvar fill-forward-paragraph-function
+This variable provides a way to override how the filling functions,
+such as @code{fill-region} and @code{fill-paragraph}, move forward to
+the next paragraph. Its value should be a function, which is called
+with a single argument @var{n}, the number of paragraphs to move, and
+should return the difference between @var{n} and the number of
+paragraphs actually moved. The default value of this variable is
+@code{forward-paragraph}. @xref{Paragraphs,,, emacs, The GNU Emacs
+Manual}.
+@end defvar
+
@defvar use-hard-newlines
If this variable is non-@code{nil}, the filling functions do not delete
newlines that have the @code{hard} text property. These ``hard
only when text is examined.
* Clickable Text:: Using text properties to make regions of text
do something when you click on them.
-* Links and Mouse-1:: How to make @key{Mouse-1} follow a link.
* Fields:: The @code{field} property defines
fields within the buffer.
* Not Intervals:: Why text properties do not use
The @code{font-lock-mode} property is useful for special modes that
implement their own highlighting. @xref{Precalculated Fontification}.
-This property is new in Emacs 22.1.
-
@item mouse-face
@kindex mouse-face @r{(text property)}
The property @code{mouse-face} is used instead of @code{face} when the
@node Clickable Text
@subsection Defining Clickable Text
@cindex clickable text
+@cindex follow links
+@cindex mouse-1
@dfn{Clickable text} is text that can be clicked, with either the
-the mouse or via keyboard commands, to produce some result. Many
-major modes use clickable text to implement features such as
-hyper-links. The @code{button} package provides an easy way to insert
-and manipulate clickable text. @xref{Buttons}.
-
- In this section, we will explain how to manually set up clickable
-text in a buffer using text properties. This involves two things: (1)
-indicating clickability when the mouse moves over the text, and (2)
-making @kbd{RET} or a mouse click on that text do something.
-
- Indicating clickability usually involves highlighting the text, and
-often involves displaying helpful information about the action, such
-as which mouse button to press, or a short summary of the action.
-This can be done with the @code{mouse-face} and @code{help-echo}
-text properties. @xref{Special Properties}.
-Here is an example of how Dired does it:
+mouse or via a keyboard command, to produce some result. Many major
+modes use clickable text to implement textual hyper-links, or
+@dfn{links} for short.
+
+ The easiest way to insert and manipulate links is to use the
+@code{button} package. @xref{Buttons}. In this section, we will
+explain how to manually set up clickable text in a buffer, using text
+properties. For simplicity, we will refer to the clickable text as a
+@dfn{link}.
+
+ Implementing a link involves three separate steps: (1) indicating
+clickability when the mouse moves over the link; (2) making @kbd{RET}
+or @kbd{Mouse-2} on that link do something; and (3) setting up a
+@code{follow-link} condition so that the link obeys
+@code{mouse-1-click-follows-link}.
+
+ To indicate clickability, add the @code{mouse-face} text property to
+the text of the link; then Emacs will highlight the link when the
+mouse moves over it. In addition, you should define a tooltip or echo
+area message, using the @code{help-echo} text property. @xref{Special
+Properties}. For instance, here is how Dired indicates that file
+names are clickable:
@smallexample
-(condition-case nil
- (if (dired-move-to-filename)
- (add-text-properties
- (point)
- (save-excursion
- (dired-move-to-end-of-filename)
- (point))
- '(mouse-face highlight
- help-echo "mouse-2: visit this file in other window")))
- (error nil))
+ (if (dired-move-to-filename)
+ (add-text-properties
+ (point)
+ (save-excursion
+ (dired-move-to-end-of-filename)
+ (point))
+ '(mouse-face highlight
+ help-echo "mouse-2: visit this file in other window")))
@end smallexample
-@noindent
-The first two arguments to @code{add-text-properties} 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:
+ To make the link clickable, bind @key{RET} and @kbd{Mouse-2} to
+commands that perform the desired action. Each command should check
+to see whether it was called on a link, and act accordingly. For
+instance, Dired's major mode keymap binds @kbd{Mouse-2} to the
+following command:
@smallexample
(defun dired-mouse-find-file-other-window (event)
@end smallexample
@noindent
-The reason for the @code{save-excursion} construct is to avoid
-changing the current buffer. In this case,
-Dired uses the functions @code{posn-window} and @code{posn-point}
-to determine which buffer the click happened in and where, and
-in that buffer, @code{dired-get-file-for-visit} to determine which
-file to visit.
+This command uses the functions @code{posn-window} and
+@code{posn-point} to determine where the click occurred, and
+@code{dired-get-file-for-visit} to determine which file to visit.
- 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:
+ Instead of binding the mouse command in a major mode keymap, you can
+bind it within the link text, using the @code{keymap} text property
+(@pxref{Special Properties}). For instance:
@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))
+ (put-text-property link-start link-end '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.
+With this method, you can easily define different commands for
+different links. Furthermore, the global definition of @key{RET} and
+@kbd{Mouse-2} remain available for the rest of the text in the buffer.
+
+@vindex mouse-1-click-follows-link
+ The basic Emacs command for clicking on links is @kbd{Mouse-2}.
+However, for compatibility with other graphical applications, Emacs
+also recognizes @kbd{Mouse-1} clicks on links, provided the user
+clicks on the link quickly without moving the mouse. This behavior is
+controlled by the user option @code{mouse-1-click-follows-link}.
+@xref{Mouse References,,, emacs, The GNU Emacs Manual}.
+
+ To set up the link so that it obeys
+@code{mouse-1-click-follows-link}, you must either (1) apply a
+@code{follow-link} text or overlay property to the link text, or (2)
+bind the @code{follow-link} event to a keymap (which can be a major
+mode keymap or a local keymap specified via the @code{keymap} text
+property). The value of the @code{follow-link} property, or the
+binding for the @code{follow-link} event, acts as a ``condition'' for
+the link action. This condition tells Emacs two things: the
+circumstances under which a @kbd{Mouse-1} click should be regarded as
+occurring ``inside'' the link, and how to compute an ``action code''
+that says what to translate the @kbd{Mouse-1} click into. The link
+action condition can be one of the following:
@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}.
+If the condition is the symbol @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}:
@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.
+If the condition is a 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
+For example, here is how pcvs enables @kbd{Mouse-1} to follow links on
file names only:
@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.
+link and the condition itself is the action code. Clearly, you should
+specify this kind of condition only when applying the condition via a
+text or property overlay on the link text (so that it does not apply
+to the entire buffer).
@end table
@noindent
-The action code tells @key{Mouse-1} how to follow the link:
+The action code tells @kbd{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
+If the action code is a string or vector, the @kbd{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
+action of the @kbd{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}.
+@kbd{Mouse-1} translates into @kbd{f}. If it is @code{[foo]},
+@kbd{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.
+For any other non-@code{nil} action code, the @kbd{Mouse-1} event is
+translated into a @kbd{Mouse-2} event at the same position.
@end table
- To define @key{Mouse-1} to activate a button defined with
+ To define @kbd{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}:
+property. The property value should be a link action condition, as
+described above. @xref{Buttons}. For example, here is how Help mode
+handles @kbd{Mouse-1}:
@smallexample
(define-button-type 'help-xref
'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
+ To define @kbd{Mouse-1} on a widget defined with
+@code{define-widget}, give the widget a @code{:follow-link} property.
+The property value should be a link action condition, as described
+above. For example, here is how the @code{link} widget specifies that
a @key{Mouse-1} click shall be translated to @key{RET}:
@smallexample