From aad68418d26acb5cf1a11416013d8737ea6cfa3f Mon Sep 17 00:00:00 2001
From: Slava Pestov <slava@slava-pestovs-macbook-pro.local>
Date: Sat, 12 Sep 2009 21:18:17 -0500
Subject: [PATCH] math, syntax: document hexadecimal float literal syntax

---
 core/math/parser/parser-docs.factor | 16 ++++++++++++++--
 core/syntax/syntax-docs.factor      | 11 ++++++++---
 2 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/core/math/parser/parser-docs.factor b/core/math/parser/parser-docs.factor
index 1e3ff4f996..af4c712836 100644
--- a/core/math/parser/parser-docs.factor
+++ b/core/math/parser/parser-docs.factor
@@ -5,7 +5,7 @@ IN: math.parser
 ARTICLE: "number-strings" "Converting between numbers and strings"
 "These words only convert between real numbers and strings. Complex numbers are constructed by the parser (" { $link "parser" } ") and printed by the prettyprinter (" { $link "prettyprint" } ")."
 $nl
-"Note that only integers can be converted to and from strings using a representation other than base 10. Calling a word such as " { $link >oct } " on a float will give a result in base 10."
+"Integers can be converted to and from arbitrary bases. Floating point numbers can only be converted to and from base 10 and 16."
 $nl
 "Converting numbers to strings:"
 { $subsection number>string }
@@ -93,7 +93,19 @@ HELP: >oct
 
 HELP: >hex
 { $values { "n" real } { "str" string } }
-{ $description "Outputs a string representation of a number using base 16." } ;
+{ $description "Outputs a string representation of a number using base 16." }
+{ $examples
+    { $example
+        "USING: math.parser prettyprint ;"
+        "3735928559 >hex ."
+        "\"deadbeef\""
+    }
+    { $example
+        "USING: math.parser prettyprint ;"
+        "-15.5 >hex ."
+        "\"-f.8p0\""
+    }
+} ;
 
 HELP: string>float ( str -- n/f )
 { $values { "str" string } { "n/f" "a real number or " { $link f } } }
diff --git a/core/syntax/syntax-docs.factor b/core/syntax/syntax-docs.factor
index 0a11f62c16..e34fb0957f 100644
--- a/core/syntax/syntax-docs.factor
+++ b/core/syntax/syntax-docs.factor
@@ -59,20 +59,25 @@ ARTICLE: "syntax-ratios" "Ratio syntax"
 "More information on ratios can be found in " { $link "rationals" } ;
 
 ARTICLE: "syntax-floats" "Float syntax"
-"Floating point literals must contain a decimal point, and may contain an exponent:"
+"Floating point literals can be input in base 10 or 16. Base 10 literals must contain a decimal point, and may contain an exponent after " { $snippet "e" } ":"
 { $code
     "10.5"
     "-3.1456"
     "7.e13"
     "1.0e-5"
 }
-"There are three special float values:"
+"Base 16 literals use " { $snippet "p" } " instead of " { $snippet "e" } " for the exponent, which is still decimal:"
+{ $example
+    "10.125 HEX: 1.44p3 = ."
+    "t"
+}
+"Syntax for special float values:"
 { $table
 { "Positive infinity" { $snippet "1/0." } }
 { "Negative infinity" { $snippet "-1/0." } }
 { "Not-a-number" { $snippet "0/0." } }
 }
-"A Not-a-number with an arbitrary payload can be parsed in:"
+"A Not-a-number with an arbitrary payload can also be parsed in:"
 { $subsection POSTPONE: NAN: }
 "More information on floats can be found in " { $link "floats" } "." ;