From: Elena Indrupskaya <e.indrupskaya@postgrespro.ru>
To: Andrew Dunstan <andrew@dunslane.net>
To: Amit Langote <amitlangote09@gmail.com>
To: PostgreSQL-development <pgsql-hackers@postgresql.org>
To: n.gluhov@postgrespro.ru
Subject: Re: SQL/JSON revisited
Date: Wed, 11 Jan 2023 10:02:02 +0300
Message-ID: <c0b12c9a-fd82-c9f8-9727-177c37f261c4@postgrespro.ru> (raw)
In-Reply-To: <073e573c-c3e5-86af-8cb3-4a0ab9e7f968@dunslane.net>
References: <CA+HiwqHROpf9e644D8BRqYvaAPmgBZVup-xKMDPk-nd4EpgzHw@mail.gmail.com>
<98ab8c72-49ad-d1e1-c9b6-8aca3a58e0f4@postgrespro.ru>
<073e573c-c3e5-86af-8cb3-4a0ab9e7f968@dunslane.net>
Tags in the patch follow the markup of the XMLTABLE function:
<function>XMLTABLE</function> (
<optional> <literal>XMLNAMESPACES</literal> (
<replaceable>namespace_uri</replaceable> <literal>AS</literal>
<replaceable>namespace_name</replaceable> <optional>, ...</optional> ),
</optional>
<replaceable>row_expression</replaceable>
<literal>PASSING</literal> <optional><literal>BY</literal>
{<literal>REF</literal>|<literal>VALUE</literal>}</optional>
<replaceable>document_expression</replaceable>
<optional><literal>BY</literal>
{<literal>REF</literal>|<literal>VALUE</literal>}</optional>
<literal>COLUMNS</literal> <replaceable>name</replaceable> {
<replaceable>type</replaceable> <optional><literal>PATH</literal>
<replaceable>column_expression</replaceable></optional>
<optional><literal>DEFAULT</literal>
<replaceable>default_expression</replaceable></optional>
<optional><literal>NOT NULL</literal> | <literal>NULL</literal></optional>
| <literal>FOR ORDINALITY</literal> }
<optional>, ...</optional>
) <returnvalue>setof record</returnvalue>
In the above, as well as in the signatures of SQL/JSON functions, there
are no exact parameter names; otherwise, they should have been followed
by the <type> tag, which is not the case. There are no parameter names
in the functions' code either. Therefore, <replaceable> tags seem more
appropriate, according to the comment to commit 47046763c3.
Sorry for upsetting your bot. :(
--
Elena Indrupskaya
Lead Technical Writer
Postgres Professional http://www.postgrespro.com> On 2023-01-10 Tu 07:51, Elena Indrupskaya wrote:
>> Hi,
>>
>> The Postgres Pro documentation team prepared another SQL/JSON
>> documentation patch (attached), to apply on top of
>> v1-0009-Documentation-for-SQL-JSON-features.patch.
>> The new patch:
>> - Fixes minor typos
>> - Does some rewording agreed with Nikita Glukhov
>> - Updates Docbook markup to make tags consistent across SQL/JSON
>> documentation and across func.sgml, and in particular, consistent with
>> the XMLTABLE function, which resembles SQL/JSON functions pretty much.
>>
> That's nice, but please don't post incremental patches like this. It
> upsets the cfbot. (I wish there were a way to tell the cfbot to ignore
> patches)
>
> Also, I'm fairly certain that a good many of your changes are not
> according to project style. The rule as I understand it is that
> <parameter> is used for things that are parameters and <replaceable> is
> only used for things that are not parameters. (I'm not sure where that's
> documented other than the comment on commit 47046763c3, but it's what I
> attempted to do with the earlier doc tidy up.)
>
>
> cheers
>
>
> andrew
>
> --
> Andrew Dunstan
> EDB: https://www.enterprisedb.com
>
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-hackers@postgresql.org
Cc: e.indrupskaya@postgrespro.ru, andrew@dunslane.net, amitlangote09@gmail.com, n.gluhov@postgrespro.ru
Subject: Re: SQL/JSON revisited
In-Reply-To: <c0b12c9a-fd82-c9f8-9727-177c37f261c4@postgrespro.ru>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox