More details for regexp literals (#5800)

Merged-By: BurdetteLamar <BurdetteLamar@Yahoo.com>

doc/syntax/literals.rdoc

@@ -381,15 +381,15 @@ on the methods you need to implement.
 
 == \Regexp Literals
 
-A regular expression is created using "/":
+A regular expression may be created using leading and trailing
+slash (<tt>'/'</tt>) characters:
 
-  /my regular expression/
+  re = /foo/ # => /foo/
+  re.class   # => Regexp
 
-The regular expression may be followed by flags which adjust the matching
-behavior of the regular expression.  The "i" flag makes the regular expression
-case-insensitive:
-
-  /my regular expression/i
+The trailing slash may be followed by one or more _flag_ characters
+that modify the behavior.
+See {Regexp options}[rdoc-ref:Regexp@Options] for details.
 
 Interpolation may be used inside regular expressions along with escaped
 characters.  Note that a regular expression may require additional escaped
@@ -482,13 +482,23 @@ You can write a symbol with <tt>%s</tt>:
 
 === <tt>%r</tt>: Regexp Literals
 
-You can write a regular expression with <tt>%r</tt>:
+You can write a regular expression with <tt>%r</tt>;
+the character used as the leading and trailing delimiter
+may be (almost) any character:
 
-  r = %r[foo\sbar]   # => /foo\sbar/
-  'foo bar'.match(r) # => #<MatchData "foo bar">
-  r = %r[foo\sbar]i  # => /foo\sbar/i
-  'FOO BAR'.match(r) # => #<MatchData "FOO BAR">
+  %r/foo/             # => /foo/
+  %r:name/value pair: # => /name\/value pair/
 
+A few "symmetrical" character pairs may be used as delimiters:
+
+  %r[foo] # => /foo/
+  %r{foo} # => /foo/
+  %r(foo) # => /foo/
+  %r<foo> # => /foo/
+
+The trailing delimiter may be followed by one or more _flag_ characters
+that modify the behavior.
+See {Regexp options}[rdoc-ref:Regexp@Options] for details.
 
 === <tt>%x</tt>: Backtick Literals