Fix specification of multiline strings.

docs/language/dartLangSpec.tex

Index: docs/language/dartLangSpec.tex
diff --git a/docs/language/dartLangSpec.tex b/docs/language/dartLangSpec.tex
index 158a10f177ce7bf2b8baa9cd3241ba394372cecb..c1e7c84a84dde07622218fbf0a5d0084dd8b27fe 100644
--- a/docs/language/dartLangSpec.tex
+++ b/docs/language/dartLangSpec.tex
@@ -27,6 +27,7 @@
 % - An await-for loop only pauses the subscription if it does something async.
 % - Assert statements may now also include a "message" operand.
 % - The Null type is now considered a subtype of all types in most cases.
+% - Specify what NEWLINE means in multiline strings.
 %
 % 1.14
 % - The call "C()" where "C" is a class name, is a now compile-time error.
@@ -2807,7 +2808,7 @@ This decision was made for compatibility with web browsers and Javascript. Earli
 \end{grammar}
 
 \LMHash{}
-A string can be either a sequence of single line strings or a multiline string.
+A string can be a sequence of single line strings and multiline strings.
 
 \begin{grammar}
  {\bf singleLineString:}`{\escapegrammar \code{"}}' stringContentDQ* `{\escapegrammar \code{"}}';
@@ -2828,10 +2829,7 @@ Hence, `abc' and ``abc'' are both legal strings, as are `He said ``To be or not
 }
 
 \LMHash{}
-Adjacent
-%single line
-strings are implicitly concatenated to form a single string literal.
-%, and so are adjacent multiline strings, but the two forms may not be mixed.
+Adjacent strings are implicitly concatenated to form a single string literal.
 
 
 \commentary{Here is an example}
@@ -2851,7 +2849,7 @@ print("A simple sum: 2 + 2 = " +
 \end{dartCode}
 
 \rationale{ which this prints  'A simple sum: 2 + 2 = 22' rather than 'A simple sum: 2 + 2 = 4'.
-However, the use the concatenation operation is still  discouraged for efficiency reasons. Instead, the recommended Dart idiom is to use string interpolation.
+However, the use the concatenation operation is still discouraged for efficiency reasons. Instead, the recommended Dart idiom is to use string interpolation.

[eernst, 2017/01/30 10:40:28]

'the use [of?] the'

 }
 
 \begin{dartCode}
@@ -2876,22 +2874,22 @@ print("A simple sum: 2 + 2 =  \$\{2+2\}");
 
 
 \begin{grammar}
- {\bf multilineString:}`{\escapegrammar \texttt{"""}}' stringContentTDQ*   `{\escapegrammar \texttt{"""}}';
-      `{\escapegrammar \code{'}\code{'}\code{'}}' stringContentTSQ* `{\escapegrammar \code{'}\code{'}\code{'}}';
-      `r' `{\escapegrammar \texttt{"""}}'  (\~{} `{\escapegrammar \texttt{"""}}')*   `{\escapegrammar \texttt{"""}}';
-      `r' `{\escapegrammar \code{'}\code{'}\code{'}}' (\~{} `{\escapegrammar \code{'}\code{'}\code{'}}')* `{\escapegrammar \code{'}\code{'}\code{'}}'
-    .
+  {\bf multilineString:}`{\escapegrammar \texttt{"""}}' stringContentTDQ*   `{\escapegrammar \texttt{"""}}';

[eernst, 2017/01/30 10:40:28]

Might as well fix the triple space issue here.

[Lasse Reichstein Nielsen, 2017/01/30 12:03:10]

Done.

+    `{\escapegrammar \code{'}\code{'}\code{'}}' stringContentTSQ* `{\escapegrammar \code{'}\code{'}\code{'}}';

[eernst, 2017/01/30 10:40:28]

Having touched this, couldn't we simplify it to `\code{'''}` rather than
repeating `\code` three times? Does `''` somehow encode `"`?

[Lasse Reichstein Nielsen, 2017/01/30 12:03:10]

It does exactly that. The `` is the left-quote and '' is the right-quote.

+    `r' `{\escapegrammar \texttt{"""}}'  (\~{} `{\escapegrammar \texttt{"""}}')*   `{\escapegrammar \texttt{"""}}';

[eernst, 2017/01/30 10:40:28]

Double space again.

[Lasse Reichstein Nielsen, 2017/01/30 12:03:10]

Done.

+    `r' `{\escapegrammar \code{'}\code{'}\code{'}}' (\~{} `{\escapegrammar \code{'}\code{'}\code{'}}')* `{\escapegrammar \code{'}\code{'}\code{'}}'

[eernst, 2017/01/30 10:40:28]

Same potential simplification of 3*code.

[Lasse Reichstein Nielsen, 2017/01/30 12:03:10]

So again no.

