Editorial

Author: leebyron

spec/Section 2 -- Language.md

@@ -105,10 +105,9 @@ CommentChar :: SourceCharacter but not LineTerminator
 GraphQL source documents may contain single-line comments, starting with the
 {`#`} marker.
 
-A comment can contain any Unicode code point in {SourceCharacter} except
-{LineTerminator} so a comment always consists of all code points starting with
-the {`#`} character up to but not including the {LineTerminator} (or end of the
-source).
+A comment can contain any {SourceCharacter} except {LineTerminator} so a comment
+always consists of all {SourceCharacter} starting with the {`#`} character up to
+but not including the {LineTerminator} (or end of the source).
 
 Comments are {Ignored} like white space and may appear after any token, or
 before a {LineTerminator}, and have no significance to the semantic meaning of a
@@ -831,13 +830,10 @@ BlockStringCharacter ::
 - SourceCharacter but not `"""` or `\"""`
 - `\"""`
 
-{StringValue} is a sequence of characters wrapped in quotation marks (U+0022).
-(ex. {`"Hello World"`}). White space and other characters ignored in other parts
-of a GraphQL document are significant within a string value.
-
-A {StringValue} is evaluated to a Unicode text value, a sequence of Unicode
-scalar values, by interpreting all escape sequences using the static semantics
-defined below.
+A {StringValue} is evaluated to a _Unicode text value_, a sequence of _Unicode
+scalar value_, by interpreting all escape sequences using the static semantics
+defined below. White space and other characters ignored in other parts of a
+GraphQL document are significant within a string value.
 
 The empty string {`""`} must not be followed by another {`"`} otherwise it would
 be interpreted as the beginning of a block string. As an example, the source
@@ -846,29 +842,30 @@ empty strings.
 
 **Escape Sequences**
 
-In a single-quoted {StringValue}, any Unicode scalar value may be expressed
+In a single-quoted {StringValue}, any _Unicode scalar value_ may be expressed
 using an escape sequence. GraphQL strings allow both C-style escape sequences
 (for example `\n`) and two forms of Unicode escape sequences: one with a
 fixed-width of 4 hexadecimal digits (for example `\u000A`) and one with a
 variable-width most useful for representing a _supplementary character_ such as
 an Emoji (for example `\u{1F4A9}`).
 
 The hexadecimal number encoded by a Unicode escape sequence must describe a
-Unicode scalar value, otherwise parsing should stop with an early error. For
-example both sources `"\uDEAD"` and `"\u{110000}"` should not be considered
-valid {StringValue}.
+Unicode scalar value, otherwise must result in a parse error. For example both
+sources `"\uDEAD"` and `"\u{110000}"` should not be considered valid
+{StringValue}.
 
 Escape sequences are only meaningful within a single-quoted string. Within a
 block string, they are simply that sequence of characters (for example
 `"""\n"""` represents the Unicode text [U+005C, U+006E]). Within a comment an
 escape sequence is not a significant sequence of characters. They may not appear
 elsewhere in a GraphQL document.
 
-Since {StringCharacter} must not contain some characters, escape sequences must
-be used to represent these characters. All other escape sequences are optional
-and unescaped non-ASCII Unicode characters are allowed within strings. If using
-GraphQL within a system which only supports ASCII, then escape sequences may be
-used to represent all Unicode characters outside of the ASCII range.
+Since {StringCharacter} must not contain some code points directly (for example,
+a {LineTerminator}), escape sequences must be used to represent them. All other
+escape sequences are optional and unescaped non-ASCII Unicode characters are
+allowed within strings. If using GraphQL within a system which only supports
+ASCII, then escape sequences may be used to represent all Unicode characters
+outside of the ASCII range.
 
 For legacy reasons, a _supplementary character_ may be escaped by two
 fixed-width unicode escape sequences forming a _surrogate pair_. For example the
