Documentation updates and UI fixes

TODO.FACTOR.txt

@@ -43,7 +43,6 @@
 - fix up the min thumb size hack
 - help cross-referencing
 - document FFI
-- document tools
 - document conventions
 - new turtle graphics tutorial
 - better line spacing in ui and html

doc/handbook/handbook.facts

@@ -1,10 +1,13 @@
-USING: help parser prettyprint ;
+USING: help inspector parser prettyprint ;
 
 ARTICLE: "handbook" "Factor documentation"
 "Welcome to Factor!"
 $terpri
+"The Factor user interface centers on the concept of a " { $emphasis "presentation" } ". A presentation is a graphical view of a live object."
+$terpri
+"Placing the mouse over a presentation highlights it with a border. Presentations are everywhere; help links, words, and code examples are all presentations. Clicking a presentation displays a browser window looking at the underlying object. A left click will reuse the current browser window; a right click always opens a new window."
+$terpri
 "Introductory material:"
-{ $subsection "presentation-intro" }
 { $subsection "tutorial" }
 { $subsection "quickref" }
 "Detailed reference documentation:"
@@ -19,26 +22,14 @@ $terpri
 { $subsection "prettyprint" }
 { $subsection "tools" } ;
 
-ARTICLE: "presentation-intro" "The presentation-based UI"
-"Factor provides a " { $emphasis "presentation-based" } " user interface. A " { $emphasis "presentation" } " is a graphical representation of a live object. You can see presentations everywhere; help links, words, and code examples are all presentations."
-$terpri
-"When you place the mouse over a presentation, it is highlighted with a surrounding border."
-$terpri
-"Clicking a presentation with the left mouse button invokes a default command. Clicking the right mouse button displays a menu of applicable commands." ;
-
 ARTICLE: "quickref" "Quick reference"
