A number of documentation fixes.

* Short-circuit combinators now show correct stack effect for quots
 * Groups and Clumps unchecked examples corrected, made runnable in listener
 * Class operations had duplicate link to class-types
 * Protocol slots readability fixed
 * Tuple word property for "tuple-layout" corrected to "layout"
 * cond>quot sentence started in lowercase
 * Method precedence code example missing stack effect for GENERIC:, M: integer explain changed to detail an integer
 * Motivation for default streams readability
 * Default input and output streams duplicate readln link removed from output stream words section
 * Looping combinators do description clarified
 * Make philosophy missing space
 * Linear order protocol duplicate after? link removed
 * Parsing words readability fix
 * Copied note regarding with-compilation-unit from define to define-declared and define-inline

basis/combinators/short-circuit/short-circuit-docs.factor

@@ -13,27 +13,27 @@ HELP: 0||
 { $description "If every quotation in the sequence outputs " { $link f } ", outputs " { $link f } ", otherwise outputs the result of the first quotation that did not yield " { $link f } "." } ;
 
 HELP: 1&&
-{ $values { "obj" object } { "quots" "a sequence of quotations with stack effect " { $snippet "( -- )" } } { "?" "the result of the last quotation, or " { $link f } } }
+{ $values { "obj" object } { "quots" "a sequence of quotations with stack effect " { $snippet "( obj -- )" } } { "?" "the result of the last quotation, or " { $link f } } }
 { $description "If every quotation in the sequence outputs a true value, outputs the result of the last quotation, otherwise outputs " { $link f } "." } ;
 
 HELP: 1||
-{ $values { "obj" object } { "quots" "a sequence of quotations" } { "?" "the first true result, or " { $link f } } }
+{ $values { "obj" object } { "quots" "a sequence of quotations with stack effect " { $snippet "( obj -- )" } } { "?" "the first true result, or " { $link f } } }
 { $description "Returns true if any quotation in the sequence returns true. Each quotation takes the same element from the datastack and must return a boolean." } ;
 
 HELP: 2&&
-{ $values { "obj1" object } { "obj2" object } { "quots" "a sequence of quotations with stack effect " { $snippet "( -- )" } } { "?" "the result of the last quotation, or " { $link f } } }
+{ $values { "obj1" object } { "obj2" object } { "quots" "a sequence of quotations with stack effect " { $snippet "( obj1 obj2 -- )" } } { "?" "the result of the last quotation, or " { $link f } } }
 { $description "If every quotation in the sequence outputs a true value, outputs the result of the last quotation, otherwise outputs " { $link f } "." } ;
 
 HELP: 2||
-{ $values { "obj1" object } { "obj2" object } { "quots" "a sequence of quotations" } { "?" "the first true result, or " { $link f } } }
+{ $values { "obj1" object } { "obj2" object } { "quots" "a sequence of quotations with stack effect " { $snippet "( obj1 obj2 -- )" } } { "?" "the first true result, or " { $link f } } }
 { $description "Returns true if any quotation in the sequence returns true. Each quotation takes the same two elements from the datastack and must return a boolean." } ;
 
 HELP: 3&&
-{ $values { "obj1" object } { "obj2" object } { "obj3" object } { "quots" "a sequence of quotations with stack effect " { $snippet "( -- )" } } { "?" "the result of the last quotation, or " { $link f } } }
+{ $values { "obj1" object } { "obj2" object } { "obj3" object } { "quots" "a sequence of quotations with stack effect " { $snippet "( obj1 obj2 obj3 -- )" } } { "?" "the result of the last quotation, or " { $link f } } }
 { $description "If every quotation in the sequence outputs a true value, outputs the result of the last quotation, otherwise outputs " { $link f } "." } ;
 
 HELP: 3||
-{ $values { "obj1" object } { "obj2" object } { "obj3" object } { "quots" "a sequence of quotations" } { "?" "the first true result, or " { $link f } } }
+{ $values { "obj1" object } { "obj2" object } { "obj3" object } { "quots" "a sequence of quotations with stack effect " { $snippet "( obj1 obj2 obj3 -- )" } } { "?" "the first true result, or " { $link f } } }
 { $description "Returns true if any quotation in the sequence returns true. Each quotation takes the same three elements from the datastack and must return a boolean." } ;
 
 HELP: n&&

basis/grouping/grouping-docs.factor

