From bd5aada8c9e6d5da3a7a4deddab1343c8b9c1bc7 Mon Sep 17 00:00:00 2001
From: Lee Byron <lee@leebyron.com>
Date: Thu, 21 Dec 2017 14:57:27 -0800
Subject: [PATCH] Additional note about formatting of block strings for
 legibility

---
 spec/Section 2 -- Language.md | 21 +++++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

diff --git a/spec/Section 2 -- Language.md b/spec/Section 2 -- Language.md
index 3b6da6d97..2e3580ba5 100644
--- a/spec/Section 2 -- Language.md	
+++ b/spec/Section 2 -- Language.md	
@@ -731,7 +731,7 @@ indentation and blank initial and trailing lines via {BlockStringValue()}.
 
 For example, the following operation containing a block string:
 
-```graphql
+```graphql example
 mutation {
   sendEmail(message: """
     Hello,
@@ -745,12 +745,29 @@ mutation {
 
 Is identical to the standard quoted string:
 
-```graphql
+```graphql example
 mutation {
   sendEmail(message: "Hello,\n  World!\n\nYours,\n  GraphQL.")
 }
 ```
 
+Since block string values strip leading and trailing empty lines, there is no
+single canonical printed block string for a given value. Because block strings
+typically represent freeform text, it is considered easier to read if they begin
+and end with an empty line.
+
+```graphql example
+"""
+This starts with and ends with an empty line,
+which makes it easier to read.
+"""
+```
+
+```graphql counter-example
+"""This does not start with or end with any empty lines,
+which makes it a little harder to read."""
+```
+
 Note: If non-printable ASCII characters are needed in a string value, a standard
 quoted string with appropriate escape sequences must be used instead of a
 block string.