From 38bdb4f85a2e5df8e1769e050f1af1208d35ae8b Mon Sep 17 00:00:00 2001 From: slava Date: Sat, 17 Jun 2006 06:10:28 +0000 Subject: [PATCH] Minor fixes, new help section in handbook documents help system in detail, along with the markup language --- doc/handbook/handbook.facts | 6 +- doc/handbook/help.facts | 94 ++++++++++++++++++++++++++++ doc/handbook/tools.facts | 3 +- library/bootstrap/boot-stage1.factor | 1 + library/help/markup.factor | 6 +- library/help/search.factor | 2 +- library/help/search.facts | 2 +- 7 files changed, 106 insertions(+), 8 deletions(-) create mode 100644 doc/handbook/help.facts diff --git a/doc/handbook/handbook.facts b/doc/handbook/handbook.facts index 9851429146..203b389c41 100644 --- a/doc/handbook/handbook.facts +++ b/doc/handbook/handbook.facts @@ -17,9 +17,8 @@ ARTICLE: "handbook" "Factor documentation" { $subsection "cookbook-variables" } { $subsection "cookbook-vocabs" } { $subsection "cookbook-io" } -{ $heading "Reference" } +{ $heading "Language reference" } { $subsection "conventions" } -{ $subsection "tools" } { $subsection "syntax" } { $subsection "dataflow" } { $subsection "words" } @@ -30,6 +29,9 @@ ARTICLE: "handbook" "Factor documentation" { $subsection "parser" } { $subsection "prettyprint" } { $subsection "alien" } +{ $heading "Environment reference" } +{ $subsection "tools" } +{ $subsection "help" } { $heading "Index" } { $subsection "article-index" } { $subsection "primitive-index" } diff --git a/doc/handbook/help.facts b/doc/handbook/help.facts new file mode 100644 index 0000000000..513081267d --- /dev/null +++ b/doc/handbook/help.facts @@ -0,0 +1,94 @@ +USING: help ; + +ARTICLE: "help" "The help system" +"The help system maintains documentation written in a simple markup language, along with cross-referencing and search. Documentation can either exist as free-standing " { $emphasis "articles" } " or be associated with words." +{ $subsection "browsing-help" } +{ $subsection "searching-help" } +{ $subsection "writing-help" } ; + +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." +{ $subsection handbook } +"Help topics are identified by article name strings, or words. You can request a specific help topic:" +{ $subsection help } +"You can also view a word's documentation and definition at once:" +{ $subsection see-help } +"You can request a list of topics linking to a specific topic:" +{ $subsection links-in. } ; + +ARTICLE: "searching-help" "Searching documentation" +"The help system maintains a full-text term index. The easiest way to search the help is from the help browser tool in the UI, however you can also search in the listener." +{ $subsection search-help. } +"A lower-level word:" +{ $subsection search-help } +{ $subsection "searching-help-impl" } ; + +ARTICLE: "searching-help-impl" "Full-text search implementation" +"The help system search engine is a very simple full-text indexer. The index is rebuilt with a call to this word:" +{ $subsection index-help } +"This indexes every help topic by first tokenizing the article content and discarding certain words," +{ $subsection tokenize } +"and then by adding it to the index:" +{ $subsection index-text } ; + +ARTICLE: "writing-help" "Writing documentation" +"A pair of parsing words are used to define free-standing articles and to associate documentation with words:" +{ $subsection POSTPONE: ARTICLE: } +{ $subsection POSTPONE: HELP: } +"The " { $emphasis "content" } " in both cases is a " { $emphasis "markup element" } ", a recursive structure taking one of the following forms:" +{ $list + { "a string," } + { "an array of markup elements," } + { "or an array of the form " { $snippet "{ $directive content... }" } ", where " { $snippet "$directive" } " is a markup word whose name starts with " { $snippet "$" } ", and " { $snippet "content..." } " is a series of markup elements" } +} +"Markup elements are therefore effectively just Factor objects, written using Factor syntax." +{ $subsection "printing-elements" } +{ $subsection "element-types" } ; + +ARTICLE: "printing-elements" "Printing markup elements" +"When writing documentation, it is useful to be able to print markup elements for testing purposes. Markup elements which are strings or arrays of elements are printed in the obvious way. Markup elements of the form " { $snippet "{ $directive content... }" } " are printed by executing the " { $snippet "$directive" } " word with the element content on the stack." +{ $subsection print-element } +{ $subsection print-content } ; + +ARTICLE: "element-types" "Element types" +"Markup elements can be classified into two broad categories, block elements and span elements. Block elements are inset with newlines before and after, whereas span elements flow with the paragraph text." +{ $subsection "span-elements" } +{ $subsection "block-elements" } +{ $subsection "markup-utils" } ; + +ARTICLE: "span-elements" "Span elements" +{ $subsection $emphasis } +{ $subsection $link } +{ $subsection $snippet } +{ $subsection $url } ; + +ARTICLE: "block-elements" "Block elements" +"The following are the standard headings found in word documentation:" +{ $subsection $values } +{ $subsection $description } +{ $subsection $contract } +{ $subsection $examples } +{ $subsection $warning } +{ $subsection $notes } +{ $subsection $side-effects } +{ $subsection $errors } +{ $subsection $see-also } +"Some additional elements:" +{ $subsection $code } +{ $subsection $curious } +{ $subsection $example } +{ $subsection $heading } +{ $subsection $links } +{ $subsection $list } +{ $subsection $markup-example } +{ $subsection $references } +{ $subsection $see } +{ $subsection $subsection } +{ $subsection $table } ; + +ARTICLE: "markup-utils" "Markup element utilities" +"Utility words to assist in defining new elements:" +{ $subsection simple-element } +{ $subsection ($span) } +{ $subsection ($block) } +{ $subsection ?terpri } ; diff --git a/doc/handbook/tools.facts b/doc/handbook/tools.facts index 052e89e42f..c5448286ff 100644 --- a/doc/handbook/tools.facts +++ b/doc/handbook/tools.facts @@ -74,8 +74,9 @@ ARTICLE: "memory" "Object memory" { $subsection instances } ; ARTICLE: "word-introspection" "Word introspection" -"You can display a word definition:" +"You can display a word's definition or documentation:" { $subsection see } +{ $subsection see-help } "Find words whose name contains a given string:" { $subsection apropos } "List all vocabularies, and list words in a vocabulary:" diff --git a/library/bootstrap/boot-stage1.factor b/library/bootstrap/boot-stage1.factor index 2a318af31c..7461a859bc 100644 --- a/library/bootstrap/boot-stage1.factor +++ b/library/bootstrap/boot-stage1.factor @@ -297,6 +297,7 @@ vectors words ; "/doc/handbook/dataflow.facts" "/doc/handbook/handbook.facts" "/doc/handbook/hashtables.facts" + "/doc/handbook/help.facts" "/doc/handbook/math.facts" "/doc/handbook/objects.facts" "/doc/handbook/parser.facts" diff --git a/library/help/markup.factor b/library/help/markup.factor index b15b3f1247..e49894cab0 100644 --- a/library/help/markup.factor +++ b/library/help/markup.factor @@ -93,14 +93,14 @@ M: link article-title link-name article-title ; M: link article-content link-name article-content ; M: link summary "Link: " swap link-name append ; +: >link ( obj -- obj ) dup word? [ ] unless ; + : ($subsection) ( quot object -- ) subsection-style [ - [ swap curry ] keep dup article-title swap + [ swap curry ] keep dup article-title swap >link rot write-outliner ] with-style ; -: >link ( obj -- obj ) dup word? [ ] unless ; - : $link ( article -- ) last-block off first link-style [ dup article-title swap >link write-object ] with-style ; diff --git a/library/help/search.factor b/library/help/search.factor index d4cec0e560..32266b2f04 100644 --- a/library/help/search.factor +++ b/library/help/search.factor @@ -50,5 +50,5 @@ SYMBOL: term-index : search-help. ( phrase -- ) "Search results for ``" write dup write "'':" print search-help [ - first [ article-title ] keep write-object terpri + first >link [ article-title ] keep write-object terpri ] each ; diff --git a/library/help/search.facts b/library/help/search.facts index eeb745a318..062d5fc426 100644 --- a/library/help/search.facts +++ b/library/help/search.facts @@ -6,7 +6,7 @@ HELP: ignored-word? "( string -- ? )" HELP: tokenize "( string -- seq )" { $values { "string" "a string" } { "seq" "a sequence of strings" } } -{ $description "Split a string along whitespace boundaries, convert all tokens to lower case, and stem all tokens." } ; +{ $description "Split a string along whitespace boundaries, convert all tokens to lower case, stem all tokens, and discards one-letter words and stop words." } ; HELP: index-text "( topic string -- )" { $values { "topic" "a help article name or a word" } { "string" "a string" } }