document the fact that event callbacks are now delimited by a prompt

using the default continuation prompt tag

original commit: 7545d7d18fd0119e441d36ac516b89dc14693861

collects/scribblings/gui/win-overview.scrbl

@@ -862,7 +862,7 @@ An eventspace's event queue is actually a priority queue with events
 
 Although a programmer has no direct control over the order in which
  events are dispatched, a programmer can control the timing of
- dispatches by setting the event dispatch handler via the
+ dispatches by setting the @deftech{event dispatch handler} via the
  @scheme[event-dispatch-handler] parameter. This parameter and other
  eventspace procedures are described in more detail in
  @secref["eventspace-funcs"].
@@ -923,13 +923,26 @@ An eventspace is a @techlink[#:doc reference-doc]{synchronizable
  parent. (Note that the blocking state of an eventspace is unrelated
  to whether an event is ready for dispatching.)
 
-@subsection[#:tag "evtcontjump"]{Exceptions and Continuation Jumps}
+@subsection[#:tag "evtcontjump"]{Exceptions, Continuations, and Jumps}
 
-Whenever the system dispatches an event, the call to the handler
- procedure is wrapped so that full continuation jumps are not allowed
- to escape from the dispatch, and escape continuation jumps are
- blocked at the dispatch site. The following @scheme[block] procedure
- illustrates how the system blocks escape continuation jumps:
+Whenever the system dispatches an event, the call to the handler is
+ wrapped with a @deftech{continuation prompt} that delimits
+ continuations captured by the handler (see
+ @racket[call-with-continuation-prompt]). For example, if a button
+ callback captures a continuation, then applying the continuation
+ later reinstalls only the work to be done by the handler up until the
+ point that it returns; the dispatch machinery to invoke the button
+ callback is not included in the continuation. The delimited
+ continuation prompt is installed outside the call to the @tech{event
+ dispatch handler}, so any captured continuation includes the
+ invocation of the @tech{event dispatch handler}.
+
+An event-handling callback (and the @tech{event dispatch handler}) is
+ further wrapped with a @deftech{continuation barrier} and a
+ @racket[dynamic-wind] that blocks jumps (using continuation prompts
+ other than the default one) that escape past the dispatch site. The
+ following @scheme[block] procedure illustrates how the system blocks
+ escape continuation jumps:
 
 @def+int[
 (define (block f)
@@ -947,12 +960,9 @@ Whenever the system dispatches an event, the call to the handler
 (let/ec k (block (lambda () (k 10))) 11)
 ]
 
-Calls to the event dispatch handler are also protected with
- @scheme[block].
-
 This blocking of continuation jumps complicates the interaction
  between @scheme[with-handlers] and @scheme[yield] (or the default
- event dispatch handler). For example, in evaluating the expression
+ @tech{event dispatch handler}). For example, in evaluating the expression
 
 @schemeblock[
 (with-handlers ([(lambda (x) #t)
@@ -971,9 +981,9 @@ the @scheme["error during yield"] handler is @italic{never} called,
  sense that control jumps out of the event handler, but @scheme[yield]
  may dispatch another event rather than escaping or returning.
 
-The following expression demonstrates a more useful way to handle
- exceptions within @scheme[yield], for the rare cases where
- such handling is useful:
+The following expression demonstrates a more effective way to handle
+ exceptions within @scheme[yield], for the rare cases where such
+ handling is useful:
 
 @schemeblock[
 (let/ec k
@@ -1022,4 +1032,6 @@ animation frame with @method[canvas<%> suspend-flush] and
 are not flushed to the screen. Use @method[canvas<%> flush] to ensure
 that canvas content is flushed when it is ready if a @method[canvas<%>
 suspend-flush] will soon follow, because the process of flushing to
-the screen can be starved if flushing is frequently suspend.
+the screen can be starved if flushing is frequently suspend.  The
+method @xmethod[canvas% refresh-now] conveniently encapsulates this
+sequence.

doc/release-notes/gracket/HISTORY.txt

@@ -1,3 +1,12 @@
+Version 5.1, February 2011
+
+The GRacket executable is now a thin wrapper on the Racket executable,
+with the drawing and GUI libraries re-implemented as plain Racket
+libraries. See "Draw_and_GUI_5_1.txt" in the Racket release-notes
+directory. These notes will be discontinued.
+
+----------------------------------------------------------------------
+
 Version 5.0.2, October 2010
 
 Minor bug fixes

doc/release-notes/racket/Draw_and_GUI_5_1.txt

@@ -148,6 +148,11 @@ content of the combo-box popup menu, but the default implementation no
 longer triggers the popup menu; instead, the popup behavior is built
 into the control.
 
+Event callbacks are delimited by a continuation prompt using the
+default continuation prompt tag. As a result, continuations can be
+usufully captured during one event callback and applied during other
+callbacks or outside of an even callback.
+
 
 Removed Functions
 -----------------