Re: Feedback About YAML 1.2, 3rd Edition

I have a whole bunch of minor fixes to add into a 4th edition. I guess I
can't avoid doing it for much longer ;-) There's some computer setup stuff I
need to do to re-activate my DocBook toolchain and so on. I'll try and do it
this weekend.

Have fun,

    Oren Ben-Kiki

On Tue, Oct 25, 2011 at 7:26 AM, Ingy dot Net <[email protected]> wrote:

> Greetings,
>
> Thank you for taking the time to make these suggestions. My first thought
> was that the spec authoring/maintenance should be a more open process. My
> second thought was that we really should have the spec on github, so people
> could file issues, fork the spec, and send pull requests. My third thought
> was realizing this:
>
> https://github.com/orenbenkiki/yaml-spec
>
> already exists, but nobody seems to make use of this.
>
> Would you be willing to submit this as a pull request. If you do I will
> lean on Oren to pull it. :)
>
> I cc'd the yaml mailing list, as the more the merrier...
>
> Cheers, Ingy
>
>
> On Mon, Oct 24, 2011 at 11:04 AM, Reality Doug <[email protected]>wrote:
>
>> Dear Oren Ben-Kiki, Clark Evans, and Ingy döt Net:
>>
>> This is feedback that may or may not be useful. I can't tell. I never got
>> the hype about XML, so maybe I am slow. It seems that YAML would be better
>> (if I can figure it out). Like with Ruby, why not say a lot with a little.
>> For me the YAML 1.2 specification, 3rd edition read well through chapter 5,
>> then I got lost. This feedback is based on having read from the beginning
>> through subchapter 7.3.2. Single-Quoted Style. Thanks for you contributions.
>> I know I did not make YAML possible.
>>
>> End of subchapter 5.1. Character Set says:
>> "To ensure JSON compatibility, YAML processors must allow all non-control
>> characters inside quoted scalars. To ensure readability, non-printable
>> characters should be escaped on output, even inside such scalars."
>>
>> 1) What output? dump and not load? Could clarify this at the start of
>> subchapter 5.1.
>> 2) "Even inside such scalars"? Where else could be non-printable
>> characters (that presumable represent the content)?
>>
>> Example 6.4. Line Prefixes
>> 1) Why is n=1 for the plain and quoted scalars, but n=2 for the block
>> scalar? Is n=1 then n=2?
>>
>> Example 6.5. Empty Lines
>> 1) What two or more (plural?) empty lines are clipped? Clipped sounds like
>> another special word like folding and chomping. How about "Removed an empty
>> line\n" so the reader is not worried about what clipped means?
>>
>> Yes, you say 'the semantics of empty lines depend', but how is the reader
>> supposed to know that when it looks like the two situations are handled
>> identically because there is exactly one "\n" for each empty line with
>> whitespace. The material is hard enough and 1000 reads would motivate the 1
>> write of a simple explanation here. A self-evident example of two different
>> cases example 6.5 is not.
>>
>> Start of subchapter 6.5 Line Folding reads:
>> "Line folding allows long lines to be broken for readability, while
>> retaining the semantics of the original long line. If a line break is
>> followed by an empty line, it is trimmed; the first line break is discarded
>> and the rest are retained as content."
>> * This is a bit confusing. Maybe you are trying to squeeze together two
>> distinct actions. Trimming seems to discard the whitespace of empty lines as
>> not explicit enough for human readability. Folding seems to be the trimming
>> of empty lines and the discarding of the line break at the end of a
>> non-empty line followed by one or more empty lines. I guess that is the
>> discarding of the first 'b-non-content'.
>> 1) Are 'the rest' the line breaks of empty lines? If so, they are not
>> clearly the rest since they are distinctly different from line breaks of
>> non-empty lines. If you mean they are all 'b-non-content' line breaks as
>> opposed to 'b-as-line-feed' breaks ending lines not the last line of a human
>> readable 'paragraph' and that is the critical point, then it would help to
>> make that explicit rather than jamming so many concepts into an inference
>> monster sentence.
>>
>> Subchapter 6.5. Line Folding, section Block Folding
>> 1) The final line break of what? Seems the break of final non-empty line,
>> but not clear. *After 'each "paragraph" is interpreted as a line' insert
>> 'with or without a terminating line feed of its own'.
>> * Change from 'empty lines are interpreted as a line feed to 'each empty
>> line is trimmed leaving only its line feed'.
>>
>> Example 6.7. Block Folding
>> 1) If you have four (yellow area) b-l-folded(n,c) on the left side, and
>> you have four "\n" on the right for each one, plus another "\n" for the last
>> line in the block that WAS NOT TRIMMED OR CHOMPED, then what was folded?
>> * Please do NOT label a "No Block Folding" example as a "Block Folding"
>> example. You might like to include some actual folding!
>> * Might note for the reader that the line end of the line with 'foo' is
>> retained because the following empty line may not be trimmed as needed for
>> the multiple lines to be folded.
>>
>> Subchapter 6.5. Line Folding, section Flow Folding
>> * After 'each "paragraph" is interpreted as a line' insert 'without a
>> terminating line feed of its own'.
>>
>> Example 7.5. Double Quoted Line Breaks
>> *The bottom line on the left has a 's-double-escaped(n)' space then an
>> escaped space between the tabs from the end of the previous line and the
>> next character of the that last line. The right side on the last line has
>> those two spaces between those two tabs. If a backslash at the end of a line
>> has the conventional meaning, then the indicated 's-double-escaped(n)' space
>> is confusingly unconventional if not wrong. If not wrong, a quick
>> explanation here would be appreciated. You are about to tell me in the next
>> paragraph that 'all leading and trailing white space characters are excluded
>> from the content.'
>>
>> Between examples 7.5 and 7.6 in subsection 7.3.1. Double-Quoted Style
>> It says: "All leading and trailing white space characters are excluded
>> from the content. Each continuation line must therefore contain at least one
>> non-space character."
>> * I think you mean must contain at least one non-WHITE character because a
>> tab is a non-space character that I guess would be excluded as
>> human-readable inexplicitness on an empty line.
>>
>> Subsubchapter 7.3.2. Single-Quoted Style.
>> * I think it is more clear to end the first paragraph with: 'it is only
>> possible to break a single-quoted line without adding a spurious space or
>> removing given white space by breaking on a single space character
>> sandwiched between two non-WHITE(?) characters. A single space character is
>> reintroduced by line folding.'
>>
>> Note: Having read the 3rd edition of the YAML 1.2 specification through
>> subsubchapter 7.3.2, I have not seen an explicit value of (n) in any of the
>> examples. If there is a concrete (n) value for some 'x-xxx-thingy(c,n)' or
>> 'x-xxx-thingy(n)', it would be helpful to show what it is.
>>
>
>

------------------------------------------------------------------------------
The demand for IT networking professionals continues to grow, and the
demand for specialized networking skills is growing even more rapidly.
Take a complimentary Learning@Cisco Self-Assessment and learn 
about Cisco certifications, training, and career opportunities. 
http://p.sf.net/sfu/cisco-dev2dev

_______________________________________________
Yaml-core mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/yaml-core