diff --git a/basis/definitions/icons/icons-docs.factor b/basis/definitions/icons/icons-docs.factor new file mode 100644 index 0000000000..8bca46bc3a --- /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 7c5fbed9f4..7562658ea4 100644 --- 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 ) -> @@ -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 6ec35b23ce..ae227fde89 100644 --- 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 547ee871aa..be521eb93a 100644 --- 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 6fa4473d97..d20e06b6c6 100644 --- 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 d4d8a6206d..6608a6e9c0 100644 --- 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 b1b938cb45..f32c0db30d 100644 --- 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 a80d386638..8b5edf38c1 100644 --- 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 7148b25a37..8d732c5568 100644 --- 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 5f1a97205e..cbedce2f52 100644 --- 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 13bb0cdf3e..a8c93feee4 100644 --- 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 e1dcba9910..553ba0f6b9 100644 --- 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" 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 c591775429..93f45591a5 100644 --- 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 b71f6ed3be..6d613a8b24 100644 --- 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 527da053fb..e0d6fd4493 100644 --- 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 2929b50081..2c87d9736a 100644 --- 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 b9f38dfef3..edac418285 100644 --- 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