Re: SQL/JSON revisited - Mailing list pgsql-hackers

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
>