Tweaking docs, change stage2 to load less stuff

core/alien/alien-docs.factor

@@ -154,7 +154,11 @@ ARTICLE: "aliens" "Alien addresses"
 { $subsection expired? }
 "Anywhere that a " { $link alien } " instance is accepted, the " { $link f } " singleton may be passed in to denote a null pointer."
 $nl
-"Usually alien objects do not have to created and dereferenced directly; instead declaring C function parameters and return values as having a pointer type such as " { $snippet "void*" } " takes care of the details. See " { $link "c-types-specs" } "." ;
+"Usually alien objects do not have to created and dereferenced directly; instead declaring C function parameters and return values as having a pointer type such as " { $snippet "void*" } " takes care of the details."
+{ $subsection "syntax-aliens" }
+"When higher-level abstractions won't do:"
+{ $subsection "reading-writing-memory" }
+{ $see-also "c-data" "c-types-specs" } ;
 
 ARTICLE: "reading-writing-memory" "Reading and writing memory directly"
 "Numerical values can be read from memory addresses and converted to Factor objects using the various typed memory accessor words:"
@@ -293,6 +297,7 @@ $nl
 "C library interface words are found in the " { $vocab-link "alien" } " vocabulary."
 { $warning "C does not perform runtime type checking, automatic memory management or array bounds checks. Incorrect usage of C library functions can lead to crashes, data corruption, and security exploits." }
 { $subsection "loading-libs" }
+{ $subsection "aliens" }
 { $subsection "alien-invoke" }
 { $subsection "alien-callback" }
 { $subsection "c-data" }

core/alien/c-types/c-types-docs.factor

@@ -253,4 +253,4 @@ $nl
 "New C types can be defined:"
 { $subsection "c-structs" }
 { $subsection "c-unions" }
-{ $subsection "reading-writing-memory" } ;
+{ $see-also "aliens" } ;

core/classes/classes-docs.factor

@@ -1,5 +1,5 @@
 USING: help.markup help.syntax kernel kernel.private
-namespaces sequences words arrays layouts help effects math
+namespaces sequences words arrays layouts effects math
 layouts classes.private classes.union classes.mixin
 classes.predicate quotations ;
 IN: classes
@@ -32,6 +32,8 @@ $nl
 { $subsection class }
 "Testing if an object is an instance of a class:"
 { $subsection instance? }
+"Class predicates can be used to test instances directly:"
+{ $subsection "class-predicates" }
 "There is a universal class which all objects are an instance of, and an empty class with no instances:"
 { $subsection object }
 { $subsection null }

core/classes/tuple/tuple-docs.factor

@@ -1,9 +1,40 @@
 USING: generic help.markup help.syntax kernel
 classes.tuple.private classes slots quotations words arrays
 generic.standard sequences definitions compiler.units
-growable vectors sbufs ;
+growable vectors sbufs assocs math ;
 IN: classes.tuple
 
+ARTICLE: "slot-read-only-declaration" "Read-only slots"
+"By default, all slots are writable. If a slot is explicitly declared " { $link read-only } ", then no writer method is generated for the slot, and the only way to set it to a value other than its initial value is to construct an instance of the tuple with " { $link boa } ", passing the initial value for the read-only slot on the stack; the common idiom of calling " { $link new } " and then immediately filling in slot values with setter words will not work with read-only slots." ;
+
+ARTICLE: "slot-class-declaration" "Slot class declarations"
+"Class declaration is optional, and the default value is " { $link object } ", the class of all objects. If a more specific class is declared, then the object system maintains an invariant that the value of the slot must always be an instance of the class, even during construction. This invariant is enforced at a number of locations:"
+{ $list
+    { "Writer words (" { $link "accessors" } ") throw an error if the new value does not satisfy the class predicate." }
+    { "The " { $link new } " word fills in slots with their initial values; the (per-class) initial values are required to satisfy the class predicate." }
+    { "The " { $link boa } " word ensures that the values on the stack satisfy the class predicate." }
+    { { $link "mirrors" } " ensure that the value passed to " { $link set-at } " satisfies the class predicate." }
+    { "The " { $link slots>tuple } " and " { $link >tuple } " words ensure that the values in the sequence satisfy the correct class predicates." }
+    { { $link "tuple-redefinition" } " fills in new slots with initial values and ensures that changes to existing declarations result in incompatible values being replaced with the initial value of their respective slots." }
+}
+{ $subsection "slot-class-coercion" } ;
+
+ARTICLE: "slot-class-coercion" "Coercive slot declarations"
+"If the class of a slot is declared to be one of " { $link fixnum } " or " { $link float } ", then rather than testing values with the class predicate, writer words coerce values to the relevant type with " { $link >fixnum } " or " { $link >float } ". This may still result in error, but permits a wider range of values than a class predicate test. It also results in a possible loss of precision; for example, storing a large integer into a " { $link fixnum } " slot will silently overflow and discard high bits, and storing a ratio into a " { $link float } " slot may lose precision if the ratio is one which cannot be represented exactly with floating-point."
+$nl
+"This feature is mostly intended as an optimization for low-level code designed to avoid integer overflow, or where floating point precision is sufficient. Most code needs to work transparently with large integers, and thus hsould avoid the coercion behavior by using " { $link integer } " and " { $link real } " in place of " { $link fixnum } " and " { $link float } "." ;
+
+ARTICLE: "tuple-declarations" "Tuple slot declarations"
+"The slot specifier syntax of the " { $link POSTPONE: TUPLE: } " parsing word understands the following slot attributes:"
+{ $list
+    "class declaration: values must satisfy the class predicate"
+    { "whether a slot is read only or not (" { $link read-only } ")" }
+    { "an initial value (" { $link initial: } ")" }
+}
+{ $subsection "slot-read-only-declaration" }
+{ $subsection "slot-class-declaration" }
+{ $subsection "slot-initial-values" } ;
+
 ARTICLE: "parametrized-constructors" "Parameterized constructors"
 "A " { $emphasis "parametrized constructor" } " is a word which directly or indirectly calls " { $link new } " or " { $link boa } ", but instead of passing a literal class symbol, it takes the class symbol as an input from the stack."
 $nl
