racket/gui: doc clarifications on refreshes and edit sequences

collects/scribblings/gui/editor-intf.scrbl

@@ -210,18 +210,31 @@ See also @method[editor<%> refresh-delayed?] and @method[editor<%>
 
 If the @racket[undoable?] flag is @racket[#f], then the changes made
  in the sequence cannot be reversed through the @method[editor<%>
- undo] method. To accomplish this, the editor just does not add
+ undo] method. See @elemref["ed-seq-undo"]{below} for more information
- entries to the undo log when in an edit sequence where the
+ on undo. The @racket[undoable?] flag is only effective for the outermost
- @racket[undoable?] flag is @racket[#f]. So, for example, if an
+ @method[editor<%> begin-edit-sequence] when nested sequences are
- @litchar{a} is inserted into the editor and then a @litchar{b}
+ used. Note that, for a @racket[text%] object, the character-inserting
- is inserted, and then an un-undoable edit-sequence begins,
+ version of @method[text% insert] interferes with sequence-based undo
- and the @litchar{a} is colored red, and then the edit-sequence ends,
+ groupings.
- then an undo will remove the @litchar{b}, leaving the @litchar{a}
+
+If the @racket[interrupt-streak?] flag is @racket[#f] and the sequence is
+ outermost, then special actions before and after the sequence count
+ as consecutive actions. For example, @method[editor<%> kill]s just before 
+ and after the sequence are appended in the clipboard.
+
+@elemtag["ed-seq-undo"]{@italic{Undo details:}} The behavior of @racket[undoable?] as @racket[#f] is
+ implemented by not adding entries to an undo log. For example, suppose that
+ an @litchar{a} is inserted into the editor, a @litchar{b}
+ is inserted, and then an un-undoable edit sequence begins,
+ and the @litchar{a} is colored red, and then the edit sequence ends.
+ An undo will remove the @litchar{b}, leaving the @litchar{a}
  colored red. 
 
- This behavior also means that editors can get confused. Consider
+ As another example, in the following interaction,
- this program:
+ @method[editor<%> undo] removes the @litchar{a}
- @examples[#:eval 
+ instead of the @litchar{b}:
+
+ @interaction[#:eval 
            editor-eval
            (eval:alts (define t (new text%))
                       ;; this is a pretty horrible hack, but 
@@ -243,28 +256,17 @@ If the @racket[undoable?] flag is @racket[#f], then the changes made
                                     "cab"]
                                    [else "cb"]))
                                (super-new)))))
-           (send t set-max-undo-history 'forever)
+           (begin
-           (send t insert "a")
+            (send t set-max-undo-history 'forever)
-           (send t insert "b")
+            (send t insert "a")
-           (send t begin-edit-sequence #f #f)
+            (send t insert "b")
-           (send t insert "c" 0 0)
+            (send t begin-edit-sequence #f #f)
-           (send t end-edit-sequence)
+            (send t insert "c" 0 0)
-           (send t get-text)
+            (send t end-edit-sequence)
-           (send t undo)
+            (send t get-text))
-           (send t get-text)]
+           (begin
- You might hope that the undo would remove the @litchar{b}, but it removes
+            (send t undo)
- the @litchar{a}.
+            (send t get-text))]
-      
- The @racket[undoable?] flag is only effective for the outermost
- @method[editor<%> begin-edit-sequence] when nested sequences are
- used. Note that, for a @racket[text%] object, the character-inserting
- version of @method[text% insert] interferes with sequence-based undo
- groupings.
-
-If the @racket[interrupt-streak?] flag is @racket[#f] and the sequence is
- outermost, then special actions before and after the sequence count
- as consecutive actions. For example, kills just before and after the
- sequence are appended in the copy buffer.
       
 }
 @methimpl{
@@ -1611,7 +1613,9 @@ The @method[editor<%> on-paint] method must not make any assumptions
  restore any drawing context settings that it changes.
 
 The editor is internally locked for writing and reflowing during a
- call to this method (see also @|lockdiscuss|).
+ call to this method (see also @|lockdiscuss|). The @method[editor<%>
+ on-paint] method is called during a refresh; see
+ @secref["editorthreads"].
 
 See also @method[editor<%> invalidate-bitmap-cache].
 

collects/scribblings/gui/snip-class.scrbl

@@ -210,7 +210,8 @@ See also @xmethod[editor<%> on-paint].
 
 The snip's editor is usually internally locked for
  writing and reflowing when this method is called
- (see also @|lockdiscuss|).
+ (see also @|lockdiscuss|), and it is normally in a refresh (see 
+ @secref["editorthreads"]).
 
 }
 @methimpl{