Re: Cleanup of syntax.sgml - Mailing list pgsql-docs

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.

 Reviewing this reminds me we are inconsistent regarding "key word" vs. "keyword".

"We advise users who to read this chapter carefully  ..." ? botched surgery on this one

Not sure I agree with removing the comment regarding "end of the input stream".

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? 

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.

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

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 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.

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"... ;)