document raw string literals in tutorial.md and rust.md

2 files changed, 38 insertions, 5 deletions

diff --git a/doc/rust.md b/doc/rust.md
index e998f97869f..59ff9736052 100644
--- a/doc/rust.md
+++ b/doc/rust.md
@@ -239,13 +239,14 @@ literal : string_lit | char_lit | num_lit ;
 
 ~~~~~~~~ {.ebnf .gram}
 char_lit : '\x27' char_body '\x27' ;
-string_lit : '"' string_body * '"' ;
+string_lit : '"' string_body * '"' | 'r' raw_string ;
 
 char_body : non_single_quote
           | '\x5c' [ '\x27' | common_escape ] ;
 
 string_body : non_double_quote
             | '\x5c' [ '\x22' | common_escape ] ;
+raw_string : '"' raw_string_body '"' | '#' raw_string '#' ;
 
 common_escape : '\x5c'
               | 'n' | 'r' | 't' | '0'
@@ -267,9 +268,10 @@ which must be _escaped_ by a preceding U+005C character (`\`).
 
 A _string literal_ is a sequence of any Unicode characters enclosed within
 two `U+0022` (double-quote) characters, with the exception of `U+0022`
-itself, which must be _escaped_ by a preceding `U+005C` character (`\`).
+itself, which must be _escaped_ by a preceding `U+005C` character (`\`),
+or a _raw string literal_.
 
-Some additional _escapes_ are available in either character or string
+Some additional _escapes_ are available in either character or non-raw string
 literals. An escape starts with a `U+005C` (`\`) and continues with one of
 the following forms:
 
@@ -285,9 +287,35 @@ the following forms:
   * A _whitespace escape_ is one of the characters `U+006E` (`n`), `U+0072`
     (`r`), or `U+0074` (`t`), denoting the unicode values `U+000A` (LF),
     `U+000D` (CR) or `U+0009` (HT) respectively.
-  * The _backslash escape_ is the character U+005C (`\`) which must be
+  * The _backslash escape_ is the character `U+005C` (`\`) which must be
     escaped in order to denote *itself*.
 
+Raw string literals do not process any escapes. They start with the character
+`U+0072` (`r`), followed zero or more of the character `U+0023` (`#`) and a
+`U+0022` (double-quote) character. The _raw string body_ is not defined in the
+EBNF grammar above: it can contain any sequence of Unicode characters and is
+terminated only by another `U+0022` (double-quote) character, followed by the
+same number of `U+0023` (`#`) characters that preceeded the opening `U+0022`
+(double-quote) character.
+
+All Unicode characters contained in the raw string body represent themselves,
+the characters `U+0022` (double-quote) (except when followed by at least as
+many `U+0023` (`#`) characters as were used to start the raw string literal) or
+`U+005C` (`\`) do not have any special meaning.
+
+Examples for string literals:
+
+~~~
+"foo"; r"foo";                     // foo
+"\"foo\""; r#""foo""#;             // "foo"
+
+"foo #\"# bar";
+r##"foo #"# bar"##;                // foo #"# bar
+
+"\x52"; "R"; r"R";                 // R
+"\\x52"; r"\x52";                  // \x52
+~~~
+
 #### Number literals
 
 ~~~~~~~~ {.ebnf .gram}
diff --git a/doc/tutorial.md b/doc/tutorial.md
index 49ba38954b3..fcb8f2836a4 100644
--- a/doc/tutorial.md
+++ b/doc/tutorial.md
@@ -353,7 +353,12 @@ whose literals are written between single quotes, as in `'x'`.
 Just like C, Rust understands a number of character escapes, using the backslash
 character, such as `\n`, `\r`, and `\t`. String literals,
 written between double quotes, allow the same escape sequences.
-More on strings [later](#vectors-and-strings).
+
+On the other hand, raw string literals do not process any escape sequences.
+They are written as `r##"blah"##`, with a matching number of zero or more `#`
+before the opening and after the closing quote, and can contain any sequence of
+characters except their closing delimiter.  More on strings
+[later](#vectors-and-strings).
 
 The nil type, written `()`, has a single value, also written `()`.