- 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

diff --git a/basis/definitions/icons/icons-docs.factor b/basis/definitions/icons/icons-docs.factor
new file mode 100644 (file)
index 0000000..8bca46b
--- /dev/null
+++ b/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"
\ No newline at end of file

diff --git a/basis/definitions/icons/icons.factor b/basis/definitions/icons/icons.factor
index 7c5fbed9f4c83bb858f942dbe397e1185150151e..7562658ea4bc0c02aad399d2a5c489ad78cde9b1 100644 (file)
--- a/basis/definitions/icons/icons.factor
+++ b/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 ;
-    
\ No newline at end of file
+: $definition-icons ( element -- )
+    drop
+    icons get >alist sort-keys
+    [ [ <$link> ] [ definition-icon-path <$image> ] bi* swap ] assoc-map
+    { "" "Definition class" } prefix
+    $table ;
\ No newline at end of file

diff --git a/basis/help/crossref/crossref-docs.factor b/basis/help/crossref/crossref-docs.factor
index 6ec35b23cede601de9ac6715ce7590b231ac163f..ae227fde89be9440957d96a2663c7955fdd3de1c 100644 (file)
--- a/basis/help/crossref/crossref-docs.factor
+++ b/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" } }

diff --git a/basis/help/help-docs.factor b/basis/help/help-docs.factor
index 547ee871aa74510f06033c48ee5a488f89964ac6..be521eb93a6c2cc760926e49de9090320144f8e0 100644 (file)
--- a/basis/help/help-docs.factor
+++ b/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." } ;

diff --git a/basis/help/help.factor b/basis/help/help.factor
index 6fa4473d970eed65355f5ec0909926230d7f8014..d20e06b6c6009139cf76e09cd7c9d17ac293badc 100644 (file)
--- a/basis/help/help.factor
+++ b/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 ;
 

diff --git a/basis/help/home/home-docs.factor b/basis/help/home/home-docs.factor
index d4d8a6206df63bf89c3488b9858eaa4a6073dab2..6608a6e9c0eaee311f74d1fb595dfa68a4e6e8db 100644 (file)
--- a/basis/help/home/home-docs.factor
+++ b/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"
\ No newline at end of file

diff --git a/basis/help/home/home.factor b/basis/help/home/home.factor
index b1b938cb45f6ce83ae48928fc53ad92e4ebd5de5..f32c0db30d48e60f2aa728053467eb7f41f80f86 100644 (file)
--- a/basis/help/home/home.factor
+++ b/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

diff --git a/basis/help/markup/markup.factor b/basis/help/markup/markup.factor
index a80d38663898edf342be6ff2cb0e1041bba66ae5..8b5edf38c13442c1c2c342ea020ae9cafdb72319 100644 (file)
--- a/basis/help/markup/markup.factor
+++ b/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 ;

diff --git a/basis/help/tips/tips-docs.factor b/basis/help/tips/tips-docs.factor
index 7148b25a373efc9b1da390f2402407a2735b6a26..8d732c55680ae0ff60ae0150c0a3200f83bc6dca 100644 (file)
--- a/basis/help/tips/tips-docs.factor
+++ b/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 } ;
 

diff --git a/basis/help/vocabs/vocabs-docs.factor b/basis/help/vocabs/vocabs-docs.factor
index 5f1a97205e2593d3d9f69e9075e237966c69bdb7..cbedce2f52a88e48722fc044b3b5ab13df72f2a6 100644 (file)
--- a/basis/help/vocabs/vocabs-docs.factor
+++ b/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" }
+} ;
\ No newline at end of file

diff --git a/basis/help/vocabs/vocabs.factor b/basis/help/vocabs/vocabs.factor
index 13bb0cdf3e144fdbfb4387d59b2868913023cf3b..a8c93feee48b5dab0606000f273432b1f035f61d 100644 (file)
--- a/basis/help/vocabs/vocabs.factor
+++ b/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 ]

diff --git a/basis/ui/tools/browser/browser.factor b/basis/ui/tools/browser/browser.factor
index e1dcba99109c85dc8d0ad9ea066e9242f98e9b30..553ba0f6b94b7416c20f97fce32f52d48465fea6 100644 (file)
--- a/basis/ui/tools/browser/browser.factor
+++ b/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
 

diff --git a/basis/ui/tools/tools-docs.factor b/basis/ui/tools/tools-docs.factor
index c591775429aa2f6fe24a574431ac6f1ccc69d0d8..93f45591a540bb65e1b65bae425143a160964dce 100644 (file)
--- a/basis/ui/tools/tools-docs.factor
+++ b/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" }

diff --git a/core/parser/parser.factor b/core/parser/parser.factor
index b71f6ed3be7d6714e85cb45c391f6afc9f818af6..6d613a8b2459e30340bc3a46ec36a3845ba2f3da 100644 (file)
--- a/core/parser/parser.factor
+++ b/core/parser/parser.factor
@@ -168,6 +168,7 @@ SYMBOL: interactive-vocabs
     "help"
     "help.apropos"
     "help.lint"
+    "help.vocabs"
     "inspector"
     "io"
     "io.files"

diff --git a/core/vocabs/loader/loader-docs.factor b/core/vocabs/loader/loader-docs.factor
index 527da053fbbaf0b91dab00f61afcd58e252d8ce9..e0d6fd44931ed4ca3c410aba0895b2f4c0c95298 100644 (file)
--- a/core/vocabs/loader/loader-docs.factor
+++ b/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"

diff --git a/core/vocabs/vocabs-docs.factor b/core/vocabs/vocabs-docs.factor
index 2929b5008180fd1d1f1386b7394eea41911566b9..2c87d9736a1533b393382828ed405f0c7dda3b42 100644 (file)
--- a/core/vocabs/vocabs-docs.factor
+++ b/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." } ;
\ No newline at end of file

diff --git a/core/vocabs/vocabs.factor b/core/vocabs/vocabs.factor
index b9f38dfef3b6a0391efc445609ae2fc898003ec7..edac418285989cd95b4cd56810dd29e16ab7be4a 100644 (file)
--- a/core/vocabs/vocabs.factor
+++ b/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 ) ;
\ No newline at end of file
+: load-vocab ( name -- vocab ) load-vocab-hook get call( name -- vocab ) ;
+
+PREDICATE: runnable-vocab < vocab
+    vocab-main >boolean ;
\ No newline at end of file