Re: YAML 1.2 (3rd Edition) is released!
Brad Baxter <[email protected]>
| Newsgroups | gmane.text.yaml.general |
|---|---|
| Message-ID | <[email protected]> |
On Tue, Jul 21, 2009 at 11:28 PM, Oren Ben-Kiki<[email protected]> wrote: > The final 1.2 specification is available at > www.yaml.org/spec/1.2/spec.{html,pdf,ps}. > We also have created an (empty) errata page at > www.yaml.org/spec/1.2/errata.html Greetings, The errata page may perhaps be empty no longer. :-) Below are mostly minor changes that I suggest, based on a first pass. There are questions I have about a few of the examples as well, but I want to study those some more ... I do have to say that the language of the document is very easy to follow, and I think clearly shows monumental effort. Cheers, Brad YAML Ain’t Markup Language (YAML™) Version 1.2 3rd Edition (2009-07-21) 3.1. Processes - refernced + referenced 4.1. Production Parameters - This sensitivity is the cause of most of the complexity of the YAML syntax definition. (clarification?) + This sensitivity to the surrounding text is the cause of most of the complexity of the YAML syntax definition. Context: c - These restrictions depend on where they appear: as implicit keys directly inside a block mapping (block-key); as implicit keys inside a flow mapping (flow-key); as values inside a flow collection (flow-in); or as values inside one (flow-out). + These restrictions depend on where they appear: as implicit keys directly inside a block mapping (block-key); as implicit keys inside a flow mapping (flow-key); as values inside a flow collection (flow-in); or as values outside one (flow-out). (Block) Chomping: t - Block scalars offer three possible mechanisms for chomping any trailing line breaks: strip, clip and keep. Unlike the previous parameters, this only controls interpretation; the line breaks are valid in either case. + Block scalars offer three possible mechanisms for chomping any trailing line breaks: strip, clip and keep. Unlike the previous parameters, this only controls interpretation; the line breaks are valid in all cases. 5.3. Indicator Characters - A “-” (#2D, hyphen) denotes a block sequence entry. + A “-” (#x2D, hyphen) denotes a block sequence entry. - A “?” (#3F, question mark) denotes a mapping key. + A “?” (#x3F, question mark) denotes a mapping key. - A “:” (#3A, colon) denotes a mapping value. + A “:” (#x3A, colon) denotes a mapping value. - A “,” (#2C, comma) ends a flow collection entry. + A “,” (#x2C, comma) ends a flow collection entry. - A “[” (#5B, left bracket) starts a flow sequence. + A “[” (#x5B, left bracket) starts a flow sequence. - A “]” (#5D, right bracket) ends a flow sequence. + A “]” (#x5D, right bracket) ends a flow sequence. - A “{” (#7B, left brace) starts a flow mapping. + A “{” (#x7B, left brace) starts a flow mapping. - A “}” (#7D, right brace) ends a flow mapping. + A “}” (#x7D, right brace) ends a flow mapping. - An “#” (#23, octothorpe, hash, sharp, pound, number sign) denotes a comment. + An “#” (#x23, octothorpe, hash, sharp, pound, number sign) denotes a comment. - An “&” (#26, ampersand) denotes a node’s anchor property. + An “&” (#x26, ampersand) denotes a node’s anchor property. - An “*” (#2A, asterisk) denotes an alias node. + An “*” (#x2A, asterisk) denotes an alias node. - The “!” (#21, exclamation) is heavily overloaded for specifying node tags. + The “!” (#x21, exclamation) is heavily overloaded for specifying node tags. - A “|” (7C, vertical bar) denotes a literal block scalar. + A “|” (#x7C, vertical bar) denotes a literal block scalar. - A “>” (#3E, greater than) denotes a folded block scalar. + A “>” (#x3E, greater than) denotes a folded block scalar. - An “'” (#27, apostrophe, single quote) surrounds a single-quoted flow scalar. + An “'” (#x27, apostrophe, single quote) surrounds a single-quoted flow scalar. - A “"” (#22, double quote) surrounds a double-quoted flow scalar. + A “"” (#x22, double quote) surrounds a double-quoted flow scalar. - A “%” (#25, percent) denotes a directive line. + A “%” (#x25, percent) denotes a directive line. - The “@” (#40, at) and “`” (#60, grave accent) are reserved for future use. + The “@” (#x40, at) and “`” (#x60, grave accent) are reserved for future use. 5.4. Line Break Characters - Note these include the non-ASCII line breaks: next line (#x85), line separator (#x2028) and paragraph separator (#x2029). + Note that these include the non-ASCII line breaks: next line (#x85), line separator (#x2028) and paragraph separator (#x2029). 5.6. Miscellaneous Characters - By convention, any URIs characters other than the allowed printable ASCII characters are first encoded in UTF-8, and then each byte is escaped using the “%” character. + By convention, any URI characters other than the allowed printable ASCII characters are first encoded in UTF-8, and then each byte is escaped using the “%” character. 5.7. Escaped Characters - Escaped ASCII form feed (#xA) character. + Escaped ASCII form feed (#xC) character. 6.8.1. “YAML” Directives - Note version 1.2 is mostly a superset of version 1.1, defined for the purpose of ensuring JSON compatibility. + Note that version 1.2 is mostly a superset of version 1.1, defined for the purpose of ensuring JSON compatibility. 7.4.2. Flow Mappings - Note the value may be completely empty since its existence is indicated by the “:”. + Note that the value may be completely empty since its existence is indicated by the “:”. 8.1.1.1. Block Indentation Indicator - Content Content may safely start with a tab or a “#” character. + Content may safely start with a tab or a “#” character. 8.1.2. Literal Style - Note all line break characters are normalized. + Note that all line break characters are normalized. 8.1.3. Folded Style - Line breaks and empty lines separating between folded and more-indented lines are also not folded. + Line breaks and empty lines separating folded and more-indented lines are also not folded. 8.2.1. Block Sequences - Note it is not possible to specify node properties for such a collection. + Note that it is not possible to specify node properties for such a collection. 8.2.2. Block Mappings - Note YAML allows here the same compact in-line notation described above for block sequence entries. + Note that YAML allows here the same compact in-line notation described above for block sequence entries. - Note it is not possible to specify node properties for such a nested mapping. + Note that it is not possible to specify node properties for such a nested mapping. 9.2. Streams Concatenating Streams - In addition, it is necessary to separate between the last document of the first stream and the first document of the second stream. + In addition, it is necessary to separate the last document of the first stream from the first document of the second stream. - This is easily ensured by inserting an document end marker between the two streams. + This is easily ensured by inserting a document end marker between the two streams. - Note this is safe regardless of the content of either stream. + Note that this is safe regardless of the content of either stream. Chapter 10. Recommended Schemas - A YAML schema is a combination of a set of tags and a a mechanism for resolving non-specific tags. + A YAML schema is a combination of a set of tags and a mechanism for resolving non-specific tags. 10.2.1.2. Boolean - In languages without a native Boolean type (such as C), is usually bound to an native integer type, using one for true and zero for false. + In languages without a native Boolean type (such as C), is usually bound to a native integer type, using one for true and zero for false. ------------------------------------------------------------------------------