Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256)
	(Exim 4.89)
	(envelope-from <pgsql-hackers-owner+archive@lists.postgresql.org>)
	id 1iC9xG-0004mD-Oe
	for pgsql-hackers@arkaria.postgresql.org; Sun, 22 Sep 2019 22:03:42 +0000
Received: from localhost ([127.0.0.1] helo=malur.postgresql.org)
	by malur.postgresql.org with esmtp (Exim 4.89)
	(envelope-from <pgsql-hackers-owner+archive@lists.postgresql.org>)
	id 1iC9xF-0000V2-GU
	for pgsql-hackers@arkaria.postgresql.org; Sun, 22 Sep 2019 22:03:41 +0000
Received: from makus.postgresql.org ([2001:4800:3e1:1::229])
	by malur.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256)
	(Exim 4.89)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1iC9xE-0000Ut-JW
	for pgsql-hackers@lists.postgresql.org; Sun, 22 Sep 2019 22:03:40 +0000
Received: from sss.pgh.pa.us ([66.207.139.130])
	by makus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1iC9xC-0002vY-As
	for pgsql-hackers@postgresql.org; Sun, 22 Sep 2019 22:03:39 +0000
Received: from sss1.sss.pgh.pa.us (localhost [127.0.0.1])
	by sss.pgh.pa.us (8.14.4/8.14.4) with ESMTP id x8MM3WWN016969;
	Sun, 22 Sep 2019 18:03:33 -0400
From: Tom Lane <tgl@sss.pgh.pa.us>
To: Alexander Korotkov <a.korotkov@postgrespro.ru>
cc: Jeff Janes <jeff.janes@gmail.com>,
        pgsql-hackers <pgsql-hackers@postgresql.org>
Subject: Re: JSONPATH documentation
In-reply-to: 
 <CAPpHfdvYektyqQp-On+dbqO7GV_h=59y=6yGxUm4Pisc2PcDjg@mail.gmail.com>
References: 
 <CAMkU=1wP-SO4KpiLxHJuPezTJCmK=JqefLXrr3eXFO7Qku+tMg@mail.gmail.com>
 <CAPpHfdvYektyqQp-On+dbqO7GV_h=59y=6yGxUm4Pisc2PcDjg@mail.gmail.com>
Comments: In-reply-to Alexander Korotkov <a.korotkov@postgrespro.ru>
	message dated "Sun, 22 Sep 2019 23:56:27 +0300"
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <16967.1569189812.1@sss.pgh.pa.us>
Date: Sun, 22 Sep 2019 18:03:32 -0400
Message-ID: <16968.1569189812@sss.pgh.pa.us>
List-Id: <pgsql-hackers.lists.postgresql.org>
List-Help: <https://lists.postgresql.org/manage/>
List-Subscribe: <https://lists.postgresql.org/manage/>
List-Post: <mailto:pgsql-hackers@lists.postgresql.org>
List-Owner: <mailto:pgsql-hackers-owner@lists.postgresql.org>
List-Archive: <https://www.postgresql.org/list/pgsql-hackers>
Precedence: bulk

Alexander Korotkov <a.korotkov@postgrespro.ru> writes:
> On Sun, Sep 22, 2019 at 9:18 PM Jeff Janes <jeff.janes@gmail.com> wrote:
> Currently description of jsonpath is divided between datatypes section
> and functions and operators section.  And yes, this looks cumbersome.

Agreed, but ...

> I think we should move the whole description to the one section.
> Probably we should move jsonpath description to datatypes section
> (assuming jsonpath is a datatype) leaving functions and operators
> section with just SQL-level functions and operators.  What do you
> think?

... I don't think that's an improvement.  We don't document detailed
behavior of a datatype's functions in datatype.sgml, and this seems
like it would be contrary to that layout.  If anything, I'd merge
the other way, with only a very minimal description of jsonpath
(perhaps none?) in datatype.sgml.

While we're whining about this, I find it very off-putting that
the jsonpath stuff was inserted in the JSON functions section
ahead of the actual JSON functions.  I think it should have
gone after them, because it feels like a barely-related interjection
as it stands.  Maybe there's even a case that it should be
its own <sect1>, after the "functions-json" section.

			regards, tom lane