> > Overall I'm good with the attempt to trim, and most of the changes, but > feel it tries to hard and ends up being to "matter-of-fact"; the > conjunctions that exist make reading a wall of text easier. I agree that > some of them could be removed as being more judgemental than mechanical. >
Fair enough and granted some of this is subjective. I went matter-of-fact because the less text to make the point, is IMO always better. > Reviewing this reminds me we are inconsistent regarding "key word" vs. > "keyword". > > It is funny you bring that up. I actually googled the difference and just stared at it because well.... nowadays they are the same thing and yes we should be consistent. > "We advise users who to read this chapter carefully ..." ? botched > surgery on this one > Not sure what you mean here? I reviewed the source sgml (that I modified): We advise users who to read this chapter carefully because it contains several rules and concepts that are implemented inconsistently among SQL databases or that are specific to <productname>PostgreSQL</productname>. If anything, I missed the overall paragraph. I would have removed the word carefully. > > > Not sure I agree with removing the comment regarding "end of the input > stream". > It seemed unnecessary as well as potentially confusing to a newer user. What is the end of an input stream? How do we know... etc? > > I think I'm ok with leaving token separation unspecified here, especially > since it isn't totally accurate (at least in regards to "special character > symbol" which often are grouped together). > > Why leave "(syntactically)" in parentheses? > Oversight. I agree that it shouldn't be in (). > Also, you got rid of the word "input" in SQL input above but left it > here. I think leaving "SQL input consists of..." is better. > Sure > > For the examples, I would put "values" on its own line. And I would add a > delete command on the same line as the update command. Then just describe > that. > > Select...; > update...; delete...; > insert ... > values ...; > > I really don't like the re-wording regarding comments. > > "But for the <command>UPDATE</command> command always ..." ? another > botched surgery > Yep, that's bad. Will fix it. > I'm not sure what the entire paragraph really gives the reader though, > besides a pointer to the reference chapter. It needs more pruning than > given here IMO. > I will take a look. > > > I feel like if we want to enhance clarity about where we differ from the > standard that we use callouts for those items instead of burying the > information in walls of text. Like the point about accepting dollar signs > in unquoted identifiers. > > > - A convention often used is to write key words in upper > + The recommened convention is to write key words in upper > [recommended needs a d] > Both should be avoided. We can say "It is the convention in this > documentation to write key words in upper case and names in lower case." > Let other places than our syntax reference speak to real-world conventions > besides ours. > agreed. > > Where we introduce "quoted identifiers" link to the description for the > formal syntax - then it's ok to remove discussions of minutia like > including double quotes in a quoted identifier. > > punctuation: > + Inside the quotes, Unicode characters can be specified in escaped > + form by writing a backslash followed by the four-digit hexadecimal > + code point number or[,] alternatively[,] a backslash followed by a > plus > + sign [(+)] followed by a six-digit hexadecimal code point number. > > > I've kind of grown fond of "This slightly bizarre behavior"... ;) > I don't disagree :). I was trying to remove the subjectiveness of it. I review the rest of what you said.
