Merge branch 'doc-fixes' of git://github.com/keitahaga/factor

basis/concurrency/locks/locks-docs.factor

@@ -60,7 +60,7 @@ ARTICLE: "concurrency.locks.rw" "Read-write locks"
 $nl
 "While this can be achieved with a simple " { $link "concurrency.locks.mutex" } ", performance will suffer, since in fact multiple threads can view the structure at the same time; serialization must only be enforced for writes."
 $nl
-"Read/write locks allow any number of threads to hold the read lock simulateneously, however attempting to acquire a write lock blocks until all other threads release read locks and write locks."
+"Read/write locks allow any number of threads to hold the read lock simultaneously, however attempting to acquire a write lock blocks until all other threads release read locks and write locks."
 $nl
 "Read/write locks are reentrant. A thread holding a write lock may acquire a read lock or a write lock without blocking. However a thread holding a read lock may not acquire a write lock recursively since that could break invariants assumed by the code executing with the read lock held."
 { $subsections

basis/db/db-docs.factor

@@ -271,24 +271,21 @@ ARTICLE: "db-lowlevel-tutorial" "Low-level database tutorial"
 { $subsections sql-query }
 "Here's an example usage where we'll make a book table, insert some objects, and query them." $nl
 "First, let's set up a custom combinator for using our database. See " { $link "db-custom-database-combinators" } " for more details."
-{ $code """
-USING: db.sqlite db io.files io.files.temp ;
+{ $code """USING: db.sqlite db io.files io.files.temp ;
 : with-book-db ( quot -- )
-    "book.db" temp-file <sqlite-db> swap with-db ; inline" }
+    "book.db" temp-file <sqlite-db> swap with-db ; inline""" }
 "Now let's create the table manually:"
-{ $code " "create table books
+{ $code """"create table books
     (id integer primary key, title text, author text, date_published timestamp,
      edition integer, cover_price double, condition text)"
     [ sql-command ] with-book-db""" }
 "Time to insert some books:"
-{ $code """
-"insert into books
+{ $code """"insert into books
     (title, author, date_published, edition, cover_price, condition)
     values('Factor for Sheeple', 'Mister Stacky Pants', date('now'), 1, 13.37, 'mint')"
 [ sql-command ] with-book-db""" }
 "Now let's select the book:"
-{ $code """
-"select id, title, cover_price from books;" [ sql-query ] with-book-db""" }
+{ $code """"select id, title, cover_price from books;" [ sql-query ] with-book-db""" }
 "Notice that the result of this query is a Factor array containing the database rows as arrays of strings. We would have to convert the " { $snippet "cover_price" } " from a string to a number in order to use it in a calculation." $nl
 "In conclusion, this method of accessing a database is supported, but it is fairly low-level and generally specific to a single database. The " { $vocab-link "db.tuples" } " vocabulary is a good alternative to writing SQL by hand." ;
 
@@ -298,10 +295,9 @@ ARTICLE: "db-custom-database-combinators" "Custom database combinators"
 "Make a " { $snippet "with-" } " combinator to open and close a database so that resources are not leaked." $nl
 
 "SQLite example combinator:"
-{ $code """
-USING: db.sqlite db io.files io.files.temp ;
+{ $code """USING: db.sqlite db io.files io.files.temp ;
 : with-sqlite-db ( quot -- )
-    "my-database.db" temp-file <sqlite-db> swap with-db ; inline""" } 
+    "my-database.db" temp-file <sqlite-db> swap with-db ; inline""" }
 
 "PostgreSQL example combinator:"
 { $code """USING: db.postgresql db ;

basis/eval/eval-docs.factor

@@ -50,7 +50,7 @@ $nl
 { $code
     """USING: eval listener vocabs.parser ;
 [
-    "cad-objects" use-vocab
+    "cad.objects" use-vocab
     (( -- seq )) (eval)
 ] with-interactive-vocabs"""
 }

basis/help/handbook/handbook.factor

@@ -45,7 +45,7 @@ $nl
 $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 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."
+"A vocabulary name ending in " { $snippet ".private" } " contains words which are either implementation details, unsafe, or both. For example, the " { $snippet "sequences.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

basis/help/help-docs.factor

@@ -476,7 +476,8 @@ HELP: HELP:
 { $description "Defines documentation for a word." }
 { $examples
     { $code
-        ": foo 2 + ;"
+        "USING: help help.markup help.syntax math syntax ;"
+        ": foo ( m -- n ) 2 + ;"
         "HELP: foo"
         "{ $values { \"m\" \"an integer\" } { \"n\" \"an integer\" } }"
         "{ $description \"Increments a value by 2.\" } ;"

basis/hints/hints-docs.factor

@@ -24,20 +24,26 @@ HELP: HINTS:
 { $description "Defines specialization hints for a word or a method."
 $nl
 "Each sequence in the list will cause a specialized version of the word to be compiled. Classes are tested for using their predicate, and literals are tested using " { $link eq? } "." }
-{ $examples "The " { $link append } " word has a specializer for the very common case where two strings or two arrays are appended:"
-{ $code "HINTS: append { string string } { array array } ;" }
-"Specializers can also be defined on methods:"
-{ $code
-    "GENERIC: count-occurrences ( elt obj -- n )"
-    ""
-    "M: sequence count-occurrences [ = ] with count ;"
-    ""
-    "M: assoc count-occurrences"
-    "    swap [ = nip ] curry assoc-filter assoc-size ;"
-    ""
-    "HINTS: M\ sequence count-occurrences { object array } ;"
-    "HINTS: M\ assoc count-occurrences { object hashtable } ;"
-}
+{ $examples
+    "The " { $link append } " word has a specializer for the very common case where two strings or two arrays are appended:"
+    { $code
+        "USING: arrays hints sequences strings syntax ;"
+        "HINTS: append { string string } { array array } ;"
+    }
+    "Specializers can also be defined on methods:"
+    { $code
+        "USING: assocs hashtables hints kernel sequences"
+        "syntax ;"
+        "GENERIC: count-occurrences ( elt obj -- n )"
+        ""
+        "M: sequence count-occurrences [ = ] with count ;"
+        ""
+        "M: assoc count-occurrences"
+        "    swap [ = nip ] curry assoc-filter assoc-size ;"
+        ""
+        "HINTS: M\\ sequence count-occurrences { object array } ;"
+        "HINTS: M\\ assoc count-occurrences { object hashtable } ;"
+    }
 } ;
 
 ABOUT: "hints"

basis/io/directories/directories-docs.factor

@@ -52,7 +52,7 @@ HELP: with-directory-files
 { $examples
     "Print all files in your home directory which are larger than a megabyte:"
     { $code
-        """USING: io.directoies io.files.info io.pathnames ;
+        """USING: io.directories io.files.info io.pathnames ;
 home [
     [
         dup link-info size>> 20 2^ >

basis/io/files/info/unix/unix-docs.factor

@@ -2,7 +2,7 @@
 ! See http://factorcode.org/license.txt for BSD license.
 USING: classes help.markup help.syntax io.streams.string
 strings math calendar io.files.info io.files.info.unix ;
-IN: io.files.unix
+IN: io.files.info.unix
 
 HELP: add-file-permissions
 { $values
@@ -102,15 +102,15 @@ HELP: set-file-permissions
      { "path" "a pathname string" } { "n" "an integer, interepreted as a string of bits" } }
 { $description "Sets the file permissions for a given file with the supplied Unix permissions integer. Supplying an octal number with " { $link POSTPONE: OCT: } " is recommended." }
 { $examples "Using the tradidional octal value:"
-    { $unchecked-example "USING: io.files.unix kernel ;"
+    { $unchecked-example "USING: io.files.info.unix kernel ;"
         "\"resource:license.txt\" OCT: 755 set-file-permissions"
         ""
     }
     "Higher-level, setting named bits:"
-    { $unchecked-example "USING: io.files.unix kernel math.bitwise ;"
+    { $unchecked-example "USING: io.files.info.unix kernel literals ;"
     "\"resource:license.txt\""
-    "{ USER-ALL GROUP-READ GROUP-EXECUTE OTHER-READ OTHER-EXECUTE }"
-    "flags set-file-permissions"
+    "flags{ USER-ALL GROUP-READ GROUP-EXECUTE OTHER-READ OTHER-EXECUTE }"
+    "set-file-permissions"
     "" }
 } ;
 

basis/tools/crossref/crossref-docs.factor

@@ -28,7 +28,7 @@ HELP: uses
 { $notes "The sequence might include the definition itself, if it is a recursive word." }
 { $examples
     "We can ask the " { $link sq } " word to produce a list of words it calls:"
-    { $unchecked-example "\ sq uses ." "{ dup * }" }
+    { $unchecked-example "\\ sq uses ." "{ dup * }" }
 } ;
 
 HELP: crossref

core/io/pathnames/pathnames-docs.factor

@@ -106,7 +106,7 @@ HELP: absolute-path
     { "path" "a pathname string" }
     { "path'" "a pathname string" }
 }
-{ $description "Prepends the " { $link current-directory } " to the pathname and resolves a " { $snippet "resource:" } " or " { $snippet "voacb:" } " prefix, if present (see " { $link "io.pathnames.special" } ")." }
+{ $description "Prepends the " { $link current-directory } " to the pathname and resolves a " { $snippet "resource:" } " or " { $snippet "vocab:" } " prefix, if present (see " { $link "io.pathnames.special" } ")." }
 { $notes "This word is exaclty the same as " { $link normalize-path } ", except on Windows NT platforms, where it does not prepend the Unicode path prefix. Most code should call " { $link normalize-path } " instead." } ;
 
 HELP: resolve-symlinks

core/vocabs/vocabs-docs.factor

@@ -77,7 +77,7 @@ HELP: forget-vocab
 { $notes "This word must be called from inside " { $link with-compilation-unit } "." } ;
 
 HELP: load-vocab-hook
-{ $var-description { $quotation "( name -- vocab )" } " which loads a vocabulary. This quotation is called by " { $link load-vocab } ". The default value should not need to be changed; this functinality is implemented via a hook stored in a variable to break a circular dependency which would otherwise exist from " { $vocab-link "vocabs" } " to " { $vocab-link "vocabs.loader" } " to " { $vocab-link "parser" } " back to " { $vocab-link "vocabs" } "." } ;
+{ $var-description { $quotation "( name -- vocab )" } " which loads a vocabulary. This quotation is called by " { $link load-vocab } ". The default value should not need to be changed; this functionality is implemented via a hook stored in a variable to break a circular dependency which would otherwise exist from " { $vocab-link "vocabs" } " to " { $vocab-link "vocabs.loader" } " to " { $vocab-link "parser" } " back to " { $vocab-link "vocabs" } "." } ;
 
 HELP: words-named
 { $values { "str" string } { "seq" "a sequence of words" } }