From 712ec2ce29353e7dddc74968e11cba120af29b0a Mon Sep 17 00:00:00 2001
From: Slava Pestov <slava@factorcode.org>
Date: Thu, 12 Jan 2006 05:34:56 +0000
Subject: [PATCH] finished math word docs

---
 contrib/math/utils.factor            |   3 +
 library/bootstrap/boot-stage1.factor |   5 ++
 library/help/markup.factor           |   3 +
 library/math/arc-trig-hyp.facts      |   5 +-
 library/math/integer.factor          |   2 +-
 library/math/integer.facts           |   4 +-
 library/math/math.factor             |  36 +++-----
 library/math/math.facts              | 119 +++++++++++++++++++++++++--
 library/math/parse-numbers.factor    |   7 +-
 library/math/parse-numbers.facts     |  55 +++++++++++++
 library/math/pow.factor              |   6 +-
 library/math/random.factor           |   2 +-
 library/math/random.facts            |  10 +++
 library/math/ratio.facts             |  23 ++++++
 library/math/trig-hyp.facts          |  57 +++++++++++++
 library/math/vectors.factor          |   3 -
 library/math/vectors.facts           |  74 +++++++++++++++++
 library/syntax/see.facts             |  64 ++++++++++++++
 18 files changed, 424 insertions(+), 54 deletions(-)
 create mode 100644 library/math/parse-numbers.facts
 create mode 100644 library/math/random.facts
 create mode 100644 library/math/ratio.facts
 create mode 100644 library/math/trig-hyp.facts
 create mode 100644 library/math/vectors.facts
 create mode 100644 library/syntax/see.facts

diff --git a/contrib/math/utils.factor b/contrib/math/utils.factor
index 98ac0e6060..b37a56702e 100644
--- a/contrib/math/utils.factor
+++ b/contrib/math/utils.factor
@@ -36,6 +36,9 @@ USING: errors kernel sequences math sequences-internals namespaces arrays ;
     #! Complex inner product.
     0 [ ** + ] 2reduce ;
 
+: sum ( v -- n ) 0 [ + ] reduce ;
+: product ( v -- n ) 1 [ * ] reduce ;
+
 : proj ( u v -- w )
     #! Orthogonal projection of u onto v.
     [ [ v. ] keep norm-sq v/n ] keep n*v ;
diff --git a/library/bootstrap/boot-stage1.factor b/library/bootstrap/boot-stage1.factor
index 8fffa163b6..930d1a21c4 100644
--- a/library/bootstrap/boot-stage1.factor
+++ b/library/bootstrap/boot-stage1.factor
@@ -235,6 +235,11 @@ vectors words ;
         "/library/math/float.facts"
         "/library/math/integer.facts"
         "/library/math/math.facts"
+        "/library/math/parse-numbers.facts"
+        "/library/math/random.facts"
+        "/library/math/ratio.facts"
+        "/library/math/trig-hyp.facts"
+        "/library/math/vectors.facts"
         "/library/syntax/parse-stream.facts"
         "/library/syntax/parser.facts"
         "/library/syntax/parse-syntax.facts"
diff --git a/library/help/markup.factor b/library/help/markup.factor
index 2d17da2744..a5b3477490 100644
--- a/library/help/markup.factor
+++ b/library/help/markup.factor
@@ -181,3 +181,6 @@ DEFER: help
 : $low-level-note
     drop
     "Calling this word directly is not necessary in most cases. Higher-level words call it automatically." print-element ;
+
+: $values-x/y
+    { { "x" "a complex number" } { "y" "a complex number" } } $values ;
diff --git a/library/math/arc-trig-hyp.facts b/library/math/arc-trig-hyp.facts
index 3de4ff7047..975bd00240 100644
--- a/library/math/arc-trig-hyp.facts
+++ b/library/math/arc-trig-hyp.facts
@@ -1,7 +1,4 @@
-IN: help
-USING: math ;
-
-: $values-x/y { { "x" "a complex number" } { "y" "a complex number" } } $values ;
+USING: help math ;
 
 HELP: acosh "( x -- y )"
 $values-x/y
diff --git a/library/math/integer.factor b/library/math/integer.factor
index faa93381ca..53b4c38ec4 100644
--- a/library/math/integer.factor
+++ b/library/math/integer.factor
@@ -17,7 +17,7 @@ UNION: integer fixnum bignum ;
         tuck /mod >r pick * swap >r swapd - r> r> (gcd)
     ] if ; inline
 
