Start to document number literals

Author: moritz

lib/Language/syntax.pod

@@ -212,11 +212,61 @@ String literals are surrounded by quotes:
 
 See L<quoting|/language/quoting> for many more options.
 
-=begin comment
-
 =head3 Number literals
 
-TODO
+Number literals are generally specified in base ten, unless a prefix like
+C<0x> (heB<x>ademcimal, base 16), C<0o> (B<o>ctal, base 8) or C<0b>
+(B<b>inary, base 2) or an explicit base in adverbial notation like
+C<< :16<A0> >> specifies it otherwise. Unlike other programming languages,
+leading zeros do I<not> indicate base 8; instea a compile-time warning is
+issued
+
+In all literal formats, you can use underscores to group digits;
+they don't carry any semantic; the following literals all evaluate to the same
+number:
+
+    1000000
+    1_000_000  
+    10_0000
+    10_00_00
+
+=head4 L<Int|/type/Int> literals
+
+    -2
+    12345
+    0xBEEF      # base 16
+    0o755       # base 8
+
+=comment TODO adverbial bases with :20<...>
+
+=head4 L<Rat|/type/Rat> literals
+
+    1.0
+    3.14159
+    -2.5
+
+=comment TODO adverbial bases with :20<...>
+
+=head4 L<Num|/type/Num> literals
+
+Scientific notation with an exponent to base ten after an C<e> produces
+L<floating point number|/type/Num>:
+
+    1e0
+    6.022e23
+    1e-9
+    -2e48
+
+=head4 L<Complex|/type/Complex> literals
+
+L<Complex|/type/Complex> numbers are written either as an imaginary number
+(which is just a rational number with postfix C<i> appended), or as a sum of
+a real and an imaginary number:
+
+    1+2i
+    6.123e5i
+
+=begin comment
 
 =head3 Pair literals