Re: BUG #14016: Incomplete documentation of IN subquery expression

On Tue, Apr 26, 2016 at 1:27 PM, Bruce Momjian <bruce@momjian.us> wrote:

> On Fri, Mar 11, 2016 at 10:02:01AM -0700, David G. Johnston wrote:
> > On Fri, Mar 11, 2016 at 9:39 AM, <manlio.perillo@gmail.com> wrote:
> >
> >     At the end of the documentation for VALUE (sql-values.html), there
> is the
> >     following tip:
> >     "For simple IN tests, it's better to rely on the list-of-scalars
> form of IN
> >     than to write a VALUES query as shown above"
> >
> >     However there is no reference to the "list-of-scalars" forms of IN,
> in the
> >     functions-subquery.html page.  It is only reported that the support=
ed
> >     syntax
> >     is "expression IN (subquery)"
> >
> >     The reference was available in an old version (7.3), where the manu=
al
> >     documented both the scalar form and sub query form:
> >     "expression IN (value[, ...])"
> >
> >
> > =E2=80=8BIt was moved...
> >
> > =E2=80=8B
> http://www.postgresql.org/docs/9.5/interactive/functions-comparisons.html=
#
> > AEN20283
> >
> > =E2=80=8BThe interpretation being that a "list of scalars" is, in this =
situation,
> > semantically equivalent to an array - though having the later you would
> have to
> > use "=3DANY(array)" instead of "IN"
> >
> > =E2=80=8BApparently someone disagreed with the note in the subquery sec=
tion:
> >
> > >>>Note: This form of IN is not truly a subquery expression, but it
> seems best
> > to document it in the same place as subquery IN.
>
> Does the attached patch improve this?
>

=E2=80=8BI'd append "scalar" to the id to distinguish in from the subquery
version.  Otherwise any suggest I make seems like overkill.  The main point
being the "list of scalars" is not a term we use on the referenced page,
and the chapter header indicates "Row and Array" of which this is similar
but technically neither.=E2=80=8B

=E2=80=8B<sect2 id=3D"functions-comparisons-in-scalar"> [...]=E2=80=8B

[...] rely on the =E2=80=8B<link
linkend=3D"functions-comparison-in-scalar">array</link> form of [...]=E2=80=
=8B


=E2=80=8BDavid J.=E2=80=8B