On Wednesday 28 August 2002 05:06 pm, Bruce Momjian wrote:
> Peter Eisentraut wrote:
> > Bruce Momjian writes:
> > > That SELECT syntax is already too confusing. I don't want to add an
> > > additional documentation specification that provides no value to users.
> >
> > The value of the documentation, especially the reference manual, is that
> > it provides an authorative source of what works and what doesn't. It is
> > not the place to hide transitional phases. Moreover, the least possible
> > value you could provide to users is to gratuitously[*] change the syntax
> > and not tell anyone about it.
> >
> > In fact, the recent trend in the SQL commands has been to accept most
> > options in any order, so it would only be logical to accept the LIMIT and
> > FOR UDPATE options in any order and document that fact. There is a
> > separate section in each reference page for information about which
> > format is compatible with what.
> >
> > But please remember that our foremost goal is to be compatible, both in
> > actuality and in mindset, with PostgreSQL, not with any other product
> > that happened to use a slightly different syntax at their whim.
> >
> > Therefore I request that both forms be accepted and documented as equally
> > valid.
>
> You made the same argument for the COPY syntax, that we publish both the
> old and new syntaxes, and I resisted because I felt most people would
> rather just see the best syntax. I don't see the documentation as
> showing every possible syntax because that really doesn't benefit users,
> or should I say confused more than it helps.
>
> If you would like a vote, we can do that, but as I remember we had the
> same issue with COPY and we got most votes to just show the best syntax.
There are two cases where I see potential problems; first would be someone
trying to migrate from pre 7.3 who sees the "new" documentation and thinks
that part of his upgrade path is going to require rewriting X number of
queries/scripts/whatever... Second will be someone that comes in and needs to
work on some legacy code and what he looks at is directly in contrast to what
is in the documentation, but it appears to run fine. Both of these cases are
going to cause people confusion and when they post to the mailing list we'll
be denied an opportunity to just blurt out in all caps RTFM! :-)
I can assure you that both of these issues will be entered into the
interactive documents at some point, I'd just feel better if it we're in
there by default.
Robert Treat
