Improvements to syntax reference

1 files changed, 28 insertions, 22 deletions

diff --git a/lib/elixir/pages/Syntax Reference.md b/lib/elixir/pages/Syntax Reference.md
index e3de5826d..97bfc224d 100644
--- a/lib/elixir/pages/Syntax Reference.md
+++ b/lib/elixir/pages/Syntax Reference.md
@@ -96,7 +96,7 @@ Charlists are always represented as themselves in the AST.
 
 Variables in Elixir must start with underscore or a non-combining Unicode character that is not in uppercase or titlecase. The variable may continue using a sequence of Unicode characters, including numbers and underscore. Variables may end in `?` or `!`. See [Unicode Syntax](unicode-syntax.html) for a formal specification. Unicode characters require OTP 20.
 
-[Elixir's naming conventions](naming-conventions.html) proposes variables to be in `snake_case` format.
+[Elixir's naming conventions](naming-conventions.html) recommend variables to be in `snake_case` format.
 
 Variables are represented by three-element tuples:
 
@@ -109,7 +109,9 @@ end
 
 ### Non-qualified calls
 
-Non-qualified calls, such as `add(1, 2)`, must start with lowercase characters which may be followed by any ASCII letter, number or underscore. Calls may end in `?` or `!`. [Elixir's naming conventions](naming-conventions.html) proposes function names to be in `snake_case` format.
+Non-qualified calls, such as `add(1, 2)`, must start with underscore or a non-combining Unicode character that is not in uppercase or titlecase. The call may continue using a sequence of Unicode characters, including numbers and underscore. Calls may end in `?` or `!`. See [Unicode Syntax](unicode-syntax.html) for a formal specification. Unicode characters require OTP 20.
+
+[Elixir's naming conventions](naming-conventions.html) recommend calls to be in `snake_case` format.
 
 Non-qualified calls are represented by three-element tuples:
 
@@ -151,9 +153,28 @@ end
 
 Many other Elixir constructs, such as `=`, `when`, `&` and `@` are simply treated as operators. See [the Operators page](operators.html) for a full reference.
 
+### Qualified calls (remote calls)
+
+Qualified calls, such as `Math.add(1, 2)`, must start with underscore or a non-combining Unicode character that is not in uppercase or titlecase. The call may continue using a sequence of Unicode characters, including numbers and underscore. Calls may end in `?` or `!`. See [Unicode Syntax](unicode-syntax.html) for a formal specification. Unicode characters require OTP 20.
+
+[Elixir's naming conventions](naming-conventions.html) recommend calls to be in `snake_case` format.
+
+For qualified calls, Elixir also allows the function name to be written between double- or single-quotes, allowing calls such as `Math."++add++"(1, 2)`. Operators can be used as qualified calls without a need for quote, such as `Kernel.+(1, 2)`.
+
+Qualified calls are represented as a tuple with three elements in the AST where the first element is the a tuple reprsenting the dot:
+
+```elixir
+quote do
+  :foo.bar(1, 2)
+end
+#=> {{:., [], [:foo, :bar]}, [], [1, 2]}
+```
+
 ### Aliases
 
-Aliases are constructs that expand to atoms at compile-time. The alias `String` expands to the atom `:"Elixir.String"`. Aliases must start with an uppercase character which may be followed by any ASCII letter, number, or underscore. [Elixir's naming conventions](naming-conventions.html) propose aliases to be in `CamelCase` format.
+Aliases are constructs that expand to atoms at compile-time. The alias `String` expands to the atom `:"Elixir.String"`. Aliases must start with an ASCII uppercase character which may be followed by any ASCII letter, number, or underscore. Non-ASCII characters are not supported in aliases.
+
+[Elixir's naming conventions](naming-conventions.html) recommend aliases to be in `CamelCase` format.
 
 Aliases are represented by an `__aliases__` call with each segment separated by dot as an argument:
 
@@ -169,22 +190,7 @@ end
 #=> {:__aliases__, [], [{:__MODULE__, [], Elixir}, :Bar, :Baz]}
 ```
 
-All arguments, except the first, will be atoms.
-
-### Qualified calls (remote calls)
-
-Qualified calls, such as `Math.add(1, 2)`, must start with lowercase characters which may be followed by any ASCII letter, number or underscore. Calls may end in `?` or `!`. [Elixir's naming conventions](naming-conventions.html) propose function names to be in `snake_case` format.
-
-For qualified calls, Elixir also allows the function name to be written between double- or single-quotes, allowing calls such as `Math."++add++"(1, 2)`. Operators can be used as qualified calls without a need for quote, such as `Kernel.+(1, 2)`.
-
-Qualified calls are represented as a tuple with three elements in the AST where the first element is the a tuple reprsenting the dot:
-
-```elixir
-quote do
-  :foo.bar(1, 2)
-end
-#=> {{:., [], [:foo, :bar]}, [], [1, 2]}
-```
+All arguments, except the first, are guaranteed to be atoms.
 
 ### Data structures
 
@@ -329,7 +335,7 @@ Elixir allows integers to contain `_` to separate digits and provides convenienc
 #=> 233 (Unicode codepoint)
 ```
 
-Those constructs exist only at the syntax level. All of the representations above are represented as integers in the AST.
+Those constructs exist only at the syntax level. All of the examples above are represented as integers in the AST.
 
 ### Optional parentheses
 
@@ -485,7 +491,7 @@ Inside `do`/`end` blocks you may introduce other keywords, such as `else` used i
 
 You can see them being used in constructs such as `receive`, `try`, and others.
 
-## Conclusion
+## Summary
 
 This document provides a quick reference to Elixir syntax, exploring the simplicity behind its AST and documenting the base constructs with their AST equivalents.
 
@@ -507,4 +513,4 @@ defmodule(Math, [
 ])
 ```
 
-The mapping between code and data (the underlying AST) is what allows Elixir to implement `defmodule`, `def`, `if`, and friends in Elixir itself. Making the constructs available for building the language also accessible to developers who want to extend the language to new domains.
+The mapping between code and data (the underlying AST) is what allows Elixir to implement `defmodule`, `def`, `if`, and others in Elixir itself. Elixir makes the constructs available for building the language itself also accessible to developers who want to extend the language to new domains.