From: Ingy d. N. <in...@in...> - 2011-10-25 05:55:58
|
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 <rea...@gm...>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. > |
From: Trans <tra...@gm...> - 2011-10-25 14:50:02
|
On Oct 25, 1:26 am, Ingy dot Net <i...@ingy.net> 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 It would help if one could make any sense of all that. I wouldn't even no where to start. Guess I now know why people tend to mention DocBook as it were the epitome of barfing. At the very least could some appropriate subdirs be used? |
From: Oren Ben-K. <or...@be...> - 2011-10-25 15:33:18
|
Yes, if I were starting today I'd have written it in asciidoc. But the spec is almost 10 years old, asciidoc wasn't around when we started (AFAIK). Have fun, Oren Ben-Kiki On Tue, Oct 25, 2011 at 4:49 PM, Trans <tra...@gm...> wrote: > > > On Oct 25, 1:26 am, Ingy dot Net <i...@ingy.net> 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 > > It would help if one could make any sense of all that. I wouldn't even > no where to start. Guess I now know why people tend to mention DocBook > as it were the epitome of barfing. > > At the very least could some appropriate subdirs be used? > > > > ------------------------------------------------------------------------------ > 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 > Yam...@li... > https://lists.sourceforge.net/lists/listinfo/yaml-core > |
From: Oren Ben-K. <or...@be...> - 2011-10-25 09:37:20
|
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 <in...@in...> 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 <rea...@gm...>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. >> > > |