From 7cd43d8ad42b61948d2c571c202ee9b3d210e153 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ingy=20d=C3=B6t=20Net?= <ingy@ingy.net>
Date: Thu, 25 Jan 2018 13:51:15 -0800
Subject: [PATCH] [yaml/en] Use preferred style; add missing uses

* YAML allows literal tabs in content, but not indentation.
* Two space indent always preferred.
  * Note: YAML dumpers always use 2 space by default.
* '- ...' doesn't need extra indentation.
  * Note: YAML dumpers don't use extra indentation.
* There was no mention of single quoted strings. They are preferred
  and should be used except when double quote semantics are actually
  required. (Best practice).
* Add flow form example for sets: `{a, b, c}`
* Show collapsed form of seq-in-seq: `- - - foo`.
---
 yaml.html.markdown | 81 +++++++++++++++++++++++++---------------------
 1 file changed, 44 insertions(+), 37 deletions(-)

diff --git a/yaml.html.markdown b/yaml.html.markdown
index 3b32a069..52658453 100644
--- a/yaml.html.markdown
+++ b/yaml.html.markdown
@@ -2,8 +2,8 @@
 language: yaml
 filename: learnyaml.yaml
 contributors:
-  - ["Adam Brenecki", "https://github.com/adambrenecki"]
-  - ["Suhas SG", "https://github.com/jargnar"]
+- [Adam Brenecki, 'https://github.com/adambrenecki']
+- [Suhas SG, 'https://github.com/jargnar']
 ---
 
 YAML is a data serialisation language designed to be directly writable and
@@ -11,7 +11,7 @@ readable by humans.
 
 It's a strict superset of JSON, with the addition of syntactically
 significant newlines and indentation, like Python. Unlike Python, however,
-YAML doesn't allow literal tab characters at all.
+YAML doesn't allow literal tab characters for indentation.
 
 ```yaml
 # Comments in YAML look like this.
@@ -32,8 +32,10 @@ boolean: true
 null_value: null
 key with spaces: value
 # Notice that strings don't need to be quoted. However, they can be.
-however: "A string, enclosed in quotes."
-"Keys can be quoted too.": "Useful if you want to put a ':' in your key."
+however: 'A string, enclosed in quotes.'
+'Keys can be quoted too.': "Useful if you want to put a ':' in your key."
+single quotes: 'have ''one'' escape pattern'
+double quotes: "have many: \", \0, \t, \u263A, \x0d\x0a == \r\n, and more."
 
 # Multiple-line strings can be written either as a 'literal block' (using |),
 # or a 'folded block' (using '>').
@@ -59,12 +61,12 @@ folded_style: >
 # COLLECTION TYPES #
 ####################
 
-# Nesting is achieved by indentation.
+# Nesting uses indentation. 2 space indent is preferred (but not required).
 a_nested_map:
-    key: value
-    another_key: Another Value
-    another_nested_map:
-        hello: hello
+  key: value
+  another_key: Another Value
+  another_nested_map:
+    hello: hello
 
 # Maps don't have to have string keys.
 0.25: a float key
@@ -72,8 +74,8 @@ a_nested_map:
 # Keys can also be complex, like multi-line objects
 # We use ? followed by a space to indicate the start of a complex key.
 ? |
-    This is a key
-    that has multiple lines
+  This is a key
+  that has multiple lines
 : and this is its value
 
 # YAML also allows mapping between sequences with the complex key syntax
@@ -83,22 +85,26 @@ a_nested_map:
   - Real Madrid
 : [ 2001-01-01, 2002-02-02 ]
 
-# Sequences (equivalent to lists or arrays) look like this:
+# Sequences (equivalent to lists or arrays) look like this
+# (note that the '-' counts as indentation):
 a_sequence:
-    - Item 1
-    - Item 2
-    - 0.5 # sequences can contain disparate types.
-    - Item 4
-    - key: value
-      another_key: another_value
-    -
-        - This is a sequence
-        - inside another sequence
+- Item 1
+- Item 2
+- 0.5 # sequences can contain disparate types.
+- Item 4
+- key: value
+  another_key: another_value
+-
+  - This is a sequence
+  - inside another sequence
+- - - Nested sequence indicators
+    - can be collapsed
 
 # Since YAML is a superset of JSON, you can also write JSON-style maps and
 # sequences:
 json_map: {"key": "value"}
 json_seq: [3, 2, 1, "takeoff"]
+and quotes are optional: {key: [3, 2, 1, takeoff]}
 
 #######################
 # EXTRA YAML FEATURES #
@@ -111,15 +117,15 @@ other_anchor: *anchor_name
 
 # Anchors can be used to duplicate/inherit properties
 base: &base
-    name: Everyone has same name
+  name: Everyone has same name
 
 foo: &foo
-    <<: *base
-    age: 10
+  <<: *base
+  age: 10
 
 bar: &bar
-    <<: *base
-    age: 20
+  <<: *base
+  age: 20
 
 # foo and bar would also have name: Everyone has same name
 
@@ -147,22 +153,23 @@ date: 2002-12-14
 # The !!binary tag indicates that a string is actually a base64-encoded
 # representation of a binary blob.
 gif_file: !!binary |
-    R0lGODlhDAAMAIQAAP//9/X17unp5WZmZgAAAOfn515eXvPz7Y6OjuDg4J+fn5
-    OTk6enp56enmlpaWNjY6Ojo4SEhP/++f/++f/++f/++f/++f/++f/++f/++f/+
-    +f/++f/++f/++f/++f/++SH+Dk1hZGUgd2l0aCBHSU1QACwAAAAADAAMAAAFLC
-    AgjoEwnuNAFOhpEMTRiggcz4BNJHrv/zCFcLiwMWYNG84BwwEeECcgggoBADs=
+  R0lGODlhDAAMAIQAAP//9/X17unp5WZmZgAAAOfn515eXvPz7Y6OjuDg4J+fn5
+  OTk6enp56enmlpaWNjY6Ojo4SEhP/++f/++f/++f/++f/++f/++f/++f/++f/+
+  +f/++f/++f/++f/++f/++SH+Dk1hZGUgd2l0aCBHSU1QACwAAAAADAAMAAAFLC
+  AgjoEwnuNAFOhpEMTRiggcz4BNJHrv/zCFcLiwMWYNG84BwwEeECcgggoBADs=
 
 # YAML also has a set type, which looks like this:
 set:
-    ? item1
-    ? item2
-    ? item3
+  ? item1
+  ? item2
+  ? item3
+or: {item1, item2, item3}
 
 # Like Python, sets are just maps with null values; the above is equivalent to:
 set2:
-    item1: null
-    item2: null
-    item3: null
+  item1: null
+  item2: null
+  item3: null
 ```
 
 ### More Resources