@@ -59,22 +90,30 @@ ARTICLE: "tuple-constructors" "Tuple constructors"
 { $subsection POSTPONE: C: }
 "By convention, construction logic is encapsulated in a word named after the tuple class surrounded in angle brackets; for example, the constructor word for a " { $snippet "point" } " class might be named " { $snippet "<point>" } "."
 $nl
+"Constructors play a part in enforcing the invariant that slot values must always match slot declarations. The " { $link new } " word fills in the tuple will initial values, and " { $link boa } " ensures that the values on the stack match the corresponding slot declarations. See " { $link "tuple-declarations" } "."
+$nl
 "All tuple construction should be done through constructor words, and construction primitives should be encapsulated and never called outside of the vocabulary where the class is defined, because this encourages looser coupling. For example, a constructor word could be changed to use memoization instead of always constructing a new instance, or it could be changed to construt a different class, without breaking callers."
 $nl
 "Examples of constructors:"
 { $code
-    "TUPLE: color red green blue alpha ;"
+    "TUPLE: color"
+    "{ red integer }"
+    "{ green integer }"
+    "{ blue integer }"
+    "{ alpha integer initial: 1 } ;"
     ""
     "! The following two are equivalent"
     "C: <rgba> rgba"
     ": <rgba> color boa ;"
     ""
     "! We can define constructors which call other constructors"
-    ": <rgb> f <rgba> ;"
+    ": <rgb> 1 <rgba> ;"
     ""
-    "! The following two are equivalent"
-    ": <color> color new ;"
-    ": <color> f f f f <rgba> ;"
+    "! The following two are equivalent; note the initial value"
+    ": <color> ( -- color ) color new ;"
+    ": <color> ( -- color ) 0 0 0 1 <rgba> ;"
+    "! Run-time error"
+    "\"not a number\" 2 3 4 color boa"
 }
 { $subsection "parametrized-constructors" } ;
 
@@ -226,19 +265,21 @@ ARTICLE: "tuple-examples" "Tuple examples"
 ARTICLE: "tuple-redefinition" "Tuple redefinition"
 "In the following, the " { $emphasis "direct slots" } " of a tuple class refers to the slot names specified in the " { $link POSTPONE: TUPLE: } " form defining the tuple class, and the " { $emphasis "effective slots" } " refers to the concatenation of the direct slots together with slots defined on superclasses."
 $nl
-"When a tuple class is redefined, all instances of the class, including subclasses, are updated. For each instance, the list of effective slots is compared with the previous list. If any slots were removed, the values are removed from the instance and are lost forever. If any slots were added, the instance gains these slots with an initial value of " { $link f } "."
+"When the " { $emphasis "effective slots" } " of a tuple class change, all instances of the class, including subclasses, are updated."
 $nl
-"There are three ways to change the list of effective slots of a class:"
+"There are three ways in which the list of effective slots may change:"
 { $list
     "Adding or removing direct slots of the class"
     "Adding or removing direct slots of a superclass of the class"
-    "Changing the inheritance hierarchy by redefining a class to have a different superclass"
+    "Changing the inheritance hierarchy by changing the superclass of a class"
+    "Declarations changing on existing slots"
 }
 "In all cases, the new effective slots are compared with the old effective slots, and each instance is updated as follows:"
 { $list
     "If any slots were removed, the values are removed from the instance and are lost forever."
-    { "If any slots were added, the instance gains these slots with an initial value of " { $link f } "." }
+    "If any slots were added, the instance gains these slots, all set to their initial values."
     "If any slots are permuted, their values in instances do not change; only the layout of the instance changes in memory."
+    "If the slot declaration of an existing slot changes, existing values are checked to see if they are still an instance of the required class. Any which are not are replaced by the initial value of that slot."
     "If the number or order of effective slots changes, any BOA constructors are recompiled."
 }
 "Note that if a slot is moved from a class to its superclass (or vice versa) in the same compilation unit, the value of the slot is preserved in existing instances, because tuple instance update always runs at the end of a compilation unit. However, if it is removed in one compilation unit and added in another, the value in existing instances is lost." ;
@@ -272,21 +313,18 @@ $nl
 } ;
 
 ARTICLE: "tuples" "Tuples"
-"Tuples are user-defined classes composed of named slots."
+"Tuples are user-defined classes composed of named slots. They are the central data type of Factor's object system."
 { $subsection "tuple-examples" }
 "A parsing word defines tuple classes:"
 { $subsection POSTPONE: TUPLE: }
