YAML Ain't Markup Language

cce-14.html has been uploaded for your review.

Changes:

  *  Re-ordered the transfer method definition
     in the informaiton model.

  *  Re-formatted the transfer model section,
     and linked it with the table of contents.
 
  *  A few edits to the transfer model section:

     - changed "real" to "float", as it stores
       a floating point approximation to
       a real number.  Think 1.13 or 1.1 
       which do not have an exact representation
       in IEEE floating point.  

     - changed "text" to "str", for string per
       my earlier change.

     - changed "integer" to "int" for consistency

     - removed the separator from !map and !seq,
       it is now fixed using the comma.  If 
       someone doesn't like it, they can use
       the full-blown form.

      
Comments:

     - Do !map and !seq in-line forms do implicit
       typing on their contents... they should.

Todo:

  *  Write 3.4, "serial access", including
     anchor and alias

  *  Change all of the links in the syntax
     section to start with syntax.

  *  Review the content of the syntax and
     transfer methods for consistency with
     the information model section

  *  Review the examples for consistency,
     and re-use of the preview samples.

  *  Check for broken links, spelling errors, 
     grammer errors, etc.

Best,

Clark

On 26/11/01 18:50 -0500, Clark C . Evans wrote:
> Ok.  I've posted a new version of the spec on
> line at http://yaml.org/cce-13.html and it'd
> be cool to get some feedback.

---
location: Status Of This Document
problemo: Paragraph is not properly justified
---
location: Intro->para2
old: serialized form native 
new: serialized form, native 
---
location: Intro->para3
old: module that provides for parser or emitter
new: module that provides parser or emitter
---
location: Intro->para3
old: must provide or obtain from the application.
new: must provide to or obtain from the application.
---
location: 1.2->p1
problemo: Please change the Perl link to http://www.perl.com
 or at least use.perl.org.
---
location: 1.2->p5
old: introduce a unique of handling whitespace.
new: introduce a unique method of handling whitespace.
---
location: 1.3->p2 
old: YAML and XML information model are starkly different
new: YAML and XML information models are starkly different
---
location: 1.3->p2
old: are a keyed collection
new: are keyed collections
---
location: 1.3-p2
old: requires mapping, conventions, or an alternative 
 programming component, a document object model
new: requires mapping conventions, or an alternative 
 programming component (eg a document object model
---
location: 1.4
old: Conformant YAML texts
new: Conformant YAML streams
---
location: 2.3->c4
old: occupation: baseball
new: occupation: baseball player
---
location: 2.4
old: given  : !text Chris
new: given  : !str Chris
note: multiple occurances
---
location: 2.4->d6
problemo: what is this? 
---
location: 2.4->d5
old: learned alot
new: learned a lot
---
location: 1.2->p2
old: supports both scalar values (string, integer)
new: supports both scalar values (string, integer, real)
---
location: 3.1
old: Exceptions to this guide line 
new: Exceptions to this guideline 
---
location: 3.2
problemo: This whole section went so far above my head I 
 couldn't even make sense of it. Could you possibly translate
 it for human consumption? Or at least try explaining it
 to someone (like me) who could translate it into humanese
 for you.
prognosis: If you don't make this simple for people to 
 understand, then people (like me) are going to ignore
 it and risk implementing non-conformant processes.
---
location: 3.2.8
old: rechable 
new: reachable 
---
location: 3.3
old: may extends information model 
new: may extend the information model 
---
location: [12]	
old: reserved_indicators ::= '^' | '@'
new: reserved_indicators ::= '^' | '@' | '%'
---
location: 4.3
old: stream contains more then
new: stream contains more than
---
location: 4.4
old: Once an anchor was used 
new: Once an anchor is used 
---
location: 4.4
text: |
 alias : &02 *01
 again : *02
problemo: I thought this was not allowed... 
---
location: 4.5.2
this: |
 ? \\
  \a
 : This key had to be escaped.
could be this: |
 "\a": This key had to be escaped.
---
location: 4.6.4
old: unlike a folded scalar, a plain scalar may start in-line
new: unlike a folded scalar, a plain scalar must start in-line
---
location: 4.6.4
old: Using an implicit text transfer method allows overcoming
new: Using an explicit text transfer method allows overcoming
---
location: 4.6.4
this is an error, no? : |
 third: <html><head><title>Embedded HTML!</title></head>
  <body><p class="none">This can even
  have embedded HTML since there is no
  escaping, and since < (the starting character)
  is not an indicator!</p></body>
because: it fails implicit regexes
fix: use quotes
---
location: 5.3
old: deserialize the node to any native native 
new: deserialize the node to any native 
note: this shows up in more than one sentence
---
location: 5.3
old: Name: org.yaml.ptr
new: Name: org.yaml.ref
note: we decided to make pointer be reference

On the whole, this document is really shaping up. The new structure with
the tutorials at the top really helps.


Good work guys!

Cheers, Brian

Thanks Brian.  Changes made and uploaded to
yaml.org/cce-15.html

| location: 3.2
| problemo: This whole section went so far above my head I 
|  couldn't even make sense of it. Could you possibly translate
|  it for human consumption? Or at least try explaining it
|  to someone (like me) who could translate it into humanese
|  for you.
| prognosis: If you don't make this simple for people to 
|  understand, then people (like me) are going to ignore
|  it and risk implementing non-conformant processes.

Yes.  I'm thinking about how to come up with 
better explanation, but I like the formalism.
I need to find a better ballence...

| old: Name: org.yaml.ptr
| new: Name: org.yaml.ref
| note: we decided to make pointer be reference

I'll change this if Oren agrees.  The problem with
reference is that most Java books (and even some
perl books talk about the following as a reference...

obj = [0]
ref = obj

Here, ref is a "reference" to the object obj.  I'm 
sure this follows from the distinction between a
reference and a pointer in C++ ... a reference is
what we're calling an alias.  

Perl, of course, uses reference to mean pointer,
and doesn't even talk about aliases (as they are
so obvious).

Thus, we are in a bit of a bind.  I'd rather stick
with pointer for the word and heavily document that
the Perl "hard reference" is an example.

| On the whole, this document is really shaping up. The 
| new structure with the tutorials at the top really helps.

Thanks.  I was hoping it would help.  The trick is
to give enough detail so that the user is bootstrapped
without getting into the details.

Best,

Clark

On 27/11/01 01:49 -0500, Clark C . Evans wrote:
> | old: Name: org.yaml.ptr
> | new: Name: org.yaml.ref
> | note: we decided to make pointer be reference
> 
> I'll change this if Oren agrees.  The problem with
> reference is that most Java books (and even some
> perl books talk about the following as a reference...
> 
> Thus, we are in a bit of a bind.  I'd rather stick
> with pointer for the word and heavily document that
> the Perl "hard reference" is an example.

I'll go with pointer. Just fix the spec to be consistent. You were using
both terms.

Cheers, Brian