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

Better help.lint, fix some typos

db4
Slava Pestov 2008-09-24 00:45:49 -05:00
parent 4b58f0b623
commit c03d4ff7d6
7 changed files with 27 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
basis/help/cookbook/cookbook.factor
View File

@ -312,13 +312,13 @@ ARTICLE: "cookbook-pitfalls" "Pitfalls to avoid"
{ "When a source file uses two vocabularies which define words with the same name, the order of the vocabularies in the " { $link POSTPONE: USE: } " or " { $link POSTPONE: USING: } " forms is important. The parser prints warnings when vocabularies shadow words from other vocabularies; see " { $link "vocabulary-search-shadow" } ". The " { $vocab-link "qualified" } " vocabulary implements qualified naming, which can be used to resolve ambiguities." } { "When a source file uses two vocabularies which define words with the same name, the order of the vocabularies in the " { $link POSTPONE: USE: } " or " { $link POSTPONE: USING: } " forms is important. The parser prints warnings when vocabularies shadow words from other vocabularies; see " { $link "vocabulary-search-shadow" } ". The " { $vocab-link "qualified" } " vocabulary implements qualified naming, which can be used to resolve ambiguities." }
{ "If a literal object appears in a word definition, the object itself is pushed on the stack when the word executes, not a copy. If you intend to mutate this object, you must " { $link clone } " it first. See " { $link "syntax-literals" } "." } { "If a literal object appears in a word definition, the object itself is pushed on the stack when the word executes, not a copy. If you intend to mutate this object, you must " { $link clone } " it first. See " { $link "syntax-literals" } "." }
{ "For a discussion of potential issues surrounding the " { $link f } " object, see " { $link "booleans" } "." } { "For a discussion of potential issues surrounding the " { $link f } " object, see " { $link "booleans" } "." }
{ "Factor's object system is quite flexible. Careless usage of union, mixin and predicate classes can lead to similar problems to those caused by ``multiple inheritance'' in other languages. In particular, it is possible to have two classes such that they have a non-empty intersection and yet neither is a subclass of the other. If a generic word defines methods on two such classes, method precedence is undefined for objects that are instances of both classes. See " { $link "method-order" } " for details." } { "Factor's object system is quite flexible. Careless usage of union, mixin and predicate classes can lead to similar problems to those caused by ``multiple inheritance'' in other languages. In particular, it is possible to have two classes such that they have a non-empty intersection and yet neither is a subclass of the other. If a generic word defines methods on two such classes, various disambiguation rules are applied to ensure method dispatch remains deterministic, however they may not be what you expect. See " { $link "method-order" } " for details." }
{ "Performance-sensitive code should have a static stack effect so that it can be compiled by the optimizing word compiler, which generates more efficient code than the non-optimizing quotation compiler. See " { $link "inference" } " and " { $link "compiler" } "." { "Performance-sensitive code should have a static stack effect so that it can be compiled by the optimizing word compiler, which generates more efficient code than the non-optimizing quotation compiler. See " { $link "inference" } " and " { $link "compiler" } "."
$nl $nl
"This means that methods defined on performance sensitive, frequently-called core generic words such as " { $link nth } " should have static stack effects which are consistent with each other, since a generic word will only have a static stack effect if all methods do." "This means that methods defined on performance sensitive, frequently-called core generic words such as " { $link nth } " should have static stack effects which are consistent with each other, since a generic word will only have a static stack effect if all methods do."
$nl $nl
"Unit tests for the " { $vocab-link "inference" } " vocabulary can be used to ensure that any methods your vocabulary defines on core generic words have static stack effects:" "Unit tests for the " { $vocab-link "stack-checker" } " vocabulary can be used to ensure that any methods your vocabulary defines on core generic words have static stack effects:"
{ $code "\"inference\" test" } { $code "\"stack-checker\" test" }
"In general, you should strive to write code with inferable stack effects, even for sections of a program which are not performance sensitive; the " { $link infer. } " tool together with the optimizing compiler's error reporting can catch many bugs ahead of time." } "In general, you should strive to write code with inferable stack effects, even for sections of a program which are not performance sensitive; the " { $link infer. } " tool together with the optimizing compiler's error reporting can catch many bugs ahead of time." }
{ "Be careful when calling words which access variables from a " { $link make-assoc } " which constructs an assoc with arbitrary keys, since those keys might shadow variables." } { "Be careful when calling words which access variables from a " { $link make-assoc } " which constructs an assoc with arbitrary keys, since those keys might shadow variables." }
{ "If " { $link run-file } " throws a stack depth assertion, it means that the top-level form in the file left behind values on the stack. The stack depth is compared before and after loading a source file, since this type of situation is almost always an error. If you have a legitimate need to load a source file which returns data in some manner, define a word in the source file which produces this data on the stack and call the word after loading the file." } { "If " { $link run-file } " throws a stack depth assertion, it means that the top-level form in the file left behind values on the stack. The stack depth is compared before and after loading a source file, since this type of situation is almost always an error. If you have a legitimate need to load a source file which returns data in some manner, define a word in the source file which produces this data on the stack and call the word after loading the file." }

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