-"For each tuple class, several words are defined. First, there is the class word, a class predicate, and accessor words for each slot."
+"For each tuple class, several words are defined, the class word, a class predicate, and accessor words for each slot."
 $nl
-"The class word is used for defining methods on the tuple class; it has the same name as the tuple class. The predicate is named " { $snippet { $emphasis "name" } "?" } ". Tuple slots are accessed via accessor words:"
+"The class word is used for defining methods on the tuple class; it has the same name as the tuple class. The predicate is named " { $snippet { $emphasis "name" } "?" } ". Initially, no specific words are defined for constructing new instances of the tuple. Constructors must be defined explicitly, and tuple slots are accessed via automatically-generated accessor words."
 { $subsection "accessors" }
-"Initially, no specific words are defined for constructing new instances of the tuple. Constructors must be defined explicitly:"
 { $subsection "tuple-constructors" }
-"Expressing relationships through the object system:"
 { $subsection "tuple-subclassing" }
-"Protocol slots:"
+{ $subsection "tuple-declarations" }
 { $subsection "protocol-slots" }
-"Introspection:"
 { $subsection "tuple-introspection" }
 "Tuple classes can be redefined; this updates existing instances:"
 { $subsection "tuple-redefinition" }
@@ -368,7 +406,7 @@ HELP: <tuple-boa> ( ... layout -- tuple )
 
 HELP: new
 { $values { "class" tuple-class } { "tuple" tuple } }
-{ $description "Creates a new instance of " { $snippet "class" } " with all slots initially set to " { $link f } "." }
+{ $description "Creates a new instance of " { $snippet "class" } " with all slots set to their initial values (see" { $link "tuple-declarations" } ")." }
 { $examples
     { $example
         "USING: kernel prettyprint ;"
@@ -404,4 +442,5 @@ HELP: construct
 HELP: boa
 { $values { "..." "slot values" } { "class" tuple-class } { "tuple" tuple } }
 { $description "Creates a new instance of " { $snippet "class" } " and fill in the slots from the stack, with the top-most stack element being stored in the right-most slot." }
-{ $notes "The name " { $snippet "boa" } " is shorthand for ``by order of arguments'', and ``BOA constructor'' is a pun on ``boa constrictor''." } ;
+{ $notes "The name " { $snippet "boa" } " is shorthand for ``by order of arguments'', and ``BOA constructor'' is a pun on ``boa constrictor''." }
+{ $errors "Throws an error if the slot values do not match class declarations on slots (see" { $link "tuple-declarations" } ")." } ;

core/compiler/compiler-docs.factor

@@ -26,7 +26,9 @@ ARTICLE: "compiler" "Optimizing compiler"
 }
 "The optimizing compiler only compiles words which have a static stack effect. This means that methods defined on fundamental generic words such as " { $link nth } " should have a static stack effect; for otherwise, most of the system would be compiled with the non-optimizing compiler. See " { $link "inference" } " and " { $link "cookbook-pitfalls" } "."
 { $subsection "compiler-usage" }
-{ $subsection "compiler-errors" } ;
+{ $subsection "compiler-errors" }
+{ $subsection "optimizer" }
+{ $subsection "generator" } ;
 
 ABOUT: "compiler"
 

core/io/files/files-docs.factor

@@ -121,7 +121,8 @@ ARTICLE: "io.files" "Basic file operations"
 { $subsection "file-streams" }
 { $subsection "fs-meta" }
 { $subsection "directories" }
-{ $subsection "delete-move-copy" } ;
+{ $subsection "delete-move-copy" }
+{ $subsection "symbolic-links" } ;
 
 ABOUT: "io.files"
 

core/refs/refs-docs.factor

@@ -4,7 +4,7 @@ USING: help.markup help.syntax kernel ;
 IN: refs
 
 ARTICLE: "refs" "References to assoc entries"
-"A " { $emphasis "reference" } " is an object encapsulating an assoc and a key; the reference then refers to either the key itself, or the value associated to the key. References can be read, written, and deleted."
+"A " { $emphasis "reference" } " is an object encapsulating an assoc and a key; the reference then refers to either the key itself, or the value associated to the key. References can be read, written, and deleted. References are defined in the " { $vocab-link "refs" } " vocabulary."
 { $subsection get-ref }
 { $subsection set-ref }
 { $subsection delete-ref }

core/slots/slots-docs.factor

@@ -1,13 +1,14 @@
 USING: help.markup help.syntax generic kernel.private parser
 words kernel quotations namespaces sequences words arrays
-effects generic.standard classes.tuple classes.builtin
-slots.private classes strings math ;
+effects generic.standard classes.builtin
+slots.private classes strings math assocs byte-arrays alien
+math ;
 IN: slots
 
 ARTICLE: "accessors" "Slot accessors"
 "For every tuple slot, a " { $emphasis "reader" } " method is defined in the " { $vocab-link "accessors" } " vocabulary. The reader is named " { $snippet { $emphasis "slot" } ">>" } " and given a tuple, pushes the slot value on the stack."
 $nl
-"Writable slots - that is, those not attributed " { $link read-only } " - also have a " { $emphasis "writer" } ". The writer is named " { $snippet "(>>" { $emphasis "slot" } ")" } " and stores a value into a slot. It has stack effect " { $snippet "( value object -- )" } ". If the slot is specialized to a specific class, the writer checks that the value being written into the slot is an instance of that class first."
+"Writable slots - that is, those not attributed " { $link read-only } " - also have a " { $emphasis "writer" } ". The writer is named " { $snippet "(>>" { $emphasis "slot" } ")" } " and stores a value into a slot. It has stack effect " { $snippet "( value object -- )" } ". If the slot is specialized to a specific class, the writer checks that the value being written into the slot is an instance of that class first. See " { $link "tuple-declarations" } " for details."
 $nl
 "In addition, two utility words are defined for each writable slot."
 $nl
@@ -61,6 +62,26 @@ $nl
 }
 { $see-also "slots" "mirrors" } ;
 