-"Some words for performing common operations at the listener:"
+"Loading source files:"
-{ $list
+{ $subsection run-file }
-    {
+"Displaying word documentation:"
-        "You can read the documentation for a word with " { $link help } ":"
+{ $subsection help }
-        { $code "\\ reverse help" }
+"Printing the top of the stack, and displaying the stack without popping:"
-    }
+{ $subsection . }
-    { "You can print the top of the stack with " { $link . } }
+{ $subsection .s }
-    {
-        "Source files are loaded with " { $link run-file } ":"
-        { $code "\"tetris.factor\" run-file" }
-    }
-}
 "If you enter an invalid word name, you will get a \"not a number\" error:"
 { $example
     "fdafasfa"

doc/handbook/tools.facts

@@ -1,11 +1,15 @@
-USING: help image inspector memory parser prettyprint sequences ;
+USING: help image inspector kernel listener memory parser
+prettyprint sequences test walker words ;
+
 ARTICLE: "tools" "Development tools"
 "This section covers words which are used during development, and not usually invoked directly by user code."
 { $subsection "listener" }
-{ $subsection "word-introspection" }
 { $subsection "describe" }
-{ $subsection "images" }
+{ $subsection "word-introspection" }
-{ $subsection "unit-test" } ;
+{ $subsection "annotations" }
+{ $subsection "timing" }
+{ $subsection "unit-test" }
+{ $subsection "images" } ;
 
 ARTICLE: "listener" "The listener"
 "The listener reads Factor expressions from a stream and evaluates them. The listener is the primary interface to the Factor runtime. Typically, you write Factor code in a text editor, then load it using the listener and test it."
@@ -22,8 +26,6 @@ $terpri
 $terpri
 "Source files can be loaded in:"
 { $subsection run-file }
-$terpri
-"An alternative way to load source is to use a handy word which reloads the original source file of a word definition:"
 { $subsection reload }
 "You can start a nested listener or exit a listener using the following words:"
 { $subsection listener }
@@ -40,9 +42,8 @@ ARTICLE: "word-introspection" "Word introspection"
 { $subsection see }
 "Find words whose name contains a given string:"
 { $subsection apropos }
-"List all vocabularies:"
+"List all vocabularies, and list words in a vocabulary:"
 { $subsection vocabs. }
-"List all words in a vocabulary:"
 { $subsection words. }
 "Display callers and words called by a given word:"
 { $subsection usage. }
@@ -60,33 +61,21 @@ ARTICLE: "describe" "Objects and the heap"
 "Finally, you can ask for a sequence of all objects which refer to a given object:"
 { $subsection references } ;
 
-ARTICLE: "images" "Working with images"
-"Factor is an " { $emphasis "image-based" } " system, meaning it integrates a persistence mechanism where the object heap can be checkpointed to disk and loaded back in. Every time Factor runs, it starts by loading an image. The image contains all code and data needed to run Factor in a \"ready-to-go\" form."
-$terpri
-"Image files are loaded by launching the Factor runtime with the image file as the first command line argument. Images are saved using one of the following two words; the latter takes an image path as a parameter:"
-{ $subsection save }
-{ $subsection save-image }
-"A new image can also be built from sources; this is known as " { $emphasis "bootstrap" } ". Bootstrap is a two-step process. The first stage is the creation of a bootstrap image inside a running Factor instance:"
-{ $subsection make-image }
-"The second stage is initiated by running the resulting bootstrap image. This stage loads any additional platform-specific code, compiles all words, and dumps a new, final image." ;
-
 ARTICLE: "walker" "The single stepper"
-
+"The single stepper evaluates a quotation a word at a time, offering the ability to look at stacks at any stage."
-;
+$terpri
-
+"Single stepping is inititated by passing a quotation to a combinator:"
-ARTICLE: "compiler" "The compiler"
+{ $subsection walk }
-compile
+"The single stepper spawns a nested listener. You can exit the nested listener using " { $link bye } "; this resumes execution of the quotation."
-try-compile
+$terpri
-recompile
+"The following words advance the single stepper; the latter recursively descends into compound definitions:"
-compiled
+{ $subsection step }
-compiled?
+{ $subsection into }
-compile-vocabs
+"At any point you can look at stacks and variables in the single stepper execution context:"
-compile-all
+{ $subsection &s }
-;
+{ $subsection &r }
-
+{ $subsection &get }
-ARTICLE: "inference" "Stack effect inference"
+"You can annotate a word with a breakpoint, so that the single stepper is started every time the word is called. See " { $link "annotations" } "." ;
-infer
-;
 
 ARTICLE: "unit-test" "Unit testing code"
 "A unit test is a piece of code which starts with known input values, then compares the output of a word with an expected output, where the expected output is defined by the word's contract."
@@ -100,9 +89,29 @@ $terpri
 { $subsection unit-test-fails } ;
 
 ARTICLE: "timing" "Timing code"
-time benchmark
+"You can time the execution of a quotation in the listener:"
-;
+{ $subsection time }
+"A lower-level word puts timings on the stack, intead of printing:"
+{ $subsection benchmark }
+"You can also read the system clock directly:"
+{ $subsection millis }
+"Another way to time code is to use the profiler. See " { $link "annotations" } "." ;
 
 ARTICLE: "annotations" "Word annotations"
-break break-on watch profile annotate
+"The word annotation feature modifies word definitions to add debugging code. You can restore the old definition by calling " { $link reload } " on the word in question."
-;
+{ $subsection watch }
+{ $subsection break }
+{ $subsection break-on }
+{ $subsection profile }
+"All of the above words are implemented using a single combinator which applies a quotation to a word definition to yield a new definition:"
+{ $subsection annotate } ;
+
+ARTICLE: "images" "Working with images"
+"Factor is an " { $emphasis "image-based" } " system, meaning it integrates a persistence mechanism where the object heap can be checkpointed to disk and loaded back in. Every time Factor runs, it starts by loading an image. The image contains all code and data needed to run Factor in a \"ready-to-go\" form."
+$terpri
+"Image files are loaded by launching the Factor runtime with the image file as the first command line argument. Images are saved using one of the following two words; the latter takes an image path as a parameter:"
+{ $subsection save }
+{ $subsection save-image }
+"A new image can also be built from sources; this is known as " { $emphasis "bootstrap" } ". Bootstrap is a two-step process. The first stage is the creation of a bootstrap image inside a running Factor instance:"
+{ $subsection make-image }
+"The second stage is initiated by running the resulting bootstrap image. This stage loads any additional platform-specific code, compiles all words, and dumps a new, final image." ;

library/tools/annotations.facts

@@ -12,11 +12,11 @@ HELP: watch "( word -- )"
 
 HELP: break "( word -- )"
 { $values { "word" "a word" } }
-{ $description "Changes a word definition so that it runs in the single-stepper." } ;
+{ $description "Changes a word definition so that it runs in the single stepper. See " { $link "walker" } "." } ;
 
 HELP: break-on "( word quot -- )"
 { $values { "word" "a word" } { "quot" "a quotation with stack effect " { $snippet "( -- ? )" } } }
-{ $description "Changes a word definition so that the quotation runs first, and if it outputs a true value, the word runs in the single-stepper." } ;
+{ $description "Changes a word definition so that the quotation runs first, and if it outputs a true value, the word runs in the single stepper. See " { $link "walker" } "." } ;
 
 HELP: profile "( word -- )"
 { $values { "word" "a word" } }

library/ui/browser.factor

@@ -37,8 +37,7 @@ C: book ( pages -- book )
     [ set-book-pages ] 2keep
     [ >r first first r> show-page ] keep ;
 
-M: book pref-dim* ( book -- dim )
+M: book pref-dim* ( book -- dim ) book-page pref-dim ;
-    book-pages { 0 0 0 } [ second pref-dim vmax ] reduce ;
 
 M: book layout* ( book -- )
     dup rect-dim swap book-page set-gadget-dim ;
@@ -48,7 +47,7 @@ M: book layout* ( book -- )
     [ first2 swapd make-pane <scroller> 2array ] map-with ;
 
 : <tab> ( name book -- button )
-    dupd [ show-page ] curry curry
+    dupd [ show-page drop ] curry curry
     >r <label> r> <bevel-button> ;
 
 : tabs ( assoc book gadget -- )
@@ -84,9 +83,15 @@ TUPLE: browser-button object ;
 
 : browser-window ( obj -- ) <browser> "Browser" open-window ;
 
+: new-browser? ( gadget -- ? )
+    find-browser not 3 hand-buttons get-global member? or ;
+
 : browser-button-action ( button -- )
-    [ browser-button-object ] keep find-browser
+    [ browser-button-object ] keep dup new-browser? [
-    [ dup save-current browse ] [ browser-window ] if* ;
+        drop browser-window
+    ] [
+        find-browser dup save-current browse
+    ] if ;
 
 C: browser-button ( gadget object -- button )
     [ set-browser-button-object ] keep

library/ui/gestures.factor

@@ -59,7 +59,7 @@ SYMBOL: hand-click-loc
 SYMBOL: hand-buttons
 V{ } clone hand-buttons set-global
 
-: button-gesture ( buttons gesture -- )
+: button-gesture ( button gesture -- )
     #! Send a gesture like [ button-down 2 ]; if nobody
     #! handles it, send [ button-down ].
     swap hand-clicked get-global 3dup >r add r> handle-gesture
@@ -141,10 +141,10 @@ V{ } clone hand-buttons set-global
     dup hand-buttons get-global push
     [ button-down ] button-gesture ;
 
-: send-button-up ( event loc world -- )
+: send-button-up ( button# loc world -- )
     move-hand
-    dup hand-buttons get-global delete
+    dup [ button-up ] button-gesture
-    [ button-up ] button-gesture ;
+    hand-buttons get-global delete ;
 
 : send-wheel ( up/down loc world -- )
     move-hand