@@ -17,10 +17,16 @@ ARTICLE: "grouping" "Groups and clumps"
 "The difference can be summarized as the following:"
 { $list
     { "With groups, the subsequences form the original sequence when concatenated:"
-        { $unchecked-example "dup n groups concat sequence= ." "t" }
+        { $unchecked-example
+            "USING: grouping ;"
+            "{ 1 2 3 4 } dup" "2 <groups> concat sequence= ." "t"
+        }
     }
     { "With clumps, collecting the first element of each subsequence but the last one, together with the last subseqence, yields the original sequence:"
-        { $unchecked-example "dup n clumps unclip-last [ [ first ] map ] dip append sequence= ." "t" }
+        { $unchecked-example
+            "USING: grouping ;"
+            "{ 1 2 3 4 } dup" "2 <clumps> unclip-last [ [ first ] map ] dip append sequence= ." "t"
+        }
     }
 }
 "A combinator built using clumps:"

core/classes/algebra/algebra-docs.factor

@@ -12,7 +12,6 @@ ARTICLE: "class-operations" "Class operations"
 { $subsection classes-intersect? }
 { $subsection min-class }
 "Low-level implementation detail:"
-{ $subsection class-types }
 { $subsection flatten-class }
 { $subsection flatten-builtin-class }
 { $subsection class-types }

core/classes/tuple/tuple-docs.factor

@@ -291,8 +291,7 @@ $nl
 { $subsection POSTPONE: SLOT: }
 "Protocol slots are used where the implementation of a superclass needs to assume that each subclass defines certain slots, however the slots of each subclass are potentially declared with different class specializers, thus preventing the slots from being defined in the superclass."
 $nl
-"For example, the " { $link growable } " mixin provides an implementation of the sequence protocol which wraps an underlying sequence, resizing it as necessary when elements are added beyond the length of the sequence. It assumes that the concrete mixin instances define two slots, " { $snippet "length" } " and " { $snippet "underlying" } ". These slots are defined as protocol slots:"
+"For example, the " { $link growable } " mixin provides an implementation of the sequence protocol which wraps an underlying sequence, resizing it as necessary when elements are added beyond the length of the sequence. It assumes that the concrete mixin instances define two slots, " { $snippet "length" } " and " { $snippet "underlying" } ". These slots are defined as protocol slots: " { $snippet "SLOT: length" } " and " { $snippet "SLOT: underlying" } ". "
-{ $snippet "SLOT: length" "SLOT: underlying" }
 "An alternate approach would be to define " { $link growable } " as a tuple class with these two slots, and have other classes subclass it as required. However, this rules out subclasses defining these slots with custom type declarations."
 $nl
 "For example, compare the definitions of the " { $link sbuf } " class,"
@@ -348,7 +347,7 @@ $nl
 { $list
     { { $snippet "\"predicate\"" } " - a quotation which tests if the top of the stack is an instance of this tuple class" }
     { { $snippet "\"slots\"" } " - a sequence of " { $link slot-spec } " instances" }
-    { { $snippet "\"tuple-layout\"" } " - an array with the tuple size and superclasses encoded in a format amneable to fast method dispatch" }
+    { { $snippet "\"layout\"" } " - an array with the tuple size and superclasses encoded in a format amneable to fast method dispatch" }
 } } ;
 
 HELP: define-tuple-predicate

core/combinators/combinators-docs.factor

@@ -434,7 +434,7 @@ HELP: cond>quot
 { $values { "assoc" "a sequence of pairs of quotations" } { "quot" quotation } }
 { $description  "Creates a quotation that when called, has the same effect as applying " { $link cond } " to " { $snippet "assoc" } "."
 $nl
-"the generated quotation is more efficient than the naive implementation of " { $link cond } ", though, since it expands into a series of conditionals, and no iteration through " { $snippet "assoc" } " has to be performed." }
+"The generated quotation is more efficient than the naive implementation of " { $link cond } ", though, since it expands into a series of conditionals, and no iteration through " { $snippet "assoc" } " has to be performed." }
 { $notes "This word is used behind the scenes to compile " { $link cond } " forms efficiently; it can also be called directly,  which is useful for meta-programming." } ;
 
 HELP: case>quot

core/generic/generic-docs.factor

@@ -9,7 +9,7 @@ ARTICLE: "method-order" "Method precedence"
 $nl
 "Here is an example:"
 { $code
-    "GENERIC: explain"
+    "GENERIC: explain ( object -- )"
     "M: object explain drop \"an object\" print ;"
     "M: number explain drop \"a number\" print ;"
     "M: sequence explain drop \"a sequence\" print ;"
@@ -17,7 +17,7 @@ $nl
 "The linear order is the following, from least-specific to most-specific:"
 { $code "{ object sequence number }" }
 "Neither " { $link number } " nor " { $link sequence } " are subclasses of each other, yet their intersection is the non-empty " { $link integer } " class. Calling " { $snippet "explain" } " with an integer on the stack will print " { $snippet "a number" } " because " { $link number } " precedes " { $link sequence } " in the class linearization order. If this was not the desired outcome, define a method on the intersection:"
-{ $code "M: integer explain drop \"a sequence\" print ;" }
+{ $code "M: integer explain drop \"an integer\" print ;" }
 "Now, the linear order is the following, from least-specific to most-specific:"
 { $code "{ object sequence number integer }" }
 "The " { $link order } " word can be useful to clarify method dispatch order:"

core/io/io-docs.factor

@@ -296,7 +296,7 @@ ARTICLE: "stdio-motivation" "Motivation for default streams"
     "    16 group"
     "] with-disposal"
 }