+ARTICLE: "slot-initial-values" "Initial values of slots"
+"An initial value for a slot can be specified with the " { $link initial: } " slot declaration attribute. For certain classes, the initial value is optional; in these cases, it does not need to be specified. For others, it is required. Initial values can be used independently of class declaration, but if specified, the value must satisfy the class predicate."
+$nl
+"The following classes have default initial values:"
+{ $table
+    { { { $link f } } { $link f } }
+    { { { $link fixnum } } { $snippet "0" } }
+    { { { $link float } } { $snippet "0.0" } }
+    { { { $link string } } { $snippet "\"\"" } }
+    { { { $link byte-array } } { $snippet "B{ }" } }
+    { { { $link simple-alien } } { $snippet "BAD-ALIEN" } }
+}
+"All other classes are handled with one of two cases:"
+{ $list
+    { "If the class is a union or mixin class which " { $emphasis "contains" } " one of the above known classes, then the initial value of the class is that of the known class, with preference given to classes earlier in the list. For example, if the slot is declared " { $link object } " (this is the default), the initial value is " { $link f } ". Similarly for " { $link sequence } " and " { $link assoc } "." }
+    { "Otherwise, a " { $link no-initial-value } " error is thrown. In this case, an initial value must be specified explicitly using " { $link initial: } "." }
+}
+"A word can be used to check if a class has an initial value or not:"
+{ $subsection initial-value } ;
+
 ARTICLE: "slots" "Slots"
 "A " { $emphasis "slot" } " is a component of an object which can store a value."
 $nl

core/syntax/syntax-docs.factor

@@ -536,7 +536,7 @@ $nl
     { { $snippet "{ \"name\" attributes... }" } " - a slot which can hold any object, with optional attributes" }
     { { $snippet "{ \"name\" class attributes... }" } " - a slot specialized to a specific class, with optional attributes" }
 }
