Add grammar comments related to block scalar productions

Author: ingydotnet

.gitignore

@@ -1,2 +1,3 @@
 /node_modules/
 /package-lock.json
+/yaml-spec-1.2-patch.yaml.orig

Makefile

@@ -30,6 +30,7 @@ comments: $(SPEC12_COMMENTS)
 
 clean:
 	rm -fr node_modules
+	rm -f package-lock.json yaml-spec-1.2-patch.yaml.orig
 
 $(SPEC12_TXT):
 	lynx --dump $(SPEC12_URL) > $@

yaml-spec-1.2-comments.yaml

@@ -333,6 +333,38 @@
 '154': |
   The (max) function tells the parser that it can consider only the given
   number of characters to match the next rule.
+'162': |
+  This production is misleading. It claims to be called with 2 arguments, m and
+  t, but it is not called with any arguments. In reality it is supposed to
+  *create* 2 state variables m and t.
+
+  It should actually be:
+
+  c-b-block-header ::=
+    ( ( c-indentation-indicator
+    c-chomping-indicator )
+    | ( c-chomping-indicator
+    c-indentation-indicator ) )
+    s-b-comment
+'163': |
+  This production should not receive any arguments. It creates a variable that
+  indicates the amount of indentation for a literal scalar.
+
+  It should actually be:
+
+  c-indentation-indicator ::=
+    ( ns-dec-digit => m = ns-dec-digit - x:30 )
+    ( <empty> => m = auto-detect() )
+'164': |
+  This production should not receive any arguments. It creates a variable that
+  indicates how trailing whitespace should be interpreted.
+
+  It should actually be:
+
+  c-chomping-indicator ::=
+    ( '-' => t = strip )
+    ( '+' => t = keep )
+    ( <empty> => t = clip )
 '183': |
   The <auto-detect-indent> rule is a "special" rule that finds the new level of
   indentation and returns the number of columns. The level must be greater than

yaml-spec-1.2-patch.yaml

@@ -2519,6 +2519,21 @@ ns-flow-node:
 ##### 8.1.1. Block Scalar Headers
 
 
+#===============================================================================
+# This production is misleading. It claims to be called with 2 arguments, m and
+# t, but it is not called with any arguments. In reality it is supposed to
+# *create* 2 state variables m and t.
+#
+# It should actually be:
+#
+# c-b-block-header ::=
+#   ( ( c-indentation-indicator
+#   c-chomping-indicator )
+#   | ( c-chomping-indicator
+#   c-indentation-indicator ) )
+#   s-b-comment
+#===============================================================================
+
 :162: c-b-block-header
 # c-b-block-header(m,t) ::=
 #   ( ( c-indentation-indicator(m)
@@ -2541,6 +2556,17 @@ c-b-block-header:
 
 
 
+#===============================================================================
+# This production should not receive any arguments. It creates a variable that
+# indicates the amount of indentation for a literal scalar.
+#
+# It should actually be:
+#
+# c-indentation-indicator ::=
+#   ( ns-dec-digit => m = ns-dec-digit - x:30 )
+#   ( <empty> => m = auto-detect() )
+#===============================================================================
+
 :163: c-indentation-indicator
 # c-indentation-indicator(m) ::=
 #   ( ns-dec-digit => m = ns-dec-digit - x:30 )
@@ -2556,6 +2582,18 @@ c-indentation-indicator:
 
 
 
+#===============================================================================
+# This production should not receive any arguments. It creates a variable that
+# indicates how trailing whitespace should be interpreted.
+#
+# It should actually be:
+#
+# c-chomping-indicator ::=
+#   ( '-' => t = strip )
+#   ( '+' => t = keep )
+#   ( <empty> => t = clip )
+#===============================================================================
+
 :164: c-chomping-indicator
 # c-chomping-indicator(t) ::=
 #   ( '-' => t = strip )

yaml-spec-1.2.yaml

@@ -2519,6 +2519,21 @@ ns-flow-node:
 ##### 8.1.1. Block Scalar Headers
 
 
+#===============================================================================
+# This production is misleading. It claims to be called with 2 arguments, m and
+# t, but it is not called with any arguments. In reality it is supposed to
+# *create* 2 state variables m and t.
+#
+# It should actually be:
+#
+# c-b-block-header ::=
+#   ( ( c-indentation-indicator
+#   c-chomping-indicator )
+#   | ( c-chomping-indicator
+#   c-indentation-indicator ) )
+#   s-b-comment
+#===============================================================================
+
 :162: c-b-block-header
 # c-b-block-header(m,t) ::=
 #   ( ( c-indentation-indicator(m)
@@ -2541,6 +2556,17 @@ c-b-block-header:
 
 
 
+#===============================================================================
+# This production should not receive any arguments. It creates a variable that
+# indicates the amount of indentation for a literal scalar.
+#
+# It should actually be:
+#
+# c-indentation-indicator ::=
+#   ( ns-dec-digit => m = ns-dec-digit - x:30 )
+#   ( <empty> => m = auto-detect() )
+#===============================================================================
+
 :163: c-indentation-indicator
 # c-indentation-indicator(m) ::=
 #   ( ns-dec-digit => m = ns-dec-digit - x:30 )
@@ -2556,6 +2582,18 @@ c-indentation-indicator:
 
 
 
+#===============================================================================
+# This production should not receive any arguments. It creates a variable that
+# indicates how trailing whitespace should be interpreted.
+#
+# It should actually be:
+#
+# c-chomping-indicator ::=
+#   ( '-' => t = strip )
+#   ( '+' => t = keep )
+#   ( <empty> => t = clip )
+#===============================================================================
+
 :164: c-chomping-indicator
 # c-chomping-indicator(t) ::=
 #   ( '-' => t = strip )