-"This code is robust however it is more complex than it needs to be since. This is where the default stream words come in; using them, the above can be rewritten as follows:"
+"This code is robust, however it is more complex than it needs to be. This is where the default stream words come in; using them, the above can be rewritten as follows:"
 { $code
     "USING: continuations kernel io io.files math.parser splitting ;"
     "\"data.txt\" utf8 <file-reader> ["
@@ -338,7 +338,6 @@ $nl
 { $subsection write1 }
 { $subsection write }
 "If the default output stream is a character stream (" { $link stream-element-type } " outputs " { $link +character+ } "), lines of text can be written:"
-{ $subsection readln }
 { $subsection print }
 { $subsection nl }
 { $subsection bl }

core/kernel/kernel-docs.factor

@@ -803,7 +803,7 @@ ARTICLE: "looping-combinators" "Looping combinators"
 { $subsection until }
 "To execute one iteration of a loop, use the following word:"
 { $subsection do }
-"This word is intended as a modifier. The normal " { $link while } " loop never executes the body if the predicate returns first on the first iteration. To ensure the body executes at least once, use " { $link do } ":"
+"This word is intended as a modifier. The normal " { $link while } " loop never executes the body if the predicate returns false on the first iteration. To ensure the body executes at least once, use " { $link do } ":"
 { $code
     "[ P ] [ Q ] do while"
 }

core/make/make-docs.factor

@@ -14,7 +14,7 @@ $nl
 $nl
 "On the other hand, using " { $link make } " instead of a single call to " { $link surround } " is overkill. The below headings summarize the most important cases where other idioms are more appropriate than " { $link make } "."
 { $heading "Make versus combinators" }
-"Sometimes, usages of " { $link make } " are better expressed with " { $link "sequences-combinators" } ". For example, instead of calling a combinator with a quotation which executes " { $link , } " exactly once on each iteration, oftena combinator encapsulating that specific idiom exists and can be used."
+"Sometimes, usages of " { $link make } " are better expressed with " { $link "sequences-combinators" } ". For example, instead of calling a combinator with a quotation which executes " { $link , } " exactly once on each iteration, often a combinator encapsulating that specific idiom exists and can be used."
 $nl
 "For example,"
 { $code "[ [ 42 * , ] each ] { } make" }

core/math/order/order-docs.factor

@@ -109,7 +109,6 @@ ARTICLE: "math.order" "Linear order protocol"
 { $subsection "order-specifiers" }
 "Utilities for comparing objects:"
 { $subsection after? }
-{ $subsection after? }
 { $subsection before? }
 { $subsection after=? }
 { $subsection before=? }

core/parser/parser-docs.factor

@@ -54,7 +54,7 @@ $nl
 ARTICLE: "parsing-words" "Parsing words"
 "The Factor parser follows a simple recursive-descent design. The parser reads successive tokens from the input; if the token identifies a number or an ordinary word, it is added to an accumulator vector. Otherwise if the token identifies a parsing word, the parsing word is executed immediately."
 $nl
-"Parsing words are defined using the a defining word:"
+"Parsing words are defined using the defining word:"
 { $subsection POSTPONE: SYNTAX: }
 "Parsing words have uppercase names by convention. Here is the simplest possible parsing word; it prints a greeting at parse time:"
 { $code "SYNTAX: HELLO \"Hello world\" print ;" }

core/words/words-docs.factor

@@ -276,6 +276,7 @@ HELP: parsing-word?
 HELP: define-declared
 { $values { "word" word } { "def" quotation } { "effect" effect } }
 { $description "Defines a word and declares its stack effect." }
+{ $notes "This word must be called from inside " { $link with-compilation-unit } "." }
 { $side-effects "word" } ;
 
 HELP: define-temp
@@ -311,4 +312,5 @@ HELP: make-inline
 HELP: define-inline
 { $values { "word" word } { "def" quotation } { "effect" effect } }
 { $description "Defines a word and makes it " { $link POSTPONE: inline } "." }
+{ $notes "This word must be called from inside " { $link with-compilation-unit } "." }
 { $side-effects "word" } ;