+  .
 
 
-    {\bf ESCAPE\_SEQUENCE:} `$\backslash$ n';
+  {\bf ESCAPE\_SEQUENCE:} `$\backslash$ n';
     `$\backslash$ r';
-   `$\backslash$ f';
-   `$\backslash$ b';
-  `$\backslash$ t';
-   `$\backslash$ v';
-  `$\backslash$ x' HEX\_DIGIT HEX\_DIGIT;
-   `$\backslash$ u' HEX\_DIGIT HEX\_DIGIT HEX\_DIGIT HEX\_DIGIT;
-   `$\backslash$ u\{' HEX\_DIGIT\_SEQUENCE `\}'
+    `$\backslash$ f';
+    `$\backslash$ b';
+    `$\backslash$ t';
+    `$\backslash$ v';
+    `$\backslash$ x' HEX\_DIGIT HEX\_DIGIT;
+    `$\backslash$ u' HEX\_DIGIT HEX\_DIGIT HEX\_DIGIT HEX\_DIGIT;
+    `$\backslash$ u\{' HEX\_DIGIT\_SEQUENCE `\}'
   .
 
 {\bf HEX\_DIGIT\_SEQUENCE:}
@@ -2901,12 +2899,12 @@ print("A simple sum: 2 + 2 =  \$\{2+2\}");
 \end{grammar}
 
 \LMHash{}
-Multiline strings are delimited by either matching triples of single quotes or matching triples of double quotes. If the first line of a multiline string consists solely of the whitespace characters defined by the production {\em WHITESPACE}  \ref{lexicalRules}), possibly prefixed by $\backslash$, then that line is ignored, including the new line at its end.
+Multiline strings are delimited by either matching triples of single quotes or matching triples of double quotes. If the first line of a multiline string consists solely of the whitespace characters defined by the production {\em WHITESPACE}  \ref{lexicalRules}), possibly prefixed by $\backslash$, then that line is ignored, including the newline at its end.
 
 
- \rationale{
- The idea is to ignore whitespace, where whitespace is defined as tabs, spaces and newlines. These can be represented directly, but since for most characters prefixing by backslash is an identity, we allow those forms as well.
- }
+\rationale{
+The idea is to ignore whitespace, where whitespace is defined as tabs, spaces and the final newline. These can be represented directly, but since for most characters prefixing by backslash is an identity in a non-raw string, we allow those forms as well.

[eernst, 2017/01/30 10:40:28]

This might be better: 'the final newline' --> 'the newline at the end of the
first line'. With this, we avoid readers thinking that this is about the
multi-line string as a whole (so there may be several newline characters and the
'final' one could be in line 7). This is based on the assumption that the topic
is the first line of the multi-line string. If we don't agree on that assumption
then some other clarification is needed. ;-)

[Lasse Reichstein Nielsen, 2017/01/30 12:03:10]

Rewritten to:
The idea is to ignore a whitespace-only first line, where ...

+}
 
  % could be clearer. Is the first line in  """\t
  %    """ ignored not. It depends if we mean whitespace before escapes are interpreted,
@@ -2915,7 +2913,7 @@ Multiline strings are delimited by either matching triples of single quotes or m
 \LMHash{}
 Strings support escape sequences for special characters. The escapes are:
 \begin{itemize}
-\item  $\backslash$n for newline, equivalent to $\backslash$x0A.
+\item $\backslash$n for newline, equivalent to $\backslash$x0A.
 \item $\backslash$r for carriage return, equivalent to $\backslash$x0D.
 \item $\backslash$f for form feed, equivalent to $\backslash$x0C.
 \item $\backslash$b for backspace, equivalent to $\backslash$x08.
@@ -2931,6 +2929,9 @@ $\backslash$u\{$HEX\_DIGIT_1$ $HEX\_DIGIT_2$\}.
  \end{itemize}
 
 \LMHash{}
+Multiline strings can contain newlines. A carriage return character followed by a newline character is considered a single newline. Newlines in multiline string literals contribute a single newline character to the string value.

[eernst, 2017/01/30 10:40:28]

We need to make it obvious that these 'newlines' are "raw", i.e., that they are
not escape sequences in the string. Maybe it would be good for the general
readability to extend it a bit: `can contain raw line breaking character
sequences (not escape sequences).` This avoids the use of the word 'newlines',
which means that we can include `\r` and `\r\n` without conflicting with the
identity '\n' == '\x0A'.

We can then continue with `The following line breaking character sequences are
recognized: \n, \r, \r\n. Each of them contributes a single newline (\n) to the
value of the multi-line string.`.

Then we also avoid `newline character` as if every other occurrence of `newline`
could mean anything else. ;-)

[Lasse Reichstein Nielsen, 2017/01/30 12:03:10]

I have rewritten this a lot - I now use "line break" about what the production
NEWLINE defines, and talk about line breaks, not newlines, inside multiline
strings.

+
+\LMHash{}
 Any string may be prefixed with the character `r', indicating that it is a {\em raw string}, in which case no escapes or interpolations are recognized.

[eernst, 2017/01/30 10:40:28]

And what does '\r\n' mean when it is encountered in a raw multi-line string
literal? Same processing, I'd assume, but it would be a reader-friendly gesture
to confirm this suspicion also for raw strings.

[Lasse Reichstein Nielsen, 2017/01/30 12:03:10]

I've moved this section above the previous one, so the line-breaking stuff
doesn't interrupt the escape stuff. Then it shouldn't be as important to say
that line-breaking isn't escape-stuff.

 
 \LMHash{}
@@ -2959,7 +2960,8 @@ It is a compile-time error if a non-raw string literal contains a character sequ
     .
 
 {\bf NEWLINE:}$\backslash$ n;
-      $\backslash$ r
+      $\backslash$ r;
+      $\backslash$ r $\backslash$ n
     .
 
  \end{grammar}