@ -1,10 +1,10 @@
USING: help help.markup help.syntax help.definitions help.topics USING: help help.markup help.syntax help.definitions help.topics
namespaces words sequences classes assocs vocabs kernel arrays namespaces words sequences classes assocs vocabs kernel arrays
prettyprint.backend kernel.private io generic math system prettyprint.backend kernel.private io generic math system
strings sbufs vectors byte-arrays strings sbufs vectors byte-arrays quotations
quotations io.streams.byte-array io.streams.byte-array classes.builtin parser lexer
classes.builtin parser lexer classes.predicate classes.union classes.predicate classes.union classes.intersection
classes.intersection classes.singleton classes.tuple ; classes.singleton classes.tuple tools.vocabs.browser ;
IN: help.handbook IN: help.handbook
ARTICLE: "conventions" "Conventions" ARTICLE: "conventions" "Conventions"
@ -139,7 +139,7 @@ ARTICLE: "collections" "Collections"
{ $subsection "heaps" } { $subsection "heaps" }
{ $subsection "graphs" } { $subsection "graphs" }
{ $subsection "buffers" } { $subsection "buffers" }
"There are many other collections in " { $snippet "extra/" } ", such as " { $vocab-link "disjoint-sets" } ", " { $vocab-link "persistent-vectors" } ", and " { $vocab-link "tuple-arrays" } "." ; "There are also many other vocabularies tagged " { $link T{ vocab-tag { name "collections" } } } " in the library." ;
USING: io.encodings.utf8 io.encodings.utf16 io.encodings.binary io.encodings.ascii io.files ; USING: io.encodings.utf8 io.encodings.utf16 io.encodings.binary io.encodings.ascii io.files ;
@ -244,7 +244,8 @@ ARTICLE: "handbook-language-reference" "Language reference"
{ $subsection "program-org" } { $subsection "program-org" }
{ $subsection "numbers" } { $subsection "numbers" }
{ $subsection "collections" } { $subsection "collections" }
{ $subsection "io" } ; { $subsection "io" }
"Vocabularies tagged " { $link T{ vocab-tag { name "extensions" } } } " implement various additional language abstractions." ;
ARTICLE: "handbook-environment-reference" "Environment reference" ARTICLE: "handbook-environment-reference" "Environment reference"
{ $subsection "prettyprint" } { $subsection "prettyprint" }

20
basis/help/lint/lint.factor
View File

