Re: Cleanup of syntax.sgml

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