[Emacs-diffs] emacs/doc/lispref ChangeLog display.texi elisp....

[Chong Yidong]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Chong Yidong <cyd>      09/04/09 01:17:11

Modified files:
        doc/lispref    : ChangeLog display.texi elisp.texi text.texi 
                         tips.texi 

Log message:
        * 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.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/lispref/ChangeLog?cvsroot=emacs&r1=1.252&r2=1.253
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/lispref/display.texi?cvsroot=emacs&r1=1.40&r2=1.41
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/lispref/elisp.texi?cvsroot=emacs&r1=1.33&r2=1.34
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/lispref/text.texi?cvsroot=emacs&r1=1.12&r2=1.13
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/lispref/tips.texi?cvsroot=emacs&r1=1.6&r2=1.7

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/ChangeLog,v
retrieving revision 1.252
retrieving revision 1.253
diff -u -b -r1.252 -r1.253
--- ChangeLog   6 Apr 2009 01:20:55 -0000       1.252
+++ ChangeLog   9 Apr 2009 01:17:08 -0000       1.253
@@ -1,3 +1,19 @@
+2009-04-09  Chong Yidong  <address@hidden>
+
+       * 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  <address@hidden>
 
        * markers.texi (The Mark): Copyedits.  Improve description of

Index: display.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/display.texi,v
retrieving revision 1.40
retrieving revision 1.41
diff -u -b -r1.40 -r1.41
--- display.texi        13 Mar 2009 05:07:04 -0000      1.40
+++ display.texi        9 Apr 2009 01:17:09 -0000       1.41
@@ -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 address@hidden @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.
address@hidden and Mouse-1}.
address@hidden Text}.
 
 @deffn Command push-button &optional pos use-mouse-action
 Perform the action specified by a button at location @var{pos}.

Index: elisp.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/elisp.texi,v
retrieving revision 1.33
retrieving revision 1.34
diff -u -b -r1.33 -r1.34
--- elisp.texi  4 Apr 2009 22:34:23 -0000       1.33
+++ elisp.texi  9 Apr 2009 01:17:10 -0000       1.34
@@ -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

Index: text.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/text.texi,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -b -r1.12 -r1.13
--- text.texi   7 Feb 2009 11:09:34 -0000       1.12
+++ text.texi   9 Apr 2009 01:17:10 -0000       1.13
@@ -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
address@hidden (@pxref{The Mark}), and puts point at the end.
 
 If @var{arg} is a address@hidden 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 address@hidden, 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 address@hidden in Transient Mark
-mode and the mark is active, this command calls @code{fill-region}
-on the active region.
+
+When @var{region} is address@hidden, 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,
address@hidden 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 address@hidden, @code{fill-paragraph} calls
-this function to do the work.  If the function returns a address@hidden
+This variable provides a way to override the filling of paragraphs.
+If its value is address@hidden, @code{fill-paragraph} calls this
+function to do the work.  If the function returns a address@hidden
 value, @code{fill-paragraph} assumes the job is done, and immediately
 returns that value.
 
@@ -1583,6 +1586,17 @@
 @end example
 @end defvar
 
address@hidden 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
address@hidden  @xref{Paragraphs,,, emacs, The GNU Emacs
+Manual}.
address@hidden defvar
+
 @defvar use-hard-newlines
 If this variable is address@hidden, 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,27 +3469,34 @@
 @node Clickable Text
 @subsection Defining Clickable Text
 @cindex clickable text
address@hidden follow links
address@hidden 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
address@hidden for short.
+
+  The easiest way to insert and manipulate links is to use the
address@hidden 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
address@hidden
+
+  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
address@hidden condition so that the link obeys
address@hidden
+
+  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)
@@ -3487,17 +3505,13 @@
            (point))
          '(mouse-face highlight
            help-echo "mouse-2: visit this file in other window")))
-  (error nil))
 @end smallexample
 
address@hidden
-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
address@hidden to determine where the click occurred, and
address@hidden 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.
-
address@hidden Links and Mouse-1
address@hidden Links and Mouse-1
address@hidden follow links
address@hidden mouse-1
-
-  The normal Emacs command for activating text in read-only buffers is
address@hidden, 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
address@hidden
-
-  To define text as a link at the Lisp level, you should bind the
address@hidden event to a command to follow the link.  Then, to indicate that
address@hidden should also follow the link, you should specify a
address@hidden condition either as a text property or as a key
-binding:
-
address@hidden @asis
address@hidden @code{follow-link} property
-If the clickable text has a address@hidden @code{follow-link} text or overlay
-property, that specifies the condition.
-
address@hidden @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.
address@hidden 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
address@hidden should handle the link.
+With this method, you can easily define different commands for
+different links.  Furthermore, the global definition of @key{RET} and
address@hidden remain available for the rest of the text in the buffer.
+
address@hidden 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}.
address@hidden References,,, emacs, The GNU Emacs Manual}.
+
+  To set up the link so that it obeys
address@hidden, you must either (1) apply a
address@hidden 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 address@hidden @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 address@hidden @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
address@hidden is inside a link if @code{(@var{func} @var{pos})} evaluates
-to address@hidden  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
address@hidden  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
@@ -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"},
address@hidden translates into @kbd{f}.  If it is @code{[foo]},
address@hidden translates into @key{foo}.
address@hidden translates into @kbd{f}.  If it is @code{[foo]},
address@hidden translates into @key{foo}.
 
 @item anything else
-For any other address@hidden action code, the @code{mouse-1} event is
-translated into a @code{mouse-2} event at the same position.
+For any other address@hidden 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
address@hidden, 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
address@hidden, 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

Index: tips.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/tips.texi,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -b -r1.6 -r1.7
--- tips.texi   8 Jan 2009 05:29:02 -0000       1.6
+++ tips.texi   9 Apr 2009 01:17:11 -0000       1.7
@@ -301,7 +301,7 @@
 way.
 
 In addition, they should mark the text as a kind of ``link'' so that
address@hidden will follow it also.  @xref{Links and Mouse-1}.
address@hidden will follow it also.  @xref{Clickable Text}.
 
 @item
 @cindex reserved keys