-: gcd ( x y -- a d ) swap 0 1 2swap (gcd) abs ; foldable
+: gcd ( x y -- a d ) 0 1 2swap (gcd) abs ; foldable
 
 : (next-power-of-2) ( i n -- n )
     2dup >= [
diff --git a/library/math/integer.facts b/library/math/integer.facts
index f519a90dd0..ee653fc9da 100644
--- a/library/math/integer.facts
+++ b/library/math/integer.facts
@@ -27,8 +27,8 @@ HELP: odd? "( n -- ? )"
 
 HELP: gcd "( x y -- a d )"
 { $values { "x" "an integer" } { "y" "an integer" } { "a" "an integer" } { "d" "an integer" } }
-{ $description "Computes the positive greatest common divisor " { $snippet "d" } " of " { $snippet "x" } " and " { $snippet "y" } ", and another value " { $snippet "a" } " satisfying:" { $code "a*x = d mod y" } }
-{ $notes "If " { $snippet "d" } " is 1, then " { $snippet "a" } " is the inverse of " { $snippet "x" } " modulo " { $snippet "y" } "." } ;
+{ $description "Computes the positive greatest common divisor " { $snippet "d" } " of " { $snippet "x" } " and " { $snippet "y" } ", and another value " { $snippet "a" } " satisfying:" { $code "a*y = d mod x" } }
+{ $notes "If " { $snippet "d" } " is 1, then " { $snippet "a" } " is the inverse of " { $snippet "y" } " modulo " { $snippet "x" } "." } ;
 
 HELP: next-power-of-2 "( m -- n )"
 { $values { "m" "a non-negative integer" } { "n" "an integer" } }
diff --git a/library/math/math.factor b/library/math/math.factor
index 78bbbf530b..6b691d45b4 100644
--- a/library/math/math.factor
+++ b/library/math/math.factor
@@ -3,7 +3,6 @@
 IN: math
 USING: errors generic kernel math-internals ;
 
-! Math operations
 G: number= ( x y -- ? ) math-combination ; foldable
 M: object number= 2drop f ;
 
@@ -35,42 +34,27 @@ GENERIC: 1- ( x -- x-1 ) foldable
 GENERIC: truncate ( n -- n ) foldable
 GENERIC: floor    ( n -- n ) foldable
 GENERIC: ceiling  ( n -- n ) foldable
-
-: max ( x y -- z ) [ > ] 2keep ? ; inline
-: min ( x y -- z ) [ < ] 2keep ? ; inline
-
-: between? ( x min max -- ? ) pick >= >r >= r> and ; inline
+GENERIC: abs      ( z -- |z| ) foldable
+GENERIC: absq     ( n -- |n|^2 ) foldable
 
 : sq dup * ; inline
-
 : neg 0 swap - ; inline
 : recip 1 swap / ; inline
-
-: rem ( x y -- x%y )
-    #! Like modulus, but always gives a positive result.
-    [ [ mod ] keep + ] keep mod ; inline
-
-: sgn ( n -- -1/0/1 )
-    #! Push the sign of a real number.
-    dup 0 < -1 0 ? swap 0 > 1 0 ? bitor ; foldable
-
-GENERIC: abs ( z -- |z| ) foldable
-GENERIC: absq ( n -- |n|^2 ) foldable
-
-: align ( offset width -- offset )
-    1- [ + ] keep bitnot bitand ; inline
+: max ( x y -- z ) [ > ] 2keep ? ; inline
+: min ( x y -- z ) [ < ] 2keep ? ; inline
+: between? ( x min max -- ? ) pick >= >r >= r> and ; inline
+: rem ( x y -- z ) tuck mod over + swap mod ; inline
+: sgn ( m -- n ) dup 0 < -1 0 ? swap 0 > 1 0 ? bitor ; foldable
+: align ( m w -- n ) 1- [ + ] keep bitnot bitand ; inline
 
 : (repeat) ( i n quot -- )
     pick pick >=
     [ 3drop ] [ [ swap >r call 1+ r> ] keep (repeat) ] if ;
     inline
 
-: repeat ( n quot -- | quot: n -- n )
-    #! The loop counter is kept on the stack, and ranges from
-    #! 0 to n-1.
-    0 -rot (repeat) ; inline
+: repeat ( n quot -- | quot: n -- n ) 0 -rot (repeat) ; inline
 
 : times ( n quot -- | quot: -- )
     swap [ >r dup slip r> ] repeat drop ; inline
 
-GENERIC: number>string ( str -- num ) foldable
+GENERIC: number>string ( n -- str ) foldable
diff --git a/library/math/math.facts b/library/math/math.facts
index 06a0ea3927..9d32314495 100644
--- a/library/math/math.facts
+++ b/library/math/math.facts
@@ -67,7 +67,8 @@ HELP: / "( x y -- z )"
         "Division of floats always yields a float."
         "Division of ratios and complex numbers proceeds using the relevant mathematical rules."
     }
