More details for Rational literals (#5840)

doc/syntax/literals.rdoc

@@ -90,15 +90,36 @@ point numbers as well.
 
 === \Rational Literals
 
-You can write a Rational number as follows (suffixed +r+):
+You can write a Rational literal using a special suffix, <tt>'r'</tt>.
 
-  12r         #=> (12/1)
-  12.3r       #=> (123/10)
+Examples:
 
-A \Rational number is exact, whereas a \Float number may be inexact.
+  1r       # => (1/1)
+  2/3r     # => (2/3)   # With denominator.
+  -1r      # => (-1/1)  # With signs.
+  -2/3r    # => (-2/3)
+  2/-3r    # => (-2/3)
+  -2/-3r   # => (2/3)
+  +1/+3r   # => (1/3)
+  1.2r     # => (6/5)   # With fractional part.
+  1_1/2_1r # => (11/21) # With embedded underscores.
+  2/4r     # => (1/2)   # Automatically reduced.
 
-  0.1r + 0.2r #=> (3/10)
-  0.1 + 0.2   #=> 0.30000000000000004
+Syntax:
+
+  <rational-literal> = <numerator> [ '/' <denominator> ] 'r'
+  <numerator> = [ <sign> ] <digits> [ <fractional-part> ]
+  <fractional-part> = '.' <digits>
+  <denominator> = [ sign ] <digits>
+  <sign> = '-' | '+'
+  <digits> = <digit> { <digit> | '_' <digit> }
+  <digit> = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'
+
+Note this, which is parsed as \Float numerator <tt>1.2</tt>
+divided by \Rational denominator <tt>3r</tt>,
+resulting in a \Float:
+
+  1.2/3r  # => 0.39999999999999997
 
 === \Complex Literals