Re: Doc Rework: Section 9.16.13 SQL/JSON Query Functions

On Fri, Jun 28, 2024 at 2:56 PM Amit Langote <amitlangote09(at)gmail(dot)com> wrote:
> On Tue, Jun 25, 2024 at 3:47 PM David G. Johnston
> <david(dot)g(dot)johnston(at)gmail(dot)com> wrote:
> >
> > Hey!
> >
> > Lots of SQL/JSON threads going about. This one is less about technical correctness and more about usability of the documentation. Though in writing this I am finding some things that aren't quite clear. I'm going to come back with those on a follow-on post once I get a chance to make my second pass on this. But for the moment just opening it up to a content and structure review.
> >
> > Please focus on the text changes. It passes "check-docs" but I still need to work on layout and stuff in html (markup, some more links).
> >
> > Thanks!
> >
> > David J.
> >
> > p.s. v1 exists here (is just the idea of using basically variable names in the function signature and minimizing direct syntax in the table);
> >
> > https://www.postgresql.org/message-id/CAKFQuwbYBvUZasGj_ZnfXhC2kk4AT%3DepwGkNd2%3DRMMVXkfTNMQ%40mail.gmail.com
>
> Thanks for writing the patch. I'll take a look at this next Monday.

I've attached a delta (0002) against your patch, wherein I've kept
most of the structuring changes you've proposed, but made changes such
as:

* use tags consistently
* use language matching the rest of func.sgml, IMO
* avoid repetition (eg. context_item described both above and below the table)
* correcting some factual discrepancies (eg. json_value never returns json null)
* avoid forward references
* capitalize function names, SQL keywords in examples as requested in
a previous review [1]

Maybe we could still polish this some more.

--
Thanks, Amit Langote

[1] https://www.postgresql.org/message-id/CAA-aLv7Dfy9BMrhUZ1skcg%3DOdqysWKzObS7XiDXdotJNF0E44Q%40mail.gmail.com