Merge pull request #264 from toml-lang/newlines

Clarify whitespace and newline rules.

README.md

@@ -63,6 +63,7 @@ Spec
 * TOML is case sensitive.
 * A TOML file must contain only UTF-8 encoded Unicode characters.
 * Whitespace means tab (0x09) or space (0x20).
+* Newline means LF (0x0A) or CRLF (0x0D0A).
 
 Comment
 -------
@@ -117,26 +118,33 @@ purpose.
 Sometimes you need to express passages of text (e.g. translation files) or would
 like to break up a very long string into multiple lines. TOML makes this easy.
 **Multi-line basic strings** are surrounded by three quotation marks on each
-side and allow newlines. If the first character after the opening delimiter is a
-newline (`0x0A`), then it is trimmed. All other whitespace remains intact.
+side and allow newlines. A newline immediately following the opening delimiter
+will be trimmed. All other whitespace and newline characters remain intact.
 
 ```toml
-# The following strings are byte-for-byte equivalent:
-key1 = "One\nTwo"
-key2 = """One\nTwo"""
-key3 = """
-One
-Two"""
+key1 = """
+Roses are red
+Violets are blue"""
+```
+
+TOML parsers should feel free to normalize newline to whatever makes sense for
+their platform.
+
+```toml
+# On a Unix system, the above multi-line string will most likely be the same as:
+key2 = "Roses are red\nViolets are blue"
+
+# On a Windows system, it will most likely be equivalent to:
+key3 = "Roses are red\r\nViolets are blue"
 ```
 
 For writing long strings without introducing extraneous whitespace, end a line
 with a `\`. The `\` will be trimmed along with all whitespace (including
 newlines) up to the next non-whitespace character or closing delimiter. If the
-first two characters after the opening delimiter are a backslash and a newline
-(`0x5C0A`), then they will both be trimmed along with all whitespace (including
-newlines) up to the next non-whitespace character or closing delimiter. All of
-the escape sequences that are valid for basic strings are also valid for
-multi-line basic strings.
+first characters after the opening delimiter are a backslash and a newline, then
+they will both be trimmed along with all whitespace and newlines up to the next
+non-whitespace character or closing delimiter. All of the escape sequences that
+are valid for basic strings are also valid for multi-line basic strings.
 
 ```toml
 # The following strings are byte-for-byte equivalent:
@@ -178,9 +186,9 @@ Since there is no escaping, there is no way to write a single quote inside a
 literal string enclosed by single quotes. Luckily, TOML supports a multi-line
 version of literal strings that solves this problem. **Multi-line literal
 strings** are surrounded by three single quotes on each side and allow newlines.
-Like literal strings, there is no escaping whatsoever. If the first character
-after the opening delimiter is a newline (`0x0A`), then it is trimmed. All other
-content between the delimiters is interpreted as-is without modification.
+Like literal strings, there is no escaping whatsoever. A newline immediately
+following the opening delimiter will be trimmed. All other content between the
+delimiters is interpreted as-is without modification.
 
 ```toml
 regex2 = '''I [dw]on't need \d{2} apples'''
@@ -307,22 +315,21 @@ apart from arrays because arrays are only ever values.
 ```
 
 Under that, and until the next table or EOF are the key/values of that table.
-Keys are on the left of the equals sign and values are on the right. Keys start
-with the first character that isn't whitespace or `[` and end with the last 
-non-whitespace character before the equals sign. Keys cannot contain a `#` 
-character.  Key/value pairs within tables are not guaranteed to be in any 
-specific order.
+Keys are on the left of the equals sign and values are on the right. Whitespace
+is ignored around key names and values.
+
+Key names may only consist of non-whitespace, non-newline characters excluding
+`=`, `#`, `.`, `[`, and `]`.
+
+Key/value pairs within tables are not guaranteed to be in any specific order.
 
 ```toml
 [table]
 key = "value"
 ```
 
-You can indent keys and their values as much as you like. Tabs or spaces. Knock
-yourself out. Why, you ask? Because you can have nested tables. Snap.
-
-Nested tables are denoted by table names with dots in them. Name your tables
-whatever crap you please, just don't use `#`, `.`, `[` or `]`.
+Dots are prohibited in key names because dots are used to signify nested tables!
+Naming rules for each dot separated part are the same as for keys (see above).
 
 ```toml
 [dog.tater]