Mercurial > emacs

--- a/doc/lispref/ChangeLog	Wed Apr 08 18:03:17 2009 +0000
+++ b/doc/lispref/ChangeLog	Thu Apr 09 01:17:08 2009 +0000
@@ -1,3 +1,19 @@
+2009-04-09  Chong Yidong  <cyd@stupidchicken.com>
+
+	* text.texi (Yank Commands): Note that yank uses push-mark.
+	(Filling): Clarify REGION argument of fill-paragraph.  Document
+	fill-forward-paragraph-function.
+	(Special Properties): Remove "new in Emacs 22" declaration.
+	(Clickable Text): Merge with Links and Mouse-1 node.
+
+	* display.texi (Button Properties, Button Buffer Commands): Change
+	xref to Clickable Text.
+
+	* tips.texi (Key Binding Conventions): Change xref to Clickable
+	Text.
+
+	* elisp.texi (Top): Update node listing.
+
 2009-04-05  Chong Yidong  <cyd@stupidchicken.com>

 	* markers.texi (The Mark): Copyedits.  Improve description of
--- a/doc/lispref/display.texi	Wed Apr 08 18:03:17 2009 +0000
+++ b/doc/lispref/display.texi	Thu Apr 09 01:17:08 2009 +0000
@@ -4801,7 +4801,7 @@
 @item follow-link
 @kindex follow-link @r{(button property)}
 The follow-link property, defining how a @key{Mouse-1} click behaves
-on this button, @xref{Links and Mouse-1}.
+on this button, @xref{Clickable Text}.

 @item button
 @kindex button @r{(button property)}
@@ -4985,7 +4985,7 @@
 If the button has a non-@code{nil} @code{follow-link} property, and
 @var{mouse-1-click-follows-link} is set, a quick @key{Mouse-1} click
 will also activate the @code{push-button} command.
-@xref{Links and Mouse-1}.
+@xref{Clickable Text}.

 @deffn Command push-button &optional pos use-mouse-action
 Perform the action specified by a button at location @var{pos}.
--- a/doc/lispref/elisp.texi	Wed Apr 08 18:03:17 2009 +0000
+++ b/doc/lispref/elisp.texi	Thu Apr 09 01:17:08 2009 +0000
@@ -1078,7 +1078,6 @@
                               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
--- a/doc/lispref/text.texi	Wed Apr 08 18:03:17 2009 +0000
+++ b/doc/lispref/text.texi	Thu Apr 09 01:17:08 2009 +0000
@@ -978,14 +978,14 @@

 @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
@@ -1449,9 +1449,12 @@
 @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
@@ -1567,9 +1570,9 @@
 @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.

@@ -1583,6 +1586,17 @@
 @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
@@ -2593,7 +2607,6 @@
                              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
@@ -3025,8 +3038,6 @@
 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
@@ -3458,46 +3469,49 @@
 @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)
@@ -3523,72 +3537,51 @@
 @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.
-
-  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:
+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 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}:

@@ -3597,12 +3590,12 @@
 @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
+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 @kbd{Mouse-1} to follow links on
 file names only:

 @smallexample
@@ -3613,32 +3606,34 @@

 @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
@@ -3646,11 +3641,10 @@
   '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
--- a/doc/lispref/tips.texi	Wed Apr 08 18:03:17 2009 +0000
+++ b/doc/lispref/tips.texi	Thu Apr 09 01:17:08 2009 +0000
@@ -301,7 +301,7 @@
 way.

 In addition, they should mark the text as a kind of ``link'' so that
-@kbd{mouse-1} will follow it also.  @xref{Links and Mouse-1}.
+@kbd{mouse-1} will follow it also.  @xref{Clickable Text}.

 @item
 @cindex reserved keys