From: Rich M. <rd...@cf...> - 2004-12-30 06:48:33
|
Page 4 I'd like to see examples for "Sequences of Mappings" and "Mappings of Sequences". Page 5 "#" is also called a "sharp" sign (from musical notation). Contrariwise, a "pound" sign will be interpreted by our British friends to mean a funny-Looking capital "L". Speaking of which, is there a simple explanation for why YAML disallows comments following the data values in cases such as these? A: 123.45 # comment B: "data" # comment C: [1, 2] # comment D: {a: 1, b: 2} # comment Page 6 The discussion of Example 2.11 is a bit terse. In Example 2.15, the text should read "Folded newlines are preserved ...". Page 8 Example 2.23 seems to imply that no quotes are needed around "application specific tag". True? I'd like to see some explanation of what these tags actually translate to, in terms of sets and mappings. -r -- email: rd...@cf...; phone: +1 650-873-7841 http://www.cfcl.com - Canta Forda Computer Laboratory http://www.cfcl.com/Meta - The FreeBSD Browser, Meta Project, etc. http://www.ptf.com/dossier - Prime Time Freeware's DOSSIER series |
From: Rich M. <rd...@cf...> - 2005-01-01 06:03:10
|
======= Page 21 ======= ... denotes a blocks equence entry. ... denotes a block sequence entry. Section 4.1.3 is basically a humongous bulleted list. Unfortunately, the bullets points get lost among the other text. I suggest that you indent the following material (including the examples!) to indicate that it is subsidiary: * A "-" denotes a ... [3] c-sequence-entry ::= "_" ... I would also suggest that you include the names of the characters: * A "-" (hyphen) denotes a ... ======= Page 23 ======= Why is there a space before the sharp sign in: A " #" denotes a comment. It seems odd that you are using curly double-quotes, but straight single-quotes, as in A "&" denotes a node's anchor property. ^ ^ ^ ======= Page 24 ======= A "'" surrounds a single quoted flow scalar. A "'" surrounds a single-quoted flow scalar. A """ surrounds a double quoted flow scalar. A """ surrounds a double-quoted flow scalar. -- email: rd...@cf...; phone: +1 650-873-7841 http://www.cfcl.com - Canta Forda Computer Laboratory http://www.cfcl.com/Meta - The FreeBSD Browser, Meta Project, etc. http://www.ptf.com/dossier - Prime Time Freeware's DOSSIER series |
From: Oren Ben-K. <or...@be...> - 2005-01-02 23:18:23
|
On Saturday 01 January 2005 07:57, Rich Morin wrote: > I suggest that you > indent the following material (including the examples!) to indicate > that it is subsidiary: ... I'm not certain that's a good idea. There are many places where there are bullet (or definition) lists intermixed with the productions. The overall effect of indenting the productions and examples in most such cases isn't good (admittedly it is the HTML version that suffers the most). I think I'll leave them unindented, at least for now. > I would also suggest that you include the names of the characters: I suppose so. Some of these name are surprisingly controversial (# in particular). Octothorpe isn't the original name (see http://www.sigtel.com/tel_tech_octothorpe.html). Besides being called "sharp" or "hash", its also known as "number sign", "gate", "square" and even "pound"... Oh well. > It seems odd that you are using curly double-quotes, but straight > single-quotes, I used <quote>...</quote> for double quoted stuff and a simple ' for apostrophe; I changed the ' to ’ which did the trick (I actually added a <q/> template to do it for me). Not a pretty sight but it works. I added the fixes to the CVS version (available at the site). Thanks! Keep on the good work, Oren Ben-Kiki |
From: Oren Ben-K. <or...@be...> - 2004-12-30 18:06:10
|
On Thursday 30 December 2004 08:48, Rich Morin wrote: > I'd like to see examples for "Sequences of Mappings" and > "Mappings of Sequences". Examples 2.3 and 2.4. > "#" is also called a "sharp" sign (from musical notation). Right. Fixed. > ... is there a simple explanation for why > YAML disallows comments following the data values in cases > such as these? > > A: 123.45 # comment > B: "data" # comment > C: [1, 2] # comment > D: {a: 1, b: 2} # comment These are legal; see examples... hmmm... Oops. No examples. OK, I added this to examples 2.2 and 4.46. Nice catch! > The discussion of Example 2.11 is a bit terse. Well, it is a rather advanced sort of usage; it would take a lot of wording to clarify everything that goes on in there. "It is not expected that the first time reader grok all of the examples" :-) If you have a better wording in mind, We'll be happy to incorporate it. > Example 2.23 seems to imply that no quotes are needed around > "application specific tag". True? True. > I'd like to see some explanation of what these tags actually > translate to, in terms of sets and mappings. The preview section needs merely to "orient" the reader so he'll have some sort of mental map of what's going on when reading the actual spec. It can't leave out too much (or the reader will get lost) but it can't get into too much detail (or it would become the actual spec). It's a balance act like walking a tightrope... Translations seem to much on the "details" side. We give such translations in the syntax section. I see you are methodically working your way through the spec. Keep on the good work! Have fun, Oren Ben-Kiki |
From: Rich M. <rd...@cf...> - 2004-12-30 19:21:44
|
At 8:06 PM +0200 12/30/04, Oren Ben-Kiki wrote: >The preview section needs merely to "orient" the reader so he'll have >some sort of mental map of what's going on when reading the actual >spec. It can't leave out too much (or the reader will get lost) but it >can't get into too much detail (or it would become the actual spec). >It's a balance act like walking a tightrope... Translations seem to >much on the "details" side. We give such translations in the syntax >section. I think I see the problem. You see this document mostly as a spec; I'm hoping for a manual. I think there is room for compromise: put in a chapter between the current chapters 2 and 3, giving LOTS of examples, explanations, and pointers into the Syntax area. I would break up Chapter 4 into six (small) chapters, to ease navigation of the document. I would also add a chapter (e.g., Syntax overview) just before these chapters. This could serve to motivate the discussion, introduce nomenclature, etc. -r -- email: rd...@cf...; phone: +1 650-873-7841 http://www.cfcl.com - Canta Forda Computer Laboratory http://www.cfcl.com/Meta - The FreeBSD Browser, Meta Project, etc. http://www.ptf.com/dossier - Prime Time Freeware's DOSSIER series |
From: Oren Ben-K. <or...@be...> - 2004-12-30 20:25:19
|
On Thursday 30 December 2004 21:21, Rich Morin wrote: > I think I see the problem. You see this document mostly as a spec; > I'm hoping for a manual. I think there is room for compromise: put > in a chapter between the current chapters 2 and 3, giving LOTS of > examples, explanations, and pointers into the Syntax area. The spec is already 85 printed pages long... It is on the verge of becoming "The YAML Book". Expanding chapter 2 this way would increase it by a good extra 20 pages or so. I think the current 5 pages of preview is as far as I'd go in this document. Besides, chapter 4 is choke-full of examples (98 of them!). The ideal solution would be to actually write "The YAML Book". There would be plenty of space for examples there. It would have to wait until we have some solid implementations so it could refer to them and expand on how to use YAML in the real world. though. We'll probably be able to get O'Reilly to publish one once YAML gains some traction... > I would break up Chapter 4 into six (small) chapters, to ease > navigation of the document. Now there's a thought. It is a huge chapter now. I'll do that... Have fun, Oren Ben-Kiki |
From: Brano T. <ti...@ds...> - 2004-12-31 08:59:02
|
PiBJIHdvdWxkIGFsc28gYWRkIGEgY2hhcHRlciAoZS5nLiwgU3ludGF4IG92ZXJ2aWV3KSBqdXN0 IGJlZm9yZSB0aGVzZSBjaGFwdGVycy4NCg0KSG93IGFib3V0IHVwZGF0aW5nICJZQU1MIHJlZmVy ZW5jZSBjYXJkIiAoaHR0cDovL3lhbWwub3JnL3JlZmNhcmQuaHRtbCk/DQpJIHVzZWQgdG8gaGF2 ZSBpdCBwaW5uZWQgbmV4dCB0byBVTUwgcmVmY2FyZCBvbiB0aGUgYmlsbGJvYXJkIGF0IG15IGRl c2suDQpRdWljayB1c2VmdWxsIGNoZWF0IHNoZWV0IHdpdGggYWN0dWFsIHVzZSBvZiBhbGwgdGhl IGZlYXR1cmVzLg0KDQpiLg0K |
From: Oren Ben-K. <or...@be...> - 2004-12-31 15:12:54
|
On Friday 31 December 2004 10:58, Brano Tich=FD wrote: > How about updating "YAML reference card" > (http://yaml.org/refcard.html)? I used to have it pinned next to UML > refcard on the billboard at my desk. Quick usefull cheat sheet with > actual use of all the features. Good point. Will do. Have fun, Oren Ben-Kiki |