[Yaml-core] RE: Draft

I've polishing the draft more, in the intention to get it to a "release
candidate" level. Once I get this done, I plan to start working on a Java
implementation.
I've made the following changes:
- I fixed the confusion between serialization characters and information
model characters.
- The productions were fixed to strictly reflect the intent, with minimal
reliance on wording to convey restrictions and distinctions. For example,
the distinction between an implicitly typed unquoted scalar and a string one
(beginning with an alphabetic character) is now reflected in the
productions. This increased the number of productions significantly and
gives an impression that YAML is more complex - but it does make it
impossible to miss the intent.
- I removed the exception allowing single indicator keys, as this
complicates things to no end and is unnecessary.
- I called the types listed in the spec itself "Common types", placed them
under org.yaml.common, and referred the reader to yaml.org for a list of
additional types (should there be a fixed URL for this? Say,
http://www.yaml.org/types.html?
Other then that, there don't seem to be any open issues except for the
normal polishing ones - making sure all the links work, that the wording is
correct, the productions don't have any bugs, and that the examples are
good.
Improving the examples does pose a question. It is easy enough to list all
the cases, but it is difficult to convey the semantics of each example in
the more complex cases (e.g., references).
One way to do it is to add an equivalent code snippet to each example. The
problem is that doing this in a single language would give the impression
that YAML is tied to that language. Perhaps the best way would be to use
different languages for different examples. I could handle Perl and Java
easily, and I have access to the Python books so I think I could manage that
as well.
Another way would be to work harder at self-explaining examples, and write
an independent example document for each language demonstrating how YAML
maps to its native data structures. Thoughts?
There's also a great technical writer working with me who is going to give
it a review, English not being my native language. Also he's going to be a
great test case for how a semi-technical person would react to the spec.
I'm attaching the current state of the draft, but I'm not placing it in the
web site yet until we agree it makes sense to do it.
Feedback is welcome as usual!
Have fun,
Oren Ben-Kiki

Thread view

I've polishing the draft more, in the intention to get it to a "release
candidate" level. Once I get this done, I plan to start working on a Java
implementation.
I've made the following changes:
- I fixed the confusion between serialization characters and information
model characters.
- The productions were fixed to strictly reflect the intent, with minimal
reliance on wording to convey restrictions and distinctions. For example,
the distinction between an implicitly typed unquoted scalar and a string one
(beginning with an alphabetic character) is now reflected in the
productions. This increased the number of productions significantly and
gives an impression that YAML is more complex - but it does make it
impossible to miss the intent.
- I removed the exception allowing single indicator keys, as this
complicates things to no end and is unnecessary.
- I called the types listed in the spec itself "Common types", placed them
under org.yaml.common, and referred the reader to yaml.org for a list of
additional types (should there be a fixed URL for this? Say,
http://www.yaml.org/types.html?
Other then that, there don't seem to be any open issues except for the
normal polishing ones - making sure all the links work, that the wording is
correct, the productions don't have any bugs, and that the examples are
good.
Improving the examples does pose a question. It is easy enough to list all
the cases, but it is difficult to convey the semantics of each example in
the more complex cases (e.g., references).
One way to do it is to add an equivalent code snippet to each example. The
problem is that doing this in a single language would give the impression
that YAML is tied to that language. Perhaps the best way would be to use
different languages for different examples. I could handle Perl and Java
easily, and I have access to the Python books so I think I could manage that
as well.
Another way would be to work harder at self-explaining examples, and write
an independent example document for each language demonstrating how YAML
maps to its native data structures. Thoughts?
There's also a great technical writer working with me who is going to give
it a review, English not being my native language. Also he's going to be a
great test case for how a semi-technical person would react to the spec.
I'm attaching the current state of the draft, but I'm not placing it in the
web site yet until we agree it makes sense to do it.
Feedback is welcome as usual!
Have fun,
Oren Ben-Kiki

Hello Oren. Thank you for the next line of polish.
I have a bunch of changes in the first few pages
(before the productions). I'll spend some time
updating that portion of the document in the
next few days and update the copy on the server.
That being said... after two months of "idle" I have a
thought to share about YAML: It's a bit complicated.
I have to re-convince myself that this is necessary.
Ok. Here are observations/nit-picks, understanding
that I do not have amnesty...
1) We should not confuse the "map/list/scalar"
mechanism with the type mechanism. In particular,
neither a map nor a scalar are types.
Let's call map/list/scalar as the "kinds" of nodes
that yaml supports. The "type" of node is reserved
for application specific purposes. If we mix "type"
and "kind" we get into a big ball of mud. "kind"
is a mandatory structural distinction, where "type"
is an application level, optional, and fully
configurable mechanism.
2) Regarding map/list entries to be keys.
First, it's a bit too complicated. Second,
its serialization needs help. I'm willing
to say "oh well" if someone has a map with
a map or list as a key. Out of scope.
3) I don't understand the multiple levels of
references. In fact, I think this falls out
of scope for YAML. Perhaps an application
defined type can be construted for this...
4) I'm uncomforable with (a) not having a @ % indicator
and (b) having : used for list bullets. How about...
key:
this: is a subordinate map
and:
- this is a
- bulleted list
I'd be comfortable with the above. If we arn't
going to have an indicator, then the bullet must
help with the indication.
5) I'd rather have the indicators mandatory again.
The syntax has gotten too "fuzzy".
In short, it seems that YAML has matured quite a
bit since we started. But coming back to it a few
months later, it seems a bit too much. Thoughts?
On Sun, Oct 21, 2001 at 09:28:29AM +0200, Oren Ben-Kiki wrote:
| I've polishing the draft more, in the intention to get it to a "release
| candidate" level. Once I get this done, I plan to start working on a Java
| implementation.
|
| I've made the following changes:
|
| - I fixed the confusion between serialization characters and information
| model characters.
+1
| - The productions were fixed to strictly reflect the intent, with minimal
| reliance on wording to convey restrictions and distinctions. For example,
| the distinction between an implicitly typed unquoted scalar and a string one
| (beginning with an alphabetic character) is now reflected in the
| productions. This increased the number of productions significantly and
| gives an impression that YAML is more complex - but it does make it
| impossible to miss the intent.
|
| - I removed the exception allowing single indicator keys, as this
| complicates things to no end and is unnecessary.
Nice idea, but how do you specify a value that is an empty map?
| - I called the types listed in the spec itself "Common types", placed them
| under org.yaml.common, and referred the reader to yaml.org for a list of
| additional types (should there be a fixed URL for this? Say,
| http://www.yaml.org/types.html?
Kool.
| Other then that, there don't seem to be any open issues except for the
| normal polishing ones - making sure all the links work, that the wording is
| correct, the productions don't have any bugs, and that the examples are
| good.
I'm sorry for complaining above. I can cap it if
there isn't shared sentiment.
| Improving the examples does pose a question. It is easy enough to list all
| the cases, but it is difficult to convey the semantics of each example in
| the more complex cases (e.g., references).
|
| One way to do it is to add an equivalent code snippet to each example. The
| problem is that doing this in a single language would give the impression
| that YAML is tied to that language. Perhaps the best way would be to use
| different languages for different examples. I could handle Perl and Java
| easily, and I have access to the Python books so I think I could manage that
| as well.
|
| Another way would be to work harder at self-explaining examples, and write
| an independent example document for each language demonstrating how YAML
| maps to its native data structures. Thoughts?
|
| There's also a great technical writer working with me who is going to give
| it a review, English not being my native language. Also he's going to be a
| great test case for how a semi-technical person would react to the spec.
|
| I'm attaching the current state of the draft, but I'm not placing it in the
| web site yet until we agree it makes sense to do it.
Thank you *so* much. This has moved along far! It's
time to roll up the sleeves and implement a prototype
to make sure it's what we want.
I'll be digging back in now, but only an hour or so per day.
Best,
Clark