-} ;
+}
+{ $errors "Throws an error if both inputs are integers, and the denominator is 0." } ;
 
 HELP: /i "( x y -- z )"
 { $values { "x" "a real number" } { "y" "a real number" } { "z" "a real number" } }
@@ -79,7 +80,8 @@ HELP: /i "( x y -- z )"
         "Integer division of floats always yields a float."
         "Integer division of ratios and complex numbers proceeds using the relevant mathematical rules."
     }
-} ;
+}
+{ $errors "Throws an error if both inputs are integers, and the denominator is 0." } ;
 
 HELP: /f "( x y -- z )"
 { $values { "x" "a real number" } { "y" "a real number" } { "z" "a real number" } }
@@ -91,7 +93,8 @@ HELP: /f "( x y -- z )"
         "Integer division of floats always yields a float."
         "Integer division of ratios and complex numbers proceeds using the relevant mathematical rules."
     }
-} ;
+}
+{ $errors "Throws an error if both inputs are integers, and the denominator is 0." } ;
 
 HELP: mod "( x y -- z )"
 { $values { "x" "an integer" } { "y" "an integer" } { "z" "an integer" } }
@@ -101,7 +104,9 @@ HELP: mod "( x y -- z )"
         "Modulus of fixnums always yields a fixnum."
         "Modulus of bignums always yields a bignum."            
     }
-} ;
+}
+{ $errors "Throws an error if the denominator is 0." }
+{ $see-also rem } ;
 
 HELP: /mod "( x y -- z w )"
 { $values { "x" "an integer" } { "y" "an integer" } { "z" "an integer" } { "w" "an integer" } }
@@ -111,7 +116,8 @@ HELP: /mod "( x y -- z w )"
         "The quotient of two fixnums may overflow and yield a bignum; the remainder is always a fixnum"
         "The quotient and remainder of two bignums is always a bignum."            
     }
-} ;
+}
+{ $errors "Throws an error if the denominator is 0." } ;
 
 HELP: bitand "( x y -- z )"
 { $values { "x" "an integer" } { "y" "an integer" } { "z" "an integer" } }
@@ -139,5 +145,106 @@ HELP: bitxor "( x y -- z )"
 
 HELP: shift "( x n -- y )"
 { $values { "x" "an integer" } { "n" "an integer" } { "y" "an integer" } }
-{ $description "Shifts " { $snippet "x" } " to the left by " { $snippet "y" } " bits if " { $snippet "y" } " is positive, or " { $snippet "-y" } " bits to the right if " { $snippet "y" } " is negative. Bits ``falling off'' the right hand side are discarded." }
+{ $description "Shifts " { $snippet "x" } " to the left by " { $snippet "y" } " bits if " { $snippet "y" } " is positive, or " { $snippet "-y" } " bits to the right if " { $snippet "y" } " is negative. A left shift of a fixnum may overflow, yielding a bignum. A right shift may result in bits ``falling off'' the right hand side and being discarded." }
 { $examples { $example "BIN: 101 5 shift .b" "10100000" } { $example "BIN: 11111 -2 shift .b" "111" } } ;
