Hello,
My comments below fall under this heading:
"Language:
There is a better way to express some point (or I made a typo). English
isn't my native language and I am not a professional writer so I have no
illusions about the quality of my writing :-) If you have a better idea
on how to convey something, I'll be more than happy to incorporate it."
But I would first like to say that the entire document is very easy to read.
You say that English isn't your native language, but it doesn't show.
I consider most of my comments to be minor and trivial. Minor in that
some may disagree and want the text to stay as is, and trivial in that
I felt that I followed your meaning in every case.
Hopefully, I've rendered this well for email; here goes ...
1.2. Prior Art
...
The syntax of YAML was motivated by Internet Mail (RFC0822) and remains partially compatible with that standard. Further, borrowing from MIME (RFC2045), YAML's top-level production is a stream of independent documents; ideal for message-based distributed processing systems.
My English teacher would have considered the sentence above incorrect.
A semi-colon may separate independent clauses but the clause beginning
with "ideal" is not independent. Perhaps just use a comma instead?
...
YAML was designed to support incremental interfaces that include both input ("getNextEvent()") and output "sendNextEvent()") one-pass interfaces. Together, these enable YAML to support the processing of large documents (e.g. transaction logs) or continuous streams (e.g. feeds from a production machine).
Missing open parenthesis after "output".
1.4. Relation to JSON
...
YAML can therefore be viewed as a natural superset of JSON, offering improved human readability and a more complete information model. This is also the case in practice; every JSON file is also a valid YAML file. This makes it easy to migrate from JSON to YAML if/when the additional features are requitred.
Typo: requitred
1.5. Terminology
...
May
The word may, or the adjective optional, mean that conforming YAML processors are permitted, but need not behave as described.
I think this sentence could be worded better. Perhaps:
The word may, or the adjective optional, mean that conforming YAML
processors are permitted to, but need not, behave as described.
I'm not so sure about that either, so someone else might make a
suggestion.
2.2. Structures
...
Repeated nodes are first identified by an anchor (marked with the ampersand - "&"), and are then aliased (referenced with an asterisk - "*") thereafter.
Even though "nodes" is hyperlinked to an explanation, it might be
helpful to further clarify it in this sentence, since this is its
first appearance. Perhaps:
Repeated nodes (i.e., scalars, sequences, mappings) are first identified
by an anchor (marked with the ampersand - "&"), and are then aliased
(referenced with an asterisk - "*") thereafter.
Or maybe not--it's just that on first reading, I didn't quite grok
"nodes" without clicking it.
2.3. Scalars
...
Example 2.14. In the plain scalar,
newlines become spaces
This example struck me as out of place, because it precedes rather then
follows the paragraph that mentions plain style flow scalars.
3.1. Processes
This section details the processes shown in the diagram above. Note a YAML processor need not provide all these processes. For example, a YAML library may provide only YAML input ability, for loading configuration files, or
only output ability, for sending data to other applications.
I would change "Note" to either "Note," or "Note that". There are cases
where you would begin a sentence with just "Note", but this isn't one of
them, IMO.
3.2.1.2. Tags
...
YAML tags are used to associate meta information with each node. In particular, each tag must specify the expected node kind (scalar, sequence, or mapping). Scalar tags must also provide mechanism for converting formatted scontent to a canonical form for supporting equality testing.
Change "mechanism" to "a mechanism" or "mechanisms".
3.2.2. Serialization Tree
To express a YAML representation using a serial API, it necessary to impose an order on mapping keys and employ alias nodes to indicate a subsequent occurrence of a previously encountered node.
Change "it necessary" to "it is necessary".
3.3.2. Resolved Tags
...
Note resolution must not consider presentation details such as comments, indentation and node style.
Change "Note" to "Note," or "Note that".
3.3.2. Resolved Tags
...
If a document contains unresolved tags, the YAML processor is unable to compose a complete representation graph. In such a case, the YAML processor may compose an partial representation, based on each node's kind and allowing for non-specific tags.
Change "an partial" to "a partial".
3.3.3. Recognized and Valid Tags
...
In contrast, a YAML processor can always compose a complete representation for an unrecognized or an invalid collection, since collection equality does not depend upon knowledge of the collection's data type. However, such a complete representation can not be used to construct a native data structure.
I would change "can not" to "cannot". The following site explains why
better than I would be able to: http://alexfiles.com/cannot.shtml
6.2. Separation Spaces
Outside indentation and scalar content, YAML uses white space characters for separation between tokens within a line. Note such white space may safely include tab characters.
Change "Note" to "Note," or "Note that".
Named Handles
...
The name of the handle is a a presentation detail and must not be used to convey content information. In particular, the YAML processor need not preserve the handle name once parsing is completed.
Change "a a" to "a".
7.4. Flow Collection Styles
A flow collection may be nested within a block collection (flow-out context), nested within another flow collection (flow-in context), or be a part of an implicit key (flow-key context). Flow collection entries are separated by the "," indicator. The final "," may be omitted. This does not cause ambiguity because flow collection entries can never be completely empty.
To me, this mention of the final "," seems slightly backward. First,
it says that entries are *separated* by the "," indicator. This does
not imply that there is a final "," indicator--rather the opposite.
So I might say instead, 'A final "," may be included.' Or something
like that.
Example 7.17. Flow Mapping Separate Values
{
unquoted¡¤:¡¤"separate",
http://foo.com,
omitted:¡ã,
¡ã:¡¤omitted,
}
%YAML 1.1
---
!!map {
? !!str "unquoted" : !!str "separate",
? !!str "http://foo.com" : !!null "",
? !!str "ommitted" : !!null "",
? !!null "" : !!str "ommitted",
}
Change multiple "ommitted"s to "omitted".
Example 7.21. Single Pair Implicit Entries
- [ YAML¡¤: entry ]
- [ ¡ã: empty key entry ]
- [ {JSON: like}:adjacent ]
%YAML 1.1
---
!!seq [
!!seq [
!!map {
? !!str "YAML"
: !!str "entry"
},
],
!!seq [
!!map {
? !!null ""
: !!str "empty key entry"
},
],
!!seq [
!!map {
? !!map {
? !!str "JSON"
: !!str "like"
} : "entry",
},
],
]
The word "adjacent" became "entry" after JSON like.
Example 7.23. Flow Content
- [ a, b ]
- { a: b }
- "a"
- 'b'
- c
%YAML 1.1
---
!!seq [
!!seq [ !!str "a", !!str "b" ],
!!str "a",
!!str "b",
!!str "c",
]
Where did "- { a: b }" go?
Example 7.24. Flow Nodes
- !!str "a"
- 'b'
- &anchor "c"
- *anchor
- a
- !!str b
- !!str¡ã
%YAML 1.1
---
!!seq [
!!str "a",
!!str "b",
&A !!str "c",
*A,
!!str "b",
!!str "",
]
Where did "- a" go?
Example 8.14. Block Sequence
block sequence:
- one¡ý
- two : three¡ý
%YAML 1.1
---
!!map {
? !!str "block"
: !!seq [
!!str "one",
!!map {
? !!str "two"
: !!str "three"
},
],
}
The key "block sequence" became just "block".
Example 8.16. Block Mappings
block mapping:
¡¤key: value¡ý
%YAML 1.1
---
!!map {
? !!str "block"
: !!map {
? !!str "key"
: !!str "value",
},
}
The key "block mapping" became just "block".
Example 8.18. Implicit Block Mapping Entries
plain key: inline value
¡ã:¡ã # both empty
"quoted key::
- entry
%YAML 1.1
---
!!map {
? !!str "plain key"
: !!str "inline value",
? !!null ""
: !!null "",
? !!str "quoted key\n"
: !!seq [ !!str "entry" ],
}
That first "quoted key" part doesn't look right (unless I'm just not
getting it).
Example 8.21. Block Scalar Nodes
literal: |2
¡¤¡¤value
folded:¡ý
¡¤¡¤¡¤!foo
¡¤¡¤>1
¡¤value
%YAML 1.1
---
!!map {
? !!str "literal"
: !!str "value",
? !<!foo> "folded"
: !!str "value",
}
This may be my misunderstanding, but doesn't !foo apply to "value",
not to "folded"?
Since people perceive the "-" indicator as indentation, nested block sequences may be indented by one less space to compensate - except if nested inside another block sequence, of course (block-out context vs. block-in context).
I think that might read better as, "except, of course, if nested inside
another block sequence (block-out context vs. block-in context)."
9.1. Document Markers
A documents may be prefixed by a byte order mark and optional comments. The document end marker may also be followed by comments.
Change "A documents" to "A document".
Regards,
-- Brad