@ -61,10 +61,10 @@ IN: help.lint
: vocab-exists? ( name -- ? ) : vocab-exists? ( name -- ? )
dup vocab swap "all-vocabs" get member? or ; dup vocab swap "all-vocabs" get member? or ;
: check-modules ( word element -- ) : check-modules ( element -- )
nip \ $vocab-link swap elements [ \ $vocab-link swap elements [
second second
vocab-exists? [ "Missing vocabulary" throw ] unless vocab-exists? [ "$vocab-link to non-existent vocabulary" throw ] unless
] each ; ] each ;
: check-rendering ( word element -- ) : check-rendering ( word element -- )
@ -91,7 +91,7 @@ M: help-error error.
2dup check-examples 2dup check-examples
2dup check-values 2dup check-values
2dup check-see-also 2dup check-see-also
2dup check-modules 2dup nip check-modules
2dup drop check-rendering 2dup drop check-rendering
] assert-depth 2drop ] assert-depth 2drop
] check-something ] check-something
@ -101,12 +101,20 @@ M: help-error error.
: check-article ( article -- ) : check-article ( article -- )
[ [
[ dup check-rendering ] assert-depth drop dup article-content [
2dup check-modules check-rendering
] assert-depth 2drop
] check-something ; ] check-something ;
: files>vocabs ( -- assoc )
vocabs
[ [ [ vocab-docs-path ] keep ] H{ } map>assoc ]
[ [ [ vocab-source-path ] keep ] H{ } map>assoc ]
bi assoc-union ;
: group-articles ( -- assoc ) : group-articles ( -- assoc )
articles get keys articles get keys
vocabs [ dup vocab-docs-path swap ] H{ } map>assoc files>vocabs
H{ } clone [ H{ } clone [
'[ '[
dup >link where dup dup >link where dup

2
basis/html/components/components.factor
View File

@ -9,7 +9,7 @@ xmode.code2html lcs.diff2html farkup
html.elements html.streams html.forms ; html.elements html.streams html.forms ;
IN: html.components IN: html.components
GENERIC: render* ( value name render -- ) GENERIC: render* ( value name renderer -- )
: render ( name renderer -- ) : render ( name renderer -- )
prepare-value prepare-value

1
basis/html/forms/forms-docs.factor
View File

@ -73,6 +73,7 @@ HELP: with-each-value
{ $notes "This word is used to implement the " { $snippet "t:each" } " tag of the " { $vocab-link "html.templates.chloe" } " templating system. It can also be called directly from " { $vocab-link "html.templates.fhtml" } " templates." } ; { $notes "This word is used to implement the " { $snippet "t:each" } " tag of the " { $vocab-link "html.templates.chloe" } " templating system. It can also be called directly from " { $vocab-link "html.templates.fhtml" } " templates." } ;
HELP: with-each-object HELP: with-each-object
{ $values { "name" string } { "quot" quotation } }
{ $description "Calls the quotation with each element of the value named " { $snippet "name" } "; the value must be a sequence. The quotation is called in a new dynamic scope where the object's slots become named values, as if " { $link from-object } " was called." } { $description "Calls the quotation with each element of the value named " { $snippet "name" } "; the value must be a sequence. The quotation is called in a new dynamic scope where the object's slots become named values, as if " { $link from-object } " was called." }
{ $notes "This word is used to implement the " { $snippet "t:bind-each" } " tag of the " { $vocab-link "html.templates.chloe" } " templating system. It can also be called directly from " { $vocab-link "html.templates.fhtml" } " templates." } ; { $notes "This word is used to implement the " { $snippet "t:bind-each" } " tag of the " { $vocab-link "html.templates.chloe" } " templating system. It can also be called directly from " { $vocab-link "html.templates.fhtml" } " templates." } ;

1
basis/html/streams/streams-docs.factor
View File

@ -18,6 +18,7 @@ HELP: with-html-stream
{ $description "Calls the quotation in a new dynamic scope with " { $link output-stream } " rebound to an " { $link html-stream } " wrapping the current " { $link output-stream } "." } { $description "Calls the quotation in a new dynamic scope with " { $link output-stream } " rebound to an " { $link html-stream } " wrapping the current " { $link output-stream } "." }
{ $examples { $examples
{ $example { $example
"USING: io io.styles html.streams ;"
"[ \"Hello\" { { font-style bold } } format nl ] with-html-stream" "[ \"Hello\" { { font-style bold } } format nl ] with-html-stream"
"<span style='font-style: normal; font-weight: bold; '>Hello</span><br/>" "<span style='font-style: normal; font-weight: bold; '>Hello</span><br/>"
} }

1
basis/html/templates/templates-docs.factor
View File

@ -28,7 +28,6 @@ HELP: set-title
{ $description "Sets the title of the current page. This is usually called by child templates, and a master template calls " { $link write-title } "." } ; { $description "Sets the title of the current page. This is usually called by child templates, and a master template calls " { $link write-title } "." } ;
HELP: write-title HELP: write-title
{ $values { "string" string } }
{ $description "Writes the title of the current page, previously set by " { $link set-title } ". This is usually called by a master template after rendering a child template." } ; { $description "Writes the title of the current page, previously set by " { $link set-title } ". This is usually called by a master template after rendering a child template." } ;
HELP: add-style HELP: add-style