Re: SQL/JSON: documentation

On 09/28/2018 08:29 PM, Peter Eisentraut wrote:
> On 28/06/2018 01:36, Nikita Glukhov wrote:
>> Attached patch with draft of SQL/JSON documentation written by
>> Liudmila Mantrova, Oleg Bartunov and me.
>>
>> Also it can be found in our sqljson repository on sqljson_doc branch:
>> https://github.com/postgrespro/sqljson/tree/sqljson_doc
>>
>> We continue to work on it.
> Some structural comments:
>
> - I don't think this should be moved to a separate file. Yes, func.sgml
> is pretty big, but if we're going to split it up, we should do it in a
> systematic way, not just one section.
>
> - The refentries are not a bad idea, but again, if we just used them for
> this one section, the navigation will behave weirdly. So I'd do it
> without them, just using normal subsections.
>
> - Stick to one-space indentation in XML.
>
Hi Peter,

Thanks for your comments! I'm OK with keeping all reference information
in func.sgml and will rework it as you suggest. While refentries are
dear to my heart, let's use subsections for now for the sake of
consistency. We'll continue working with Nikita and Oleg to improve the
content before we resend an updated patch; I believe we might still need
a separate source file if we end up having a separate chapter with usage
examples and implementation details.

--
Liudmila Mantrova
Technical writer at Postgres Professional: http://www.postgrespro.com
The Russian Postgres Company