+
+HELP: bitnot "( x -- y )"
+{ $values { "x" "an integer" } { "y" "an integer" } }
+{ $description "Computes the bitwise complement of the input; that is, each bit in the input number is flipped." }
+{ $notes "Due to the two's complement representation of signed integers, the following two lines are equivalent:" { $code "bitnot" "neg 1-" } } ;
+
+HELP: 1+ "( x -- y )"
+{ $values { "x" "a number" } { "y" "a number" } }
+{ $description
+    "Increments a number by 1. The following two lines are equivalent, but the first is more efficient:"
+    { $code "1+" "1 +" }
+} ;
+
+HELP: 1- "( x -- y )"
+{ $values { "x" "a number" } { "y" "a number" } }
+{ $description
+    "Decrements a number by 1. The following two lines are equivalent, but the first is more efficient:"
+    { $code "1-" "1 -" }
+} ;
+
+HELP: truncate "( x -- y )"
+{ $values { "x" "a real number" } { "y" "a whole real number" } }
+{ $description "Outputs the number that results from subtracting the fractional component of " { $snippet "x" } "." }
+{ $notes "The result is not necessarily an integer." } ;
+
+HELP: floor "( x -- y )"
+{ $values { "x" "a real number" } { "y" "a whole real number" } }
+{ $description "Outputs the greatest whole number smaller than or equal to " { $snippet "x" } "." }
+{ $notes "The result is not necessarily an integer." } ;
+
+HELP: ceiling "( x -- y )"
+{ $values { "x" "a real number" } { "y" "a whole real number" } }
+{ $description "Outputs the least whole number greater than or equal to " { $snippet "x" } "." }
+{ $notes "The result is not necessarily an integer." } ;
+
+HELP: abs "( x -- y )"
+{ $values { "x" "a complex number" } { "y" "a non-negative real number" } }
+{ $description "Computes the absolute value of a complex number." } ;
+
+HELP: absq "( x -- y )"
+{ $values { "x" "a complex number" } { "y" "a non-negative real number" } }
+{ $description "Computes the squared absolute value of a complex number. This is marginally more efficient than " { $link abs } "." } ;
+
+HELP: sq "( x -- y )"
+{ $values { "x" "a number" } { "y" "a number" } }
+{ $description "Multiplies a number by itself." } ;
+
+HELP: neg "( x -- -x )"
+{ $values { "x" "a number" } { "-x" "a number" } }
+{ $description "Computes a number's additive inverse." } ;
+
+HELP: recip "( x -- -x )"
+{ $values { "x" "a number" } { "-x" "a number" } }
+{ $description "Computes a number's multiplicative inverse." }
+{ $errors "Throws an error if " { $snippet "x" } " is the integer 0." } ;
+
+HELP: max "( x y -- z )"
+{ $values { "x" "a real number" } { "y" "a real number" } { "z" "a real number" } }
+{ $description "Outputs the greatest of two real numbers." } ;
+
+HELP: min "( x y -- z )"
+{ $values { "x" "a real number" } { "y" "a real number" } { "z" "a real number" } }
+{ $description "Outputs the smallest of two real numbers." } ;
+
+HELP: between? "( x y z -- ? )"
+{ $values { "x" "a real number" } { "y" "a real number" } { "z" "a real number" } { "?" "a boolean" } }
+{ $description "Tests if " { $snippet "x" } " is in the interval " { $snippet "[y,z]" } "." }
+{ $notes "As per the closed interval notation, the end-points are included in the interval." } ;
+
+HELP: rem "( x y -- z )"
+{ $values { "x" "an integer" } { "y" "an integer" } { "z" "an integer" } }
+{ $description
+    "Computes the remainder of dividing " { $snippet "x" } " by " { $snippet "y" } ", with the remainder always positive."
+    { $list 
+        "Modulus of fixnums always yields a fixnum."
+        "Modulus of bignums always yields a bignum."            
+    }
+}
+{ $errors "Throws an error if the denominator is 0." }
+{ $see-also mod } ;
+
+HELP: sgn "( x -- n )"
+{ $values { "x" "a real number" } { "n" "-1, 0 or 1" } }
+{ $description
+    "Outputs one of the following:"
+    { $list
+        "-1 if " { $snippet "x" } " is negative"
+        "0 if " { $snippet "x" } " is equal to 0"
+        "1 if " { $snippet "x" } " is positive"
+    }
+} ;
+
+HELP: align "( m w -- n )"
+{ $values { "m" "an integer" } { "w" "a power of 2" } { "n" "an integer multiple of " { $snippet "w" } } }
+{ $description "Outputs the least multiple of " { $snippet "w" } " greater than " { $snippet "m" } "." }
+{ $notes "This word will give an incorrect result if " { $snippet "w" } " is not a power of 2." } ;
+
+HELP: number>string "( n -- str )"
+{ $values { "n" "a real number" } { "str" "a string" } }
+{ $description "Converts a real number to a string." }
+{ $notes "Printing complex numbers requires the more general prettyprinter facility (see " { $link "prettyprint" } ")." } ;
diff --git a/library/math/parse-numbers.factor b/library/math/parse-numbers.factor
index 454c7b33d5..d742f46db2 100644
--- a/library/math/parse-numbers.factor
+++ b/library/math/parse-numbers.factor
@@ -1,11 +1,9 @@
 ! Copyright (C) 2004, 2005 Slava Pestov.
-! See http://factor.sf.net/license.txt for BSD license.
+! See http://factorcode.org/license.txt for BSD license.
 IN: math
 USING: errors generic kernel math-internals namespaces sequences
 strings ;
 
