grammar changes

SPEC.md

@@ -695,18 +695,19 @@ can be nested.
 
 Finally, a special kind of comment called a "slashdash", denoted by `/-`, can
 be used to comment out entire _components_ of a KDL document logically, and
-have those elements be treated as whitespace.
+have those elements not be included as part of the parsed document data.
 
 Slashdash comments can be used before the following, including before their type
 annotations, if present:
 
-* A [Node](#node) name: the entire Node is
+* A [Node](#node): the entire Node is treated as Whitespace, including all
-  treated as Whitespace, including all props, args, and children.
+  props, args, and children.
-* A node [Argument](#argument): the Argument value is treated as Whitespace.
+* An [Argument](#argument): the Argument value is treated as Whitespace.
 * A [Property](#property) key: the entire property, including both key and value,
   is treated as Whitespace. A slashdash of just the property value is not allowed.
-* A [Children Block](#children-block): the entire block, including all children within,
+* A [Children Block](#children-block): the entire block, including all
-  is treated as Whitespace. Other node items may follow a slashdashed children block.
+  children within, is treated as Whitespace. Only other children blocks, whether
+  slashdashed or not, may follow a slashdashed children block.
 
 ### Newline
 
@@ -752,25 +753,29 @@ document := bom? nodes
 
 nodes := (line-space* node)* line-space*
 
-plain-line-space := newline | ws | single-line-comment
+slashdash := '/-'
-plain-node-space := ws* escline ws* | ws+
 
-line-space := plain-line-space+ | '/-' plain-node-space* node
+// Whitespace where newlines are allowed.
-node-space := plain-node-space+ ('/-' plain-node-space* (node-prop-or-arg | node-children))?
+line-space := newline | ws | single-line-comment
 
-required-node-space := node-space* plain-node-space+
+// Whitespace within nodes, where newline-ish things must be esclined.
-optional-node-space := node-space*
+node-space := ws* escline ws* | ws+
 
-base-node := type? optional-node-space string (required-node-space node-prop-or-arg)* (required-node-space node-children)?
+base-node := slashdash? type? node-space* string
-node := base-node optional-node-space node-terminator
+      (node-space+ node-prop-or-arg)*
-final-node := base-node optional-node-space node-terminator?
+      // slashdashed node-children must always be after props and args.
-node-prop-or-arg := prop | value
+      (node-space+ slashdash node-children)*
+      (node-space+ node-children)?
+      (node-space+ slashdash node-children)*
+node := base-node node-space* node-terminator
+final-node := base-node node-space* node-terminator?
+node-prop-or-arg := slashdash? (prop | value)
 node-children := '{' nodes final-node? '}'
 node-terminator := single-line-comment | newline | ';' | eof
 
-prop := string optional-node-space '=' optional-node-space value
+prop := string node-space* '=' node-space* value
-value := type? optional-node-space (string | number | keyword)
+value := type? node-space* (string | number | keyword)
-type := '(' optional-node-space string optional-node-space ')'
+type := '(' node-space* string node-space* ')'
 
 string := identifier-string | quoted-string | raw-string
 
@@ -850,3 +855,6 @@ Specifically:
   `a - 'x'` means "any `a`, except something that matches the literal `'x'`".
 * The prefix `^` means "something that does not match" whatever follows it.
   For example, `^foo` means "must not match `foo`".
+* A single definition may be split over multiple lines. Newlines are treated as
+  spaces.
+* `//` at the beginning of a line is used for comments.