Write briefly about syntax extension in the syntax section

The currently existing syntax extension facilities don't really merit
their own section.

4 files changed, 27 insertions, 9 deletions

diff --git a/doc/tutorial/data.md b/doc/tutorial/data.md
index 0ae474aa54c..95ccb0ecec6 100644
--- a/doc/tutorial/data.md
+++ b/doc/tutorial/data.md
@@ -61,9 +61,10 @@ name as the field.
         {x, y}             { /* Simply bind the fields */ }
     }
 
-When you are not interested in all the fields of a record, a record
-pattern may end with `, _` (as in `{field1, _}`) to indicate that
-you're ignoring all other fields.
+The field names of a record do not have to appear in a pattern in the
+same order they appear in the type. When you are not interested in all
+the fields of a record, a record pattern may end with `, _` (as in
+`{field1, _}`) to indicate that you're ignoring all other fields.
 
 ## Tags
 
diff --git a/doc/tutorial/ext.md b/doc/tutorial/ext.md
deleted file mode 100644
index ff2589b8443..00000000000
--- a/doc/tutorial/ext.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# Syntax extension
-
-FIXME to be written
diff --git a/doc/tutorial/order b/doc/tutorial/order
index 7b66416f291..bf621816d47 100644
--- a/doc/tutorial/order
+++ b/doc/tutorial/order
@@ -8,6 +8,5 @@ args
 generic
 mod
 ffi
-ext
 task
 test
diff --git a/doc/tutorial/syntax.md b/doc/tutorial/syntax.md
index 8182cc11932..aa53932c382 100644
--- a/doc/tutorial/syntax.md
+++ b/doc/tutorial/syntax.md
@@ -1,7 +1,5 @@
 # Syntax Basics
 
-FIXME: briefly mention syntax extentions, #fmt
-
 ## Braces
 
 Assuming you've programmed in any C-family language (C++, Java,
@@ -307,3 +305,26 @@ written like this:
         #[cfg(target_os = "win32")];
         /* ... */
     }
+
+## Syntax extensions
+
+There are plans to support user-defined syntax (macros) in Rust. This
+currently only exists in very limited form.
+
+The compiler defines a few built-in syntax extensions. The most useful
+one is `#fmt`, a printf-style text formatting macro that is expanded
+at compile time.
+
+    std::io::writeln(#fmt("%s is %d", "the answer", 42));
+
+`#fmt` supports most of the directives that [printf][pf] supports, but
+will give you a compile-time error when the types of the directives
+don't match the types of the arguments.
+
+[pf]: http://en.cppreference.com/w/cpp/io/c/fprintf
+
+All syntax extensions look like `#word`. Another built-in one is
+`#env`, which will look up its argument as an environment variable at
+compile-time.
+
+    std::io::writeln(#env("PATH"));