-"Slot attributes are lists of slot attribute specifiers followed by values; a slot attribute specifier is one of " { $link initial: } " or " { $link read-only } "." }
+"Slot attributes are lists of slot attribute specifiers followed by values; a slot attribute specifier is one of " { $link initial: } " or " { $link read-only } ". See " { $link "tuple-declarations" } " for details." }
 { $examples
     "A simple tuple class:"
     { $code "TUPLE: color red green blue ;" }

extra/bit-arrays/bit-arrays-docs.factor

@@ -2,9 +2,6 @@ USING: arrays help.markup help.syntax kernel
 kernel.private math prettyprint strings vectors sbufs ;
 IN: bit-arrays
 
-ARTICLE: "syntax-bit-arrays" "Bit array syntax"
-"Bit arrays are documented in " { $link "bit-arrays" } "." ;
-
 ARTICLE: "bit-arrays" "Bit arrays"
 "Bit array are a fixed-size mutable sequences (" { $link "sequence-protocol" } ") whose elements are either " { $link t } " or " { $link f } ". Each element only uses one bit of storage, hence the name. The literal syntax is covered in " { $link "syntax-bit-arrays" } "."
 $nl

extra/bootstrap/unicode/unicode.factor

@@ -1,12 +1,4 @@
-USING: strings.parser kernel namespaces ;
-
-USE: unicode.breaks
-USE: unicode.case
-USE: unicode.categories
-USE: unicode.collation
-USE: unicode.data
-USE: unicode.normalize
-USE: unicode.script
+USING: strings.parser kernel namespaces unicode.data ;
 
 [ name>char [ "Invalid character" throw ] unless* ]
 name>char-hook set-global

extra/cocoa/cocoa-docs.factor

@@ -28,5 +28,21 @@ $nl
 { $subsection send }
 { $subsection super-send } ;
 
+ARTICLE: "cocoa" "Cocoa bridge"
+"The " { $vocab-link "cocoa" } " vocabulary implements a Factor-Cocoa bridge for Mac OS X (GNUstep is not supported)."
+$nl
+"The lowest layer uses the " { $link "alien" } " to define bindings for the various functions in Apple's Objective-C runtime. This is defined in the " { $vocab-link "cocoa.runtime" } " vocabulary."
+$nl
+"On top of this, a dynamic message send facility is built:"
+{ $subsection "objc-calling" }
+{ $subsection "objc-subclassing" }
+"A utility library is built to faciliate the development of Cocoa applications in Factor:"
+{ $subsection "cocoa-types" }
+{ $subsection "cocoa-application-utils" }
+{ $subsection "cocoa-dialogs" }
+{ $subsection "cocoa-pasteboard-utils" }
+{ $subsection "cocoa-view-utils" }
+{ $subsection "cocoa-window-utils" } ;
+
 IN: cocoa
-ABOUT: "objc-calling"
+ABOUT: "cocoa"

extra/concurrency/count-downs/count-downs-docs.factor

@@ -19,6 +19,7 @@ ARTICLE: "concurrency.count-downs" "Count-down latches"
 "The " { $vocab-link "concurrency.count-downs" } " vocabulary implements the " { $emphasis "count-down latch" } " data type, whichis a wrapper for a non-negative integer value which tends towards zero. A thread can either decrement the value, or wait for it to become zero."
 { $subsection <count-down> }
 { $subsection count-down }
-{ $subsection await } ;
+{ $subsection await }
+"The vocabulary was modelled after a similar feature in Java's " { $snippet "java.util.concurrent" } " library." ;
 
 ABOUT: "concurrency.count-downs"

extra/concurrency/distributed/distributed-docs.factor

@@ -9,7 +9,7 @@ HELP: start-node
 { $description "Starts a node server for receiving messages from remote Factor instances." } ;
 
 ARTICLE: "concurrency.distributed" "Distributed message passing"
-"The " { $vocab-link "concurrency.distributed" } " implements transparent distributed message passing."
+"The " { $vocab-link "concurrency.distributed" } " implements transparent distributed message passing, inspired by Erlang and Termite."
 { $subsection start-node }
 "Instances of " { $link thread } " can be sent to remote processes, at which point they are converted to objects holding the thread ID and the current node's host name:"
 { $subsection remote-process }

extra/concurrency/exchangers/exchangers-docs.factor

@@ -17,6 +17,8 @@ ARTICLE: "concurrency.exchangers" "Object exchange points"
 { $subsection exchanger }
 { $subsection <exchanger> }
 { $subsection exchange }
-"One use-case is two threads, where one thread reads data into a buffer and another thread processes the data. The reader thread can begin by reading the data, then passing the buffer through an exchanger, then recursing. The processing thread can begin by creating an empty buffer, and exchanging it through the exchanger. It then processes the result and recurses." ;
+"One use-case is two threads, where one thread reads data into a buffer and another thread processes the data. The reader thread can begin by reading the data, then passing the buffer through an exchanger, then recursing. The processing thread can begin by creating an empty buffer, and exchanging it through the exchanger. It then processes the result and recurses."
+$nl
+"The vocabulary was modelled after a similar feature in Java's " { $snippet "java.util.concurrent" } " library." ;
 
 ABOUT: "concurrency.exchangers"

extra/delegate/delegate-docs.factor

@@ -28,13 +28,22 @@ HELP: group-words
 { $values { "group" "a group" } { "words" "an array of words" } }
 { $description "Given a protocol or tuple class, this returns the corresponding generic words that this group contains." } ;
 
-ARTICLE: { "delegate" "intro" } "Delegation module"
-"This vocabulary defines methods for consultation and mimicry, independent of the current Factor object system; it is a replacement for Factor's builtin delegation system. Fundamental to the concept of generic word groups, which can be specific protocols, generic words or tuple slot accessors. Fundamentally, a group is a word which has a method for " { $link group-words } ". One type of group is a tuple, which consists of the slot words. To define a group as a set of words, use"
+ARTICLE: { "delegate" "intro" } "Delegation"
+"The " { $vocab-link "delegate" } " vocabulary implements run-time consultation for method dispatch."
+$nl
+"Fundamental to the concept of " { $emphasis "protocols" } ", which are groups of tuple slot accessors, or groups of arbtirary generic words."
+$nl
+"This allows an object to implement a certain protocol by passing the method calls to another object."
+$nl
+"Unlike " { $link "tuple-subclassing" } ", which expresses " { $emphasis "is-a" } " relationships by statically including the methods and slots of the superclass in all subclasses, consultation forwards generic word calls to another distinct object."
+$nl
+"Fundamentally, a protocol is a word which has a method for " { $link group-words } ". One type of protocol is a tuple, which consists of the slot accessors. To define a protocol as a set of words, use"
 { $subsection POSTPONE: PROTOCOL: }
 { $subsection define-protocol }
-"One method of object extension which this vocabulary defines is consultation. This is slightly different from the current Factor concept of delegation, in that instead of delegating for all generic words not implemented, only generic words included in a specific group are consulted. Additionally, instead of using a single hard-coded delegate slot, you can specify any quotation to execute in order to retrieve who to consult. The literal syntax and defining word are"
+"The literal syntax and defining word are:"
 { $subsection POSTPONE: CONSULT: }
-{ $subsection define-consult } ;
+{ $subsection define-consult }
+"The " { $vocab-link "delegate.protocols" } " vocabulary defines formal protocols for the various informal protocols used in the Factor core, such as " { $link "sequence-protocol" } ", " { $link "assocs-protocol" } " or " { $link "stream-protocol" } ;
 
 IN: delegate
 ABOUT: { "delegate" "intro" }

extra/hash2/hash2-docs.factor

@@ -1,7 +1,7 @@
 USING: help.syntax help.markup ;
 IN: hash2
 
-ARTICLE: { "hash2" "intro" } "hash2 Vocabulary"
+ARTICLE: { "hash2" "intro" } "Hash2"
 "The hash2 vocabulary specifies a simple minimal datastructure for hash tables with two integers as keys. These hash tables are fixed size and do not conform to the associative mapping protocol. Words used in creating and manipulating these hash tables include:"
 { $subsection <hash2> }
 { $subsection hash2 }

extra/help/handbook/handbook.factor

@@ -1,8 +1,8 @@
 USING: help help.markup help.syntax help.definitions help.topics
 namespaces words sequences classes assocs vocabs kernel arrays
 prettyprint.backend kernel.private io generic math system
-strings sbufs vectors byte-arrays bit-arrays float-arrays
-quotations io.streams.byte-array io.encodings.string
+strings sbufs vectors byte-arrays
+quotations io.streams.byte-array
 classes.builtin parser lexer classes.predicate classes.union
 classes.intersection classes.singleton classes.tuple ;
 IN: help.handbook
@@ -72,38 +72,6 @@ ARTICLE: "evaluator" "Evaluation semantics"
 "If the last action performed is the execution of a word, the current quotation is not saved on the call stack; this is known as " { $snippet "tail-recursion" } " and allows iterative algorithms to execute without incurring unbounded call stack usage."
 { $see-also "compiler" } ;
 
-USING: concurrency.combinators
-concurrency.messaging
-concurrency.promises
-concurrency.futures
-concurrency.locks
-concurrency.semaphores
-concurrency.count-downs
-concurrency.exchangers
-concurrency.flags ;
-
-ARTICLE: "concurrency" "Concurrency"
-"Factor supports a variety of concurrency abstractions, however they are mostly used to multiplex input/output operations since the thread scheduling is co-operative and only one CPU is used at a time."
-$nl
-"Factor's concurrency support was insipired by Erlang, Termite, Scheme48 and Java's " { $snippet "java.util.concurrent" } " library."
-$nl
-"The basic building blocks:"
-{ $subsection "threads" }
-{ $subsection "alarms" }
-"High-level abstractions:"
-{ $subsection "concurrency.combinators" }
-{ $subsection "concurrency.promises" }
-{ $subsection "concurrency.futures" }
-{ $subsection "concurrency.mailboxes" }
-{ $subsection "concurrency.messaging" }
-"Shared-state abstractions:"
-{ $subsection "concurrency.locks" }
-{ $subsection "concurrency.semaphores" }
-{ $subsection "concurrency.count-downs" }
-{ $subsection "concurrency.exchangers" }
-{ $subsection "concurrency.flags" }
-"Other concurrency abstractions include " { $vocab-link "concurrency.distributed" } " and " { $vocab-link "channels" } "." ;
-
 ARTICLE: "objects" "Objects"
 "An " { $emphasis "object" } " is any datum which may be identified. All values are objects in Factor. Each object carries type information, and types are checked at runtime; Factor is dynamically typed."
 { $subsection "equality" }
@@ -131,7 +99,9 @@ ARTICLE: "numbers" "Numbers"
 "Advanced features:"
 { $subsection "math-vectors" }
 { $subsection "math-intervals" }
-{ $subsection "math-bitfields" } ;
+{ $subsection "math-bitfields" }
+"Implementation:"
+{ $subsection "math.libm" } ;
 
 USE: io.buffers
 
@@ -143,19 +113,16 @@ ARTICLE: "collections" "Collections"
 { $subsection "quotations" }
 "Fixed-length specialized sequences:"
 { $subsection "strings" }
-{ $subsection "bit-arrays" }
 { $subsection "byte-arrays" }
-{ $subsection "float-arrays" }
-"Resizable sequence:"
+"Resizable sequences:"
 { $subsection "vectors" }
-"Resizable specialized sequences:"
+{ $subsection "byte-vectors" }
 { $subsection "sbufs" }
-{ $vocab-subsection "Bit vectors" "bit-vectors" }
-{ $vocab-subsection "Byte vectors" "byte-vectors" }
-{ $vocab-subsection "Float vectors" "float-vectors" }
+{ $subsection "growable" }
 { $heading "Associative mappings" }
 { $subsection "assocs" }
 { $subsection "namespaces" }
+{ $subsection "refs" }
 "Implementations:"
 { $subsection "hashtables" }
 { $subsection "alists" }
@@ -172,8 +139,7 @@ ARTICLE: "collections" "Collections"
 { $subsection "buffers" }
 "There are many other collections in " { $snippet "extra/" } ", such as " { $vocab-link "disjoint-set" } ", " { $vocab-link "persistent-vectors" } ", and " { $vocab-link "tuple-arrays" } "." ;
 
-USING: io.sockets io.sockets.secure io.launcher io.mmap io.monitors
-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 ;
 
 ARTICLE: "encodings-introduction" "An introduction to encodings"
 "In order to express text in terms of binary, some sort of encoding has to be used. In a modern context, this is understood as a two-way mapping between Unicode code points (characters) and some amount of binary. Since English isn't the only language in the world, ASCII is not sufficient as a mapping from binary to Unicode; it can't even express em-dashes or curly quotes. Unicode was designed as a universal character set that could potentially represent everything." $nl
@@ -194,6 +160,10 @@ $nl
 ARTICLE: "io" "Input and output"
 { $heading "Streams" }
 { $subsection "streams" }
+{ $subsection "io.files" }
+{ $heading "Encodings" }
+{ $subsection "encodings-introduction" }
+{ $subsection "io.encodings" }
 "Wrapper streams:"
 { $subsection "io.streams.duplex" }
 { $subsection "io.streams.plain" }
@@ -202,21 +172,10 @@ ARTICLE: "io" "Input and output"
 "Utilities:"
 { $subsection "stream-binary" }
 { $subsection "styles" }
-{ $heading "Encodings" }
-{ $subsection "encodings-introduction" }
-{ $subsection "io.encodings" }
-{ $subsection "io.encodings.string" }
-{ $heading "Files" }
-{ $subsection "io.files" }
-{ $subsection "io.mmap" }
-{ $subsection "io.monitors" }
-{ $heading "Communications" }
-{ $subsection "network-streams" }
-{ $subsection "io.launcher" }
-{ $subsection "io.pipes" }
-{ $heading "Other features" }
-{ $subsection "io.timeouts" }
 { $subsection "checksums" }
+"Implementation:"
+{ $subsection "io.streams.c" }
+{ $subsection "io.ports" }
 { $see-also "destructors" } ;
 
 ARTICLE: "tools" "Developer tools"
@@ -226,6 +185,8 @@ ARTICLE: "tools" "Developer tools"
 { $subsection "listener" }
 { $subsection "tools.crossref" }
 { $subsection "inspector" }
+{ $subsection "tools.completion" }
+{ $subsection "summary" }
 "Debugging tools:"
 { $subsection "tools.annotations" }
 { $subsection "tools.test" }
@@ -268,50 +229,54 @@ ARTICLE: "program-org" "Program organization"
 { $subsection "definitions" }
 { $subsection "vocabularies" }
 { $subsection "parser" }
-{ $subsection "vocabs.loader" } ;
+{ $subsection "vocabs.loader" }
+{ $subsection "source-files" } ;
 
 USING: help.cookbook help.tutorial ;
 
-ARTICLE: "handbook" "Factor documentation"
-"Welcome to Factor."
-{ $heading "Starting points" }
-{ $subsection "cookbook" }
-{ $subsection "first-program" }
-{ $subsection "vocab-index" }
-{ $heading "Language reference" }
+ARTICLE: "handbook-language-reference" "Language reference"
 { $subsection "conventions" }
 { $subsection "syntax" }
 { $subsection "dataflow" }
 { $subsection "objects" }
 { $subsection "program-org" }
-{ $heading "Library reference" }
 { $subsection "numbers" }
 { $subsection "collections" }
-{ $subsection "models" }
-{ $subsection "io" }
-{ $subsection "concurrency" }
-{ $subsection "system" }
-{ $subsection "alien" }
-{ $heading "Environment reference" }
-{ $subsection "cli" }
-{ $subsection "images" }
+{ $subsection "io" } ;
+
+ARTICLE: "handbook-environment-reference" "Environment reference"
 { $subsection "prettyprint" }
 { $subsection "tools" }
+{ $subsection "cli" }
 { $subsection "help" }
 { $subsection "inference" }
 { $subsection "compiler" }
-{ $subsection "layouts" }
-{ $heading "User interface" }
-{ $subsection "ui" }
-{ $subsection "ui-tools" }
-{ $heading "Index" }
+{ $subsection "system" }
+{ $subsection "images" }
+{ $subsection "alien" }
+{ $subsection "init" }
+{ $subsection "layouts" } ;
+
+ARTICLE: "handbook-library-reference" "Library reference"
+"This index only includes articles from loaded vocabularies. To explore more vocabularies, see " { $link "vocab-index" } "."
+{ $index [ "handbook" orphan-articles remove ] } ;
+
+ARTICLE: "handbook" "Factor documentation"
+"Welcome to Factor."
+$nl
+"Explore the code base:"
+{ $subsection "vocab-index" }
+"Learn the language:"
+{ $subsection "cookbook" }
+{ $subsection "first-program" }
+{ $subsection "handbook-language-reference" }
+{ $subsection "handbook-environment-reference" }
+{ $subsection "handbook-library-reference" }
+"The below indices only include articles from loaded vocabularies. To explore more vocabularies, see " { $link "vocab-index" } "."
+{ $subsection "article-index" }
 { $subsection "primitive-index" }
 { $subsection "error-index" }
 { $subsection "type-index" }
 { $subsection "class-index" } ;
 
-{ <array> <string> <sbuf> <vector> <byte-array> <bit-array> <float-array> }
-related-words
-
-{ >array >quotation >string >sbuf >vector >byte-array >bit-array >float-array }
-related-words
+ABOUT: "handbook"

extra/help/help-docs.factor

@@ -84,6 +84,7 @@ $nl
     { "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" }
 }
 { $subsection "element-types" }
