From 9bbef9d62c9da26a00c51861569d2954fb3bbc1c Mon Sep 17 00:00:00 2001
From: Alexander Regueiro <alexreg@me.com>
Date: Thu, 9 Aug 2018 23:43:09 +0100
Subject: [PATCH] Added section on compatibility and subsection on raw
 identifiers.

---
 src/SUMMARY.md                       |  7 +++--
 src/compatibility.md                 |  7 +++++
 src/compatibility/raw_identifiers.md | 42 ++++++++++++++++++++++++++++
 src/index.md                         |  6 ++--
 4 files changed, 58 insertions(+), 4 deletions(-)
 create mode 100644 src/compatibility.md
 create mode 100644 src/compatibility/raw_identifiers.md

diff --git a/src/SUMMARY.md b/src/SUMMARY.md
index 24f7ce8303..31792d0fa7 100644
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@@ -196,7 +196,10 @@
     - [Integration testing](testing/integration_testing.md)
     - [Dev-dependencies](testing/dev_dependencies.md)
 
+- [Unsafe Operations](unsafe.md)
+
+- [Compatibility](compatibility.md)
+    - [Raw identifiers](compatibility/raw_identifiers.md)
+
 - [Meta](meta.md)
     - [Documentation](meta/doc.md)
-
-- [Unsafe Operations](unsafe.md)
diff --git a/src/compatibility.md b/src/compatibility.md
new file mode 100644
index 0000000000..00424ceb22
--- /dev/null
+++ b/src/compatibility.md
@@ -0,0 +1,7 @@
+# Compatibility
+
+The Rust language is fastly evolving, and because of this certain compatibility
+issues can arise, despite efforts to ensure forwards-compatibility wherever
+possible.
+
+* [Raw identifiers](compatibility/raw_identifiers.md)
diff --git a/src/compatibility/raw_identifiers.md b/src/compatibility/raw_identifiers.md
new file mode 100644
index 0000000000..eb42cf645a
--- /dev/null
+++ b/src/compatibility/raw_identifiers.md
@@ -0,0 +1,42 @@
+# Raw identifiers
+
+Rust, like many programming languages, has the concept of "keywords".
+These identifiers mean something to the language, and so you cannot use them in
+places like variable names, function names, and other places.
+Raw identifiers let you use keywords where they would not normally be allowed.
+This is particularly useful when Rust introduces new keywords, and a library
+using an older edition of Rust has a variable or function with the same name
+as a keyword introduced in a newer edition.
+
+For example, consider a crate `foo` compiled with the 2015 edition of Rust that
+exports a function named `try`. This keyword is reserved for a new feature in
+the 2018 edition, so without raw identifiers, we would have no way to name the
+function.
+
+```rust,ignore
+extern crate foo;
+
+fn main() {
+    foo::try();
+}
+```
+
+You'll get this error:
+
+```text
+error: expected identifier, found keyword `try`
+ --> src/main.rs:4:4
+  |
+4 | foo::try();
+  |      ^^^ expected identifier, found keyword
+```
+
+You can write this with a raw identifier:
+
+```rust,ignore
+extern crate foo;
+
+fn main() {
+    foo::r#try();
+}
+```
diff --git a/src/index.md b/src/index.md
index 5f3a1ed613..128b9c0179 100644
--- a/src/index.md
+++ b/src/index.md
@@ -51,10 +51,12 @@ Now let's begin!
 
 - [Testing](testing.html) - All sorts of testing in Rust.
 
-- [Meta](meta.html) - Documentation, Benchmarking.
-
 - [Unsafe Operations](unsafe.html)
 
+- [Compatibility](compatibility.html)
+
+- [Meta](meta.html) - Documentation, Benchmarking.
+
 
 [rust]: https://www.rust-lang.org/
 [install]: https://www.rust-lang.org/install.html