- definitions.icons now has a reference article

- move about to help.vocabs; it now opens the vocab browser instead
- help.vocabs is in default use list
- add runnable-vocab predicate class

basis/definitions/icons/icons-docs.factor

@@ -0,0 +1,12 @@
+IN: definitions.icons
+USING: help.markup help.syntax ;
+
+ARTICLE: "definitions.icons" "Definition icons"
+"The " { $vocab-link "definitions.icons" } " vocabulary associates common definition types with icons."
+{ $definition-icons }
+"Looking up the icon associated with a definition:"
+{ $subsection definition-icon }
+"Defining new icons:"
+{ $subsection POSTPONE: ICON: } ;
+
+ABOUT: "definitions.icons"

basis/definitions/icons/icons.factor

@@ -2,22 +2,29 @@
 ! See http://factorcode.org/license.txt for BSD license.
 USING: assocs classes.predicate fry generic io.pathnames kernel
 macros sequences vocabs words words.symbol words.constant
-lexer parser help.topics ;
+lexer parser help.topics help.markup namespaces sorting ;
 IN: definitions.icons
 
 GENERIC: definition-icon ( definition -- path )
 
-<PRIVATE
-
 : definition-icon-path ( string -- string' )
-    "resource:basis/definitions/icons/" prepend-path ".tiff" append ;
+    "vocab:definitions/icons/" prepend-path ".tiff" append ;
 
 <<
 
-SYNTAX: ICON:
-    scan-word \ definition-icon create-method
-    scan '[ drop _ definition-icon-path ]
-    define ;
+SYMBOL: icons
+
+icons [ H{ } clone ] initialize
+
+: define-icon ( class name -- )
+    [ swap icons get set-at ]
+    [
+        [ \ definition-icon create-method ]
+        [ '[ drop _ definition-icon-path ] ] bi*
+        define
+    ] 2bi ;
+
+SYNTAX: ICON: scan-word scan define-icon ;
 
 >>
 
@@ -29,12 +36,15 @@ ICON: primitive primitive-word
 ICON: symbol symbol-word
 ICON: constant constant-word
 ICON: word normal-word
-ICON: vocab-link unopen-vocab
 ICON: word-link word-help-article
 ICON: link help-article
+ICON: runnable-vocab runnable-vocab
+ICON: vocab open-vocab
+ICON: vocab-link unopen-vocab
 
-PRIVATE>
-
-M: vocab definition-icon
-    vocab-main "runnable-vocab" "open-vocab" ? definition-icon-path ;
-    
+: $definition-icons ( element -- )
+    drop
+    icons get >alist sort-keys
+    [ [ <$link> ] [ definition-icon-path <$image> ] bi* swap ] assoc-map
+    { "" "Definition class" } prefix
+    $table ;

basis/help/crossref/crossref-docs.factor

@@ -11,10 +11,7 @@ HELP: article-parent
 
 HELP: help-path
 { $values { "topic" "an article name or a word" } { "seq" "a new sequence" } }
-{ $description "Outputs a sequence of all help articles which contain " { $snippet "topic" } " as a subsection, traversing all the way up to the root." }
-{ $examples
-    { $example "USING: help.crossref prettyprint ;" "\"sequences\" help-path ." "{ \"collections\" \"handbook-language-reference\" \"handbook\" }" }
-} ;
+{ $description "Outputs a sequence of all help articles which contain " { $snippet "topic" } " as a subsection, traversing all the way up to the root." } ;
 
 HELP: xref-article
 { $values { "topic" "an article name or a word" } }

basis/help/help-docs.factor

@@ -69,12 +69,6 @@ ARTICLE: "element-types" "Element types"
 IN: help.markup
 ABOUT: "element-types"
 
-ARTICLE: "browsing-help" "Browsing documentation"
-"The easiest way to browse the help is from the help browser tool in the UI, however you can also display help topics in the listener. Help topics are identified by article name strings, or words. You can request a specific help topic:"
-{ $subsection help }
-"You can also display the main help article for a vocabulary:"
-{ $subsection about } ;
-
 ARTICLE: "writing-help" "Writing documentation"
 "By convention, documentation is written in files whose names end with " { $snippet "-docs.factor" } ". Vocabulary documentation should be placed in the same directory as the vocabulary source code; see " { $link "vocabs.loader" } "."
 $nl
@@ -148,11 +142,6 @@ HELP: help
 { $description
     "Displays a help topic."
 } ;
-HELP: about
-{ $values { "vocab" "a vocabulary specifier" } }
-{ $description
-    "Displays the main help article for the vocabulary. The main help article is set with the " { $link POSTPONE: ABOUT: } " parsing word."
-} ;
 
 HELP: :help
 { $description "Displays documentation for the most recent error." } ;

basis/help/help.factor

@@ -127,15 +127,6 @@ help-hook [ [ print-topic ] ] initialize
 : help ( topic -- )
     help-hook get call( topic -- ) ;
 
-: about ( vocab -- )
-    dup require
-    dup vocab [ ] [ no-vocab ] ?if
-    dup vocab-help [ help ] [
-        "The " write vocab-name write
-        " vocabulary does not define a main help article." print
-        "To define one, refer to \\ ABOUT: help" print
-    ] ?if ;
-
 : ($index) ( articles -- )
     sort-articles [ \ $subsection swap 2array ] map print-element ;
 

basis/help/home/home-docs.factor

@@ -2,18 +2,22 @@ IN: help.home
 USING: help.markup help.syntax ;
 
 ARTICLE: "help.home" "Factor documentation"
-{ $heading "Starting points" }
+"If this is your first time with Factor, you can start by writing " { $link "first-program" } "."
+{ $heading "Reference" }
 { $list
-  { $link "ui-listener" }
   { $link "handbook" }
   { $link "vocab-index" }
+  { $link "ui-tools" }
+  { $link "handbook-library-reference" }
 }
 { $heading "Recently visited" }
 { $table
   { "Words" "Articles" "Vocabs" }
   { { $recent recent-words } { $recent recent-articles } { $recent recent-vocabs } }
-} print-element
+}
+"The browser, completion popups and other tools use a common set of " { $link "definitions.icons" } "."
 { $heading "Recent searches" }
-{ $recent-searches } ;
+{ $recent-searches }
+"Use the search field in the top-right of the " { $link "ui-browser" } " window to search for words, vocabularies and help articles." ;
 
 ABOUT: "help.home"

basis/help/home/home.factor

@@ -24,7 +24,7 @@ M: object add-recent-where f ;
     first get [ nl ] [ 1array $pretty-link ] interleave ;
 
 : $recent-searches ( element -- )
-    drop recent-searches get [ nl ] [ ($link) ] interleave ;
+    drop recent-searches get [ <$link> ] map $list ;
 
 : redisplay-recent-page ( -- )
     "help.home" >link dup associate

basis/help/markup/markup.factor

@@ -140,6 +140,9 @@ ALIAS: $slot $snippet
 : $image ( element -- )
     [ [ "" ] dip first image associate format ] ($span) ;
 
+: <$image> ( path -- element )
+    1array \ $image prefix ;
+
 ! Some links
 : write-link ( string object -- )
     link-style get [ write-object ] with-style ;

basis/help/tips/tips-docs.factor

@@ -1,5 +1,6 @@
 IN: help.tips
-USING: help.markup help.syntax debugger ;
+USING: help.markup help.syntax debugger prettyprint see help help.vocabs
+help.apropos tools.time stack-checker editors ;
 
 TIP: "To look at the most recent error, run " { $link :error } ". To look at the most recent error's callstack, run " { $link :c } "." ;
 
@@ -15,6 +16,8 @@ TIP: "You can write documentation for your own code using the " { $link "help" }
 
 TIP: "You can write graphical applications using the " { $link "ui" } "." ;
 
+TIP: "Power tools: " { $links see edit help about apropos time infer. } ;
+ 
 ARTICLE: "all-tips-of-the-day" "All tips of the day"
 { $tips-of-the-day } ;
 

basis/help/vocabs/vocabs-docs.factor

@@ -1,4 +1,4 @@
-USING: help.markup help.syntax io strings ;
+USING: help help.topics help.markup help.syntax io strings ;
 IN: help.vocabs
 
 ARTICLE: "vocab-tags" "Vocabulary tags"
@@ -15,3 +15,24 @@ ARTICLE: "vocab-index" "Vocabulary index"
 HELP: words.
 { $values { "vocab" "a vocabulary name" } }
 { $description "Printings a listing of all the words in a vocabulary, categorized by type." } ;
+
+HELP: about
+{ $values { "vocab" "a vocabulary specifier" } }
+{ $description
+    "Displays the main help article for the vocabulary. The main help article is set with the " { $link POSTPONE: ABOUT: } " parsing word."
+} ;
+
+ARTICLE: "browsing-help" "Browsing documentation"
+"Help topics are instances of a mixin:"
+{ $subsection topic }
+"Most commonly, topics are article name strings, or words. You can display a specific help topic:"
+{ $subsection help }
+"You can also display the help for a vocabulary:"
+{ $subsection about }
+"To list a vocabulary's words only:"
+{ $subsection words. }
+{ $examples
+  { $code "\"evaluator\" help" }
+  { $code "\\ + help" }
+  { $code "\"io.files\" about" }
+} ;

basis/help/vocabs/vocabs.factor

@@ -9,6 +9,9 @@ make namespaces prettyprint sequences sets sorting summary
 tools.vocabs vocabs vocabs.loader words words.symbol definitions.icons ;
 IN: help.vocabs
 
+: about ( vocab -- )
+    [ require ] [ vocab help ] bi ;
+
 : $pretty-link ( element -- )
     [ first definition-icon 1array $image " " print-element ]
     [ $definition-link ]

basis/ui/tools/browser/browser.factor

@@ -78,7 +78,7 @@ M: browser-gadget focusable-child* search-field>> ;
     <browser-gadget> "Browser" open-status-window ;
 
 : browser-window ( -- )
-    "handbook" (browser-window) ;
+    "help.home" (browser-window) ;
 
 \ browser-window H{ { +nullary+ t } } define-command
 
@@ -97,7 +97,7 @@ M: browser-gadget focusable-child* search-field>> ;
 
 : com-forward ( browser -- ) model>> go-forward ;
 
-: com-documentation ( browser -- ) "help.home" swap show-help ;
+: com-home ( browser -- ) "help.home" swap show-help ;
 
 : browser-help ( -- ) "ui-browser" com-browse ;
 
@@ -106,7 +106,7 @@ M: browser-gadget focusable-child* search-field>> ;
 browser-gadget "toolbar" f {
     { T{ key-down f { A+ } "LEFT" } com-back }
     { T{ key-down f { A+ } "RIGHT" } com-forward }
-    { f com-documentation }
+    { T{ key-down f { A+ } "H" } com-home }
     { T{ key-down f f "F1" } browser-help }
 } define-command-map
 

basis/ui/tools/tools-docs.factor

@@ -57,8 +57,12 @@ ARTICLE: "ui-tools" "UI developer tools"
 "The " { $vocab-link "ui.tools" } " vocabulary hierarchy implements a collection of simple developer tools."
 $nl
 "To take full advantage of the UI tools, you should be using a supported text editor. See " { $link "editor" } "."
+$nl
+"Common functionality:"
 { $subsection "ui-shortcuts" }
 { $subsection "ui-presentations" }
+{ $subsection "definitions.icons" }
+"Tools:"
 { $subsection "ui-listener" }
 { $subsection "ui-browser" }
 { $subsection "ui-inspector" }

core/parser/parser.factor

@@ -168,6 +168,7 @@ SYMBOL: interactive-vocabs
     "help"
     "help.apropos"
     "help.lint"
+    "help.vocabs"
     "inspector"
     "io"
     "io.files"

core/vocabs/loader/loader-docs.factor

@@ -56,6 +56,7 @@ $nl
 "Application vocabularies can define a main entry point, giving the user a convenient way to run the application:"
 { $subsection POSTPONE: MAIN: }
 { $subsection run }
+{ $subsection runnable-vocab }
 { $see-also "vocabularies" "parser-files" "source-files" } ;
 
 ABOUT: "vocabs.loader"

core/vocabs/vocabs-docs.factor

@@ -96,3 +96,6 @@ $nl
 HELP: >vocab-link
 { $values { "name" string } { "vocab" "a vocabulary specifier" } }
 { $description "If the vocabulary is loaded, outputs the corresponding " { $link vocab } " instance, otherwise creates a new " { $link vocab-link } "." } ;
+
+HELP: runnable-vocab
+{ $class-description "The class of vocabularies with a " { $slot "main" } " word." } ;

core/vocabs/vocabs.factor

@@ -105,4 +105,7 @@ M: vocab-spec forget* forget-vocab ;
 
 SYMBOL: load-vocab-hook ! ( name -- vocab )
 
-: load-vocab ( name -- vocab ) load-vocab-hook get call( name -- vocab ) ;
+: load-vocab ( name -- vocab ) load-vocab-hook get call( name -- vocab ) ;
+
+PREDICATE: runnable-vocab < vocab
+    vocab-main >boolean ;