@@ -880,9 +877,10 @@ such code points.
 When producing a {StringValue}, implementations should use escape sequences to
 represent non-printable control characters (U+0000 to U+001F and U+007F to
 U+009F). Other escape sequences are not necessary, however an implementation may
-use escape sequences to represent any other range of code points. If an
-implementation chooses to escape a _supplementary character_, it should not use
-a fixed-width surrogate pair unicode escape sequence.
+use escape sequences to represent any other range of code points (for example,
+when producing ASCII-only output). If an implementation chooses to escape a
+_supplementary character_, it should only use a variable-width unicode escape
+sequence.
 
 **Block Strings**
 
@@ -940,11 +938,11 @@ string.
 
 **Static Semantics**
 
-A {StringValue} describes a Unicode text value, a sequence of *Unicode scalar
-value*s. These semantics describe how to apply the {StringValue} grammar to a
+A {StringValue} describes a Unicode text value, a sequence of _Unicode scalar
+value_. These semantics describe how to apply the {StringValue} grammar to a
 source text to evaluate a Unicode text. Errors encountered during this
 evaluation are considered a failure to apply the {StringValue} grammar to a
-source and result in a parsing error.
+source and must result in a parsing error.
 
 StringValue :: `""`
 
@@ -965,7 +963,7 @@ StringCharacter :: `\u` EscapedUnicode
   within {EscapedUnicode}.
 - Assert {value} is a within the _Unicode scalar value_ range (>= 0x0000 and <=
   0xD7FF or >= 0xE000 and <= 0x10FFFF).
-- Return the code point {value}.
+- Return the _Unicode scalar value_ {value}.
 
 StringCharacter :: `\u` HexDigit HexDigit HexDigit HexDigit `\u` HexDigit
 HexDigit HexDigit HexDigit
@@ -981,8 +979,8 @@ HexDigit HexDigit HexDigit
 - Otherwise:
   - Assert {leadingValue} is within the _Unicode scalar value_ range.
   - Assert {trailingValue} is within the _Unicode scalar value_ range.
-  - Return the sequence of the code point {leadingValue} followed by the code
-    point {trailingValue}.
+  - Return the sequence of the _Unicode scalar value_ {leadingValue} followed by
+    the _Unicode scalar value_ {trailingValue}.
 
 Note: If both escape sequences encode a _Unicode scalar value_, then this
 semantic is identical to applying the prior semantic on each fixed-width escape
@@ -991,19 +989,19 @@ value_.
 
 StringCharacter :: `\` EscapedCharacter
 
-- Return the code point represented by {EscapedCharacter} according to the table
-  below.
-
-| Escaped Character | Code Point | Character Name               |
-| ----------------- | ---------- | ---------------------------- |
-| {`"`}             | U+0022     | double quote                 |
-| {`\`}             | U+005C     | reverse solidus (back slash) |
-| {`/`}             | U+002F     | solidus (forward slash)      |
-| {`b`}             | U+0008     | backspace                    |
-| {`f`}             | U+000C     | form feed                    |
-| {`n`}             | U+000A     | line feed (new line)         |
-| {`r`}             | U+000D     | carriage return              |
-| {`t`}             | U+0009     | horizontal tab               |
+- Return the _Unicode scalar value_ represented by {EscapedCharacter} according
+  to the table below.
+
+| Escaped Character | Scalar Value | Character Name               |
+| ----------------- | ------------ | ---------------------------- |
+| {`"`}             | U+0022       | double quote                 |
+| {`\`}             | U+005C       | reverse solidus (back slash) |
+| {`/`}             | U+002F       | solidus (forward slash)      |
+| {`b`}             | U+0008       | backspace                    |
+| {`f`}             | U+000C       | form feed                    |
+| {`n`}             | U+000A       | line feed (new line)         |
+| {`r`}             | U+000D       | carriage return              |
+| {`t`}             | U+0009       | horizontal tab               |
 
 StringValue :: `"""` BlockStringCharacter\* `"""`