+{ $subsection "printing-elements" }
 "Related words can be cross-referenced:"
 { $subsection related-words }
 { $see-also "help.lint" } ;

extra/help/help.factor

@@ -31,6 +31,10 @@ M: predicate word-help* drop \ $predicate ;
     articles get keys
     all-words [ word-help ] filter append ;
 
+: orphan-articles ( -- seq )
+    articles get keys
+    [ article-parent not ] filter ;
+
 : xref-help ( -- )
     all-articles [ xref-article ] each ;
 
@@ -109,7 +113,7 @@ M: word set-article-parent swap "help-parent" set-word-prop ;
 
 : $index ( element -- )
     first call dup empty?
-    [ drop ] [ [ ($index) ] ($block) ] if ;
+    [ drop ] [ ($index) ] if ;
 
 : $about ( element -- )
     first vocab-help [ 1array $subsection ] when* ;

extra/io/sockets/sockets-docs.factor

@@ -28,7 +28,8 @@ $nl
     { { $link inet6 } " - a TCP/IP connection to an IPv6 address and port number; no name lookup is performed" }
 }
 "The " { $vocab-link "io.servers.connection" } " library defines high-level wrappers around " { $link <server> } " which makes it easy to listen for IPv4, IPv6 and secure socket connections simultaneously, perform logging, and optionally only allow connections from the loopback interface."
