steve
/
factor
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

rearrange top-level help a little so that introductory articles are more discoverable

db4
Joe Groff 2009-10-24 16:14:19 -05:00
parent d08e10bff6
commit 6f006cd0c7
4 changed files with 32 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
basis/help/handbook/handbook.factor
View File

@ -39,13 +39,13 @@ ARTICLE: "conventions" "Conventions"
{ $heading "Documentation conventions" }
"Factor documentation consists of two distinct bodies of text. There is a hierarchy of articles, much like this one, and there is word documentation. Help articles reference word documentation, and vice versa, but not every documented word is referenced from some help article."
$nl
"The browser, completion popups and other tools use a common set of " { $link "definitions.icons" } "."
$nl
"Every article has links to parent articles at the top. Explore these if the article you are reading is too specific."
$nl
"Some generic words have " { $strong "Description" } " headings, and others have " { $strong "Contract" } " headings. A distinction is made between words which are not intended to be extended with user-defined methods, and those that are."
{ $heading "Vocabulary naming conventions" }
"A vocabulary name ending in " { $snippet ".private" } " contains words which are either implementation detail, unsafe, or both. For example, the " { $snippet "sequence.private" } " vocabulary contains words which access sequence elements without bounds checking (" { $link "sequences-unsafe" } ")."
$nl
"You should avoid using internal words from the Factor library unless absolutely necessary. Similarly, your own code can place words in internal vocabularies if you do not want other people to use them unless they have a good reason."
"A vocabulary name ending in " { $snippet ".private" } " contains words which are either implementation details, unsafe, or both. For example, the " { $snippet "sequence.private" } " vocabulary contains words which access sequence elements without bounds checking (" { $link "sequences-unsafe" } "). You should avoid using private words from the Factor library unless absolutely necessary. Similarly, your own code can place words in private vocabularies using " { $link POSTPONE: <PRIVATE } " if you do not want other people using them without good reason."
{ $heading "Word naming conventions" }
"These conventions are not hard and fast, but are usually a good first step in understanding a word's behavior:"
{ $table
@ -364,12 +364,6 @@ ARTICLE: "handbook-library-reference" "Libraries"
{ $index [ orphan-articles { "help.home" "handbook" } diff ] } ;
ARTICLE: "handbook" "Factor handbook"
{ $heading "Getting Started" }
{ $subsections
"cookbook"
"first-program"
}
{ $heading "Reference" }
{ $subsections
"handbook-language-reference"
"io"
@ -379,15 +373,6 @@ ARTICLE: "handbook" "Factor handbook"
"ui-tools"
"alien"
"handbook-library-reference"
}
{ $heading "Explore loaded libraries" }
{ $subsections
"article-index"
"primitive-index"
"error-index"
"class-index"
}
{ $heading "Explore the code base" }
{ $subsections "vocab-index" } ;
} ;
ABOUT: "handbook"

35
basis/help/home/home-docs.factor
View File

@ -2,22 +2,33 @@ IN: help.home
USING: help.markup help.syntax ;
ARTICLE: "help.home" "Factor documentation"
"If this is your first time with Factor, you can start by writing " { $link "first-program" } "."
{ $heading "Reference" }
{ $list
{ $link "handbook" }
{ $link "vocab-index" }
{ $link "ui-tools" }
{ $link "ui-listener" }
{ $heading "Getting started" }
{ $subsections
"cookbook"
"first-program"
}
{ $heading "User interface" }
{ $subsections
"listener"
"ui-tools"
}
{ $heading "Reference" }
{ $subsections
"handbook"
"vocab-index"
"article-index"
"primitive-index"
"error-index"
"class-index"
}
{ $heading "Searches" }
"Use the search field in the top-right of the " { $link "ui-browser" } " window to search for words, vocabularies, and help articles."
{ $recent-searches }
{ $heading "Recently visited" }
{ $table
{ "Words" "Articles" "Vocabs" }
{ { $recent recent-words } { $recent recent-articles } { $recent recent-vocabs } }
}
"The browser, completion popups and other tools use a common set of " { $link "definitions.icons" } "."
{ $heading "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"
ABOUT: "help.home"

4
basis/listener/listener-docs.factor
View File

@ -48,10 +48,12 @@ $nl
"Multi-line expressions are supported:"
{ $example "{ 1 2 3 } [\n .\n] each" "1\n2\n3" }
"The listener knows when to expect more input by looking at the height of the stack. Parsing words such as " { $link POSTPONE: { } " leave elements on the parser stack, and corresponding words such as " { $link POSTPONE: } } " pop them."
$nl
"The listener will display the current contents of the datastack after every expression is evaluated. The listener can additionally watch dynamic variables:"
{ $subsections "listener-watch" }
"To start a nested listener:"
{ $subsections listener }
"To exit the listener, invoke the " { $link return } " word."
"To exit a listener, invoke the " { $link return } " word."
$nl
"Multi-line quotations can be read independently of the rest of the listener:"
{ $subsections read-quot } ;

4
basis/ui/tools/listener/listener-docs.factor
View File

@ -12,7 +12,7 @@ $nl
"Interactors implement the " { $link stream-readln } ", " { $link stream-read } " and " { $link read-quot } " generic words." } ;
ARTICLE: "ui-listener" "UI listener"
"The graphical listener is based around the terminal listener (" { $link "listener" } ") and adds an input history, and word and vocabulary completion."
"The graphical listener adds input history and word and vocabulary completion. See " { $link "listener" } " for general information on the listener."
{ $command-map listener-gadget "toolbar" }
{ $command-map interactor "completion" }
{ $command-map interactor "interactor" }
@ -48,4 +48,4 @@ TIP: "Scroll the listener from the keyboard by pressing " { $command listener-ga
TIP: "Press " { $command tool "common" refresh-all } " or run " { $link refresh-all } " to reload changed source files from disk. " ;
ABOUT: "ui-listener"
ABOUT: "ui-listener"