Re: SQL/JSON revisited

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
>