-{ $see-also "io.sockets.secure" } ;
+$nl
+"The " { $vocab-link "io.sockets.secure" } " vocabulary implements secure, encrypted sockets via SSL and TLS." ;
 
 ARTICLE: "network-packet" "Packet-oriented networking"
 "A packet-oriented socket can be opened with this word:"

extra/lcs/lcs-docs.factor

@@ -22,7 +22,7 @@ HELP: delete
 HELP: insert
 { $class-description "Represents an action in an edit script where an item is added, going from the initial sequence to the final sequence. This has one slot, called item, containing the thing which is inserted" } ;
 
-ARTICLE: "lcs" "LCS, Diffing and Distance"
+ARTICLE: "lcs" "LCS, diffing and distance"
 "This vocabulary provides words for three apparently unrelated but in fact very similar problems: finding a longest common subsequence between two sequences, getting a minimal edit script (diff) between two sequences, and calculating the Levenshtein distance between two sequences. The implementations of these algorithms are very closely related, and all running times are O(nm), where n and m are the lengths of the input sequences."
 { $subsection lcs }
 { $subsection diff }

extra/logging/logging-docs.factor

@@ -115,9 +115,9 @@ ARTICLE: "logging" "Logging framework"
 { $subsection "logging.levels" }
 { $subsection "logging.messages" }
 { $subsection "logging.rotation" }
-{ $vocab-subsection "Log file parser" "logging.parser" }
-{ $vocab-subsection "Log analysis" "logging.analysis" }
-{ $vocab-subsection "Automated log analysis" "logging.insomniac" }
+{ $subsection "logging.parser" }
+{ $subsection "logging.analysis" }
+{ $subsection "logging.insomniac" }
 { $subsection "logging.server" } ;
 
 ABOUT: "logging"

extra/logging/logging.factor

@@ -117,3 +117,9 @@ PRIVATE>
     CREATE-WORD dup scan-word
     '[ 1array stack>message , , log-message ]
     (( message -- )) define-declared ; parsing
+
+USE: vocabs.loader
+
+"logging.parser" require
+"logging.analysis" require
+"logging.insomniac" require

extra/opengl/gl/gl-docs.factor

@@ -3,7 +3,7 @@ USING: help.syntax help.markup ;
 
 IN: opengl.gl
 
-ARTICLE: "opengl-low-level" "OpenGL Library (low level)"
+ARTICLE: "opengl-low-level" "OpenGL binding"
   { $subsection "opengl-specifying-vertices" }
   { $subsection "opengl-geometric-primitives" }
   { $subsection "opengl-modeling-transformations" } ;

extra/opengl/opengl-docs.factor

@@ -123,9 +123,12 @@ HELP: with-translation
 { $values { "loc" "a pair of integers" } { "quot" quotation } }
 { $description "Calls the quotation with a translation by " { $snippet "loc" } " pixels applied to the current " { $link GL_MODELVIEW } " matrix, restoring the matrix when the quotation is done." } ;
 
+
 ARTICLE: "gl-utilities" "OpenGL utility words"
-"In addition to the full OpenGL API, the " { $vocab-link "opengl" } " vocabulary includes some utility words to give OpenGL a more Factor-like feel."
+"The " { $vocab-link "opengl" } " vocabulary implements some utility words to give OpenGL a more Factor-like feel."
 $nl
+"The " { $vocab-link "opengl.gl" } " and " { $vocab-link "opengl.glu" } " vocabularies have the actual OpenGL bindings."
+{ $subsection "opengl-low-level" }
 "Wrappers:"
 { $subsection gl-color }
 { $subsection gl-vertex }

extra/unicode/collation/collation-docs.factor

@@ -3,7 +3,7 @@ IN: unicode.collation
 
 ABOUT: "unicode.collation"
 
-ARTICLE: "unicode.collation" "Unicode collation algorithm"
+ARTICLE: "unicode.collation" "Unicode collation algorithm (UCA)"
 "The Unicode Collation Algorithm (UTS #10) forms a reasonable way to sort strings when accouting for all of the characters in Unicode. At the moment, only the default Unicode collation element table (DUCET) is used, but a more accurate collation would take locale into account. The following words are defined:"
 { $subsection sort-strings }
 { $subsection collation-key }