-! Number parsing
-
 : not-a-number "Not a number" throw ;
 
 DEFER: base>
@@ -54,7 +52,6 @@ M: object digit> not-a-number ;
 G: >base ( num radix -- string ) [ over ] standard-combination ;
 
 M: integer >base ( num radix -- string )
-    #! Convert a number to a string in a certain base.
     [
         over 0 < [
             swap neg swap integer, CHAR: - ,
@@ -71,8 +68,6 @@ M: ratio >base ( num radix -- string )
     ] "" make ;
 
 M: float >base ( num radix -- string )
-    #! This is terrible. Will go away when we do our own float
-    #! output.
     drop float>string
     CHAR: . over member? [ ".0" append ] unless ;
 
diff --git a/library/math/parse-numbers.facts b/library/math/parse-numbers.facts
new file mode 100644
index 0000000000..4045915ea5
--- /dev/null
+++ b/library/math/parse-numbers.facts
@@ -0,0 +1,55 @@
+USING: help math prettyprint ;
+
+HELP: base> "( str radix -- n )"
+{ $values { "str" "a string" } { "radix" "an integer between 2 and 36" } { "n" "a real number" } }
+{ $description "Creates a real number from a string representation with the given radix. The radix is ignored for floating point literals; they are always taken to be in base 10." }
+{ $errors "Throws an error if the string cannot be interpreted as a number in the given base." }
+{ $see-also >base } ;
+
+HELP: string>number "( str -- n )"
+{ $values { "str" "a string" } { "n" "a real number" } }
+{ $description "Creates a real number from a string representation of a number in base 10." }
+{ $errors "Throws an error if the string cannot be interpreted as a number in base 10." }
+{ $see-also number>string } ;
+
+HELP: bin> "( str -- n )"
+{ $values { "str" "a string" } { "n" "a real number" } }
+{ $description "Creates a real number from a string representation of a number in base 2." }
+{ $errors "Throws an error if the string cannot be interpreted as a number in base 2." }
+{ $see-also POSTPONE: BIN: } ;
+
+HELP: oct> "( str -- n )"
+{ $values { "str" "a string" } { "n" "a real number" } }
+{ $description "Creates a real number from a string representation of a number in base 8." }
+{ $errors "Throws an error if the string cannot be interpreted as a number in base 8." }
+{ $see-also POSTPONE: OCT: } ;
+
+HELP: hex> "( str -- n )"
+{ $values { "str" "a string" } { "n" "a real number" } }
+{ $description "Creates a real number from a string representation of a number in base 16." }
+{ $errors "Throws an error if the string cannot be interpreted as a number in base 16." }
+{ $see-also POSTPONE: HEX: } ;
+
+HELP: >base "( n radix -- str )"
+{ $values { "n" "a real number" } { "radix" "an integer between 2 and 36" } { "str" "a string" } }
+{ $description "Converts a real number into a string representation using the given radix. If the number is a float, the radix is ignored and the output is always in base 10." }
+{ $see-also base> } ;
+
+HELP: number>string "( n -- str )"
+{ $values { "n" "a real number" } { "str" "a string" } }
+{ $description "Outputs a string representation of a number using base 10." } ;
+
+HELP: >bin "( n -- str )"
+{ $values { "n" "a real number" } { "str" "a string" } }
+{ $description "Outputs a string representation of a number using base 2." }
+{ $see-also .b } ;
+
+HELP: >oct "( n -- str )"
+{ $values { "n" "a real number" } { "str" "a string" } }
+{ $description "Outputs a string representation of a number using base 8." } 
+{ $see-also .o } ;
+
+HELP: >hex "( n -- str )"
+{ $values { "n" "a real number" } { "str" "a string" } }
+{ $description "Outputs a string representation of a number using base 16." } 
+{ $see-also .h } ;
diff --git a/library/math/pow.factor b/library/math/pow.factor
index a2aca0426a..f709ea29f4 100644
--- a/library/math/pow.factor
+++ b/library/math/pow.factor
@@ -1,5 +1,5 @@
 ! Copyright (C) 2004, 2005 Slava Pestov.
-! See http://factor.sf.net/license.txt for BSD license.
+! See http://factorcode.org/license.txt for BSD license.
 IN: math
 USING: errors kernel math math-internals ;
 
@@ -9,7 +9,6 @@ USING: errors kernel math math-internals ;
 GENERIC: sqrt ( n -- n ) foldable
 
 M: complex sqrt >polar swap fsqrt swap 2 / polar> ;
-
 M: real sqrt dup 0 < [ neg fsqrt 0 swap rect> ] [ fsqrt ] if ;
 
 GENERIC: ^ ( z w -- z^w ) foldable
@@ -24,8 +23,6 @@ M: number ^ ( z w -- z^w )
     swap >polar 3dup ^theta >r ^mag r> polar> ;
 
 : each-bit ( n quot -- | quot: 0/1 -- )
-    #! Apply the quotation to each bit of the number. The number
-    #! must be positive.
     over 0 number= pick -1 number= or [
         2drop
     ] [
@@ -51,7 +48,6 @@ M: integer ^ ( z w -- z^w )
     ] if ; foldable
 
 : log2 ( n -- b )
-    #! Log base two for integers.
     {
         { [ dup 0 <= ] [ "Input must be positive" throw ] }
         { [ dup 1 = ] [ drop 0 ] }
diff --git a/library/math/random.factor b/library/math/random.factor
index e6317b5c32..cdfea2b7ed 100644
--- a/library/math/random.factor
+++ b/library/math/random.factor
@@ -1,5 +1,5 @@
 ! Copyright (C) 2005 Doug Coleman.
-! See http://factor.sf.net/license.txt for BSD license.
+! See http://factorcode.org/license.txt for BSD license.
 
 ! mersenne twister based on 
 ! http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/MT2002/CODES/mt19937ar.c
diff --git a/library/math/random.facts b/library/math/random.facts
new file mode 100644
index 0000000000..23fcf1431c
--- /dev/null
+++ b/library/math/random.facts
@@ -0,0 +1,10 @@
+USING: help math ;
+
+HELP: (random-int) "( -- rand )"
+{ $values { "rand" "an integer between 0 and 2^32-1" } }
+{ $description "Generates a random 32-bit unsigned integer." } ;
+
+HELP: random-int "( n -- rand )"
+{ $values { "rand" "an integer between 0 and n" } }
+{ $description "Outputs a pseudo-random integer in the interval " { $snippet "[0,n]" } "." }
+{ $notes "As per the closed interval notation, the end-points are included in the interval." } ;
diff --git a/library/math/ratio.facts b/library/math/ratio.facts
new file mode 100644
index 0000000000..e32983e337
--- /dev/null
+++ b/library/math/ratio.facts
@@ -0,0 +1,23 @@
+USING: help math math-internals ;
+
+HELP: ratio f
+{ $description "The class of rational numbers with denominator not equal to 1." } ;
+
+HELP: rational f
+{ $description "The class of rational numbers, a disjoint union of integers and ratios." } ;
+
+HELP: numerator "( a/b -- a )"
+{ $values { "a/b" "a rational number" } { "a" "an integer" } }
+{ $description "Outputs the numerator of a rational number. Acts as the identity on integers." } ;
+
+HELP: denominator "( a/b -- b )"
+{ $values { "a/b" "a rational number" } { "b" "a positive integer" } }
+{ $description "Outputs the denominator of a rational number. Always outputs 1 with integers." } ;
+
+HELP: >fraction "( a/b -- a b )"
+{ $values { "a/b" "a rational number" } { "a" "an integer" } { "b" "a positive integer" } }
+{ $description "Extracts the numerator and denominator of a rational number." } ;
+
+HELP: 2>fraction "( a/b c/d -- a c b d )"
+{ $values { "a/b" "a rational number" } { "a" "an integer" } { "c" "an integer" } { "b" "a positive integer" } { "d" "a positive integer" } }
+{ $description "Extracts the numerator and denominator of two rational numbers at once." } ;
diff --git a/library/math/trig-hyp.facts b/library/math/trig-hyp.facts
new file mode 100644
index 0000000000..d14a36410e
--- /dev/null
+++ b/library/math/trig-hyp.facts
@@ -0,0 +1,57 @@
+USING: help math ;
+
+HELP: cosh "( x -- y )"
+$values-x/y
+{ $description "Hyperbolic cosine." } ;
+
+HELP: sech "( x -- y )"
+$values-x/y
+{ $description "Hyperbolic secant." } ;
+
+HELP: sinh "( x -- y )"
+$values-x/y
+{ $description "Hyperbolic sine." } ;
+
+HELP: sinh "( x -- y )"
+$values-x/y
+{ $description "Hyperbolic sine." } ;
+
+HELP: cosech "( x -- y )"
+$values-x/y
+{ $description "Hyperbolic cosecant." } ;
+
+HELP: tanh "( x -- y )"
+$values-x/y
+{ $description "Hyperbolic tangent." } ;
+
+HELP: coth "( x -- y )"
+$values-x/y
+{ $description "Hyperbolic cotangent." } ;
+
+HELP: cosh "( x -- y )"
+$values-x/y
+{ $description "Trigonometric cosine." } ;
+
+HELP: sech "( x -- y )"
+$values-x/y
+{ $description "Trigonometric secant." } ;
+
+HELP: sinh "( x -- y )"
+$values-x/y
+{ $description "Trigonometric sine." } ;
+
+HELP: sinh "( x -- y )"
+$values-x/y
+{ $description "Trigonometric sine." } ;
+
+HELP: cosech "( x -- y )"
+$values-x/y
+{ $description "Trigonometric cosecant." } ;
+
+HELP: tanh "( x -- y )"
+$values-x/y
+{ $description "Trigonometric tangent." } ;
+
+HELP: coth "( x -- y )"
+$values-x/y
+{ $description "Trigonometric cotangent." } ;
diff --git a/library/math/vectors.factor b/library/math/vectors.factor
index 7735203f03..3123c23508 100644
--- a/library/math/vectors.factor
+++ b/library/math/vectors.factor
@@ -22,8 +22,5 @@ USING: arrays generic kernel sequences ;
 : norm ( vec -- n ) norm-sq sqrt ;
 : normalize ( vec -- uvec ) dup norm v/n ;
 
-: sum ( v -- n ) 0 [ + ] reduce ;
-: product ( v -- n ) 1 [ * ] reduce ;
-
 : set-axis ( x y axis -- v )
     dup length [ >r 0 = pick pick ? r> swap nth ] 2map 2nip ;
diff --git a/library/math/vectors.facts b/library/math/vectors.facts
new file mode 100644
index 0000000000..1e532c74e1
--- /dev/null
+++ b/library/math/vectors.facts
@@ -0,0 +1,74 @@
+USING: help math ;
+
+HELP: vneg "( u -- v )"
+{ $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
+{ $description "Negates each element of " { $snippet "u" } "." } ;
+
+HELP: n*v "( n u -- v )"
+{ $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
+{ $description "Multiplies each element of " { $snippet "u" } " by " { $snippet "n" } "." } ;
+
+HELP: v*n "( n u -- v )"
+{ $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
+{ $description "Multiplies each element of " { $snippet "u" } " by " { $snippet "n" } "." } ;
+
+HELP: n/v "( n u -- v )"
+{ $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
+{ $description "Divides " { $snippet "n" } " by each element of " { $snippet "u" } "." } ;
+
+HELP: v/n "( n u -- v )"
+{ $values { "n" "a number" } { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
+{ $description "Divides each element of " { $snippet "u" } " by " { $snippet "n" } "." } ;
+
+HELP: v+ "( u v -- w )"
+{ $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
+{ $description "Adds " { $snippet "u" } " and " { $snippet "v" } " component-wise." } ;
+
+HELP: v- "( u v -- w )"
+{ $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
+{ $description "Subtracts " { $snippet "v" } " from " { $snippet "u" } " component-wise." } ;
+
+HELP: v* "( u v -- w )"
+{ $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
+{ $description "Multiplies " { $snippet "u" } " and " { $snippet "v" } " component-wise." } ;
+
+HELP: v/ "( u v -- w )"
+{ $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
+{ $description "Divides " { $snippet "u" } " by " { $snippet "v" } " component-wise." }
+{ $errors "Throws an error if an integer division by zero occurs." } ;
+
+HELP: vmax "( u v -- w )"
+{ $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
+{ $description "Creates a sequence where each element is the maximum of the corresponding elements from " { $snippet "u" } " andd " { $snippet "v" } "." }
+{ $examples { $example "{ 1 2 5 } { -7 6 3 } vmax ." "{ 1 6 5 }" } } ;
+
+HELP: vmin "( u v -- w )"
+{ $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "w" "a sequence of real numbers" } }
+{ $description "Creates a sequence where each element is the minimum of the corresponding elements from " { $snippet "u" } " andd " { $snippet "v" } "." }
+{ $examples { $example "{ 1 2 5 } { -7 6 3 } vmin ." "{ -7 2 3 }" } } ;
+
+HELP: v. "( u v -- y )"
+{ $values { "u" "a sequence of real numbers" } { "v" "a sequence of real numbers" } { "y" "a real number" } }
+{ $description "Computes the real-valued dot product." }
+{ $notes
+    "This word can also take complex number sequences as input, however mathematically it will compute the wrong result. The complex-valued dot product is defined differently:"
+    { $snippet "0 [ conjugate * + ] 2reduce" }
+} ;
+
+HELP: norm-sq "( v -- y )"
+{ $values { "v" "a sequence of numbers" } { "y" "a non-negative real number" } }
+{ $description "Computes the squared length of a mathematical vector." } ;
+
+HELP: norm "( v -- y )"
+{ $values { "v" "a sequence of numbers" } { "y" "a non-negative real number" } }
+{ $description "Computes the length of a mathematical vector." } ;
+
+HELP: normalize "( v -- v )"
+{ $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } }
+{ $description "Computes a mathematical vector with the same direction but length 1." }
+{ $errors "Throws an error if " { $snippet "v" } " has zero length." } ;
+
+HELP: set-axis "( u v axis -- w )"
+{ $values { "u" "a sequence of numbers" } { "v" "a sequence of numbers" } { "w" "a sequence of numbers" } }
+{ $description "Using " { $snippet "w" } " as a template, creates a new sequence containing corresponding elements from " { $snippet "x" } " in place of 0, and corresponding elements from " { $snippet "y" } " in place of 1." }
+{ $examples { $example "{ 1 2 3 } { 4 5 6 } { 0 1 0 } set-axis ." "{ 1 5 3 }" } } ;
diff --git a/library/syntax/see.facts b/library/syntax/see.facts
new file mode 100644
index 0000000000..f3cfa9c398
--- /dev/null
+++ b/library/syntax/see.facts
@@ -0,0 +1,64 @@
+USING: help prettyprint ;
+
+HELP: declaration. "( word prop -- )"
+{ $values { "word" "a word" } { "prop" "a word" } }
+{ $description "Prettyprints " { $snippet "prop" } " if " { $snippet "word" } " defines a word property string named by " { $snippet "prop" } "." }
+$prettyprinting-note ;
+
+HELP: in. "( word -- )"
+{ $values { "word" "a word" } }
+{ $description "Prettyprints a " { $snippet "IN:" } " declaration for the word." }
+$prettyprinting-note ;
+
+HELP: (synopsis) "( word -- )"
+{ $values { "word" "a word" } }
+{ $description "Prettyprints the prologue of the word's source definition." }
+$prettyprinting-note ;
+
+HELP: comment. "( string -- )"
+{ $description "Prettyprints some text with the comment style." }
+$prettyprinting-note ;
+
+HELP: stack-effect "( word -- str )"
+{ $values { "word" "a word" } { "str" "a string" } }
+{ $description "Outputs the stack effect of a word, as a stack picture string. The stack effect is taken from either online help, or a cached inferred effect." }
+$prettyprinting-note ;
+
+HELP: synopsis "( word -- str )"
+{ $values { "word" "a word" } { "str" "a string" } }
+{ $description "Outputs a short string describing the word in Factor pseudo-code." }
+{ $examples { $example "\\ append synopsis print" "IN: sequences : append ( seq1 seq2 -- seq )" } } ;
+
+HELP: (see) "( word -- )"
+{ $values { "word" "a word" } }
+{ $contract "Prettyprints the definition of the word." }
+$prettyprinting-note ;
+
+HELP: see-body "( quot word -- )"
+{ $values { "quot" "a quotation" } { "word" "a word" } }
+{ $description "Prettyprints the elements of a quotation, followed by a semicolon (;) and any declarations for the word." }
+$prettyprinting-note ;
+
+HELP: method. "( word class method -- )"
+{ $values { "word" "a generic word" } { "class" "a class word" } { "method" "a method quotation" } }
+{ $description "Prettyprints a method definition." }
+$prettyprinting-note ;
+
+HELP: class. "( class -- )"
+{ $values { "class" "a class word" } }
+{ $contract "Prettyprints the class definition." }
+$prettyprinting-note ;
+
+HELP: methods. "( class -- )"
+{ $values { "class" "a class word" } }
+{ $contract "Prettyprints all methods defined on this class." }
+$prettyprinting-note ;
+
+HELP: see "( word -- )"
+{ $values { "word" "a word" } }
+{ $description "Prettyprints the definition of a word." } ;
+
+HELP: apropos "( substr -- )"
+{ $values { "substr" "a string" } }
+{ $description "Outputs a list of all words whose name is a completion for " { $snippet "substr" } ", in the sense that after tokenizing both the word name and " { $snippet "substr" } " on a set of dividers, each chunk in the word name contains the corresponding chunk from " { $snippet "substr" } "." }
+{ $examples { $example "\"h-e\" apropos" "IN: hashtables : hash-subset ( hash quot -- subhash )\nIN: hashtables : hash-subset-with" } } ;