Fix some issues with a recent change

* doc/lispref/commands.texi (Misc Events): Improve documentation
on pinch events.
* etc/NEWS: Update documentation status for some recent changes
and describe pinch events in more detail.
* lisp/face-remap.el (text-scale-pinch): Prevent pinch events
from being received in too quick succession.

doc/lispref/commands.texi

@@ -2088,21 +2088,21 @@ what event types to expect for the mouse wheel.
 @cindex @code{pinch} event
 @item (pinch @var{position} @var{dx} @var{dy} @var{scale} @var{angle})
 This kind of event is generated by the user performing a ``pinch''
-gesture with two fingers on a touchpad.  @var{position} is a mouse
-position list (@pxref{Click Events}) detailing the position of the
-mouse cursor when the event occured, @var{dx} is the distance between
-the horizontal positions of the fingers since the last event in the
-same sequence, @var{dy} is the vertical movement of the fingers since
-the last event in the same sequence, @var{scale} is the division of
-the current distance between the fingers and the distance at the start
-of the sequence, and @var{angle} is the delta in degrees between the
-angles of the fingers in this event and the fingers in the last event
-of the same sequence.
+gesture by placing two fingers on a touchpad and moving them towards
+or away from each other.  @var{position} is a mouse position list
+(@pxref{Click Events}) detailing the position of the mouse pointer
+when the event occured, @var{dx} is the change between the horizontal
+positions of the fingers since the last event in the same sequence,
+@var{dy} is the vertical movement of the fingers since the last event
+in the same sequence, @var{scale} is the ratio of the current distance
+between the fingers and the distance at the start of the sequence, and
+@var{angle} is the delta in degrees between the angles of the fingers
+in this event and the fingers in the last event of the same sequence.
 
 All arguments after @var{position} are floating point numbers.
 
 This event is usually sent as part of a sequence, which begins with
-the user placing two fingers on the touchpad and ends with the user
+the user placing two fingers on the touchpad, and ends with the user
 removing those fingers.  @var{dx}, @var{dy}, and @var{angle} will be
 @code{0.0} in the first event sent after a sequence begins.
 

etc/NEWS

@@ -312,7 +312,6 @@ effectively dragged.
 Customize this option to limit the number of entries in the menu
 "Edit->Paste from Kill Menu".  The default is 60.
 
----
 ** Performing a pinch gesture on a touchpad now increases the text scale.
 
 ** show-paren-mode
@@ -890,8 +889,9 @@ wheel on some mice, or when the user's finger moves off the touchpad.
 
 +++
 ** New event type 'pinch'.
-This event is sent when a user peforms a two-finger pinch gesture on a
-touchpad.
+This event is sent when a user peforms a pinch gesture on a touchpad,
+which is comprised of placing two fingers on the touchpad and moving
+them towards or away from each other.
 
 ** Keymaps and key definitions
 

lisp/face-remap.el

@@ -396,8 +396,19 @@ a top-level keymap, `text-scale-increase' or
 ;;;###autoload (define-key global-map [pinch] 'text-scale-pinch)
 ;;;###autoload
 (defun text-scale-pinch (event)
-  "Adjust the height of the default face by the scale in EVENT."
+  "Adjust the height of the default face by the scale in the pinch event EVENT."
   (interactive "e")
+  (when (not (eq (event-basic-type event) 'pinch))
+    (error "`text-scale-pinch' bound to bad event type"))
+  (let ((evt))
+    (catch 'done
+      (while t
+        (unless (and (setq evt (read-event nil nil 0.01))
+                     (eq (car evt) 'pinch))
+          (throw 'done nil))))
+    (when (and (consp evt)
+               (eq (car evt) 'pinch))
+      (setq event evt)))
   (let ((window (posn-window (nth 1 event)))
         (scale (nth 4 event))
         (dx (nth 2 event))