Re: Patch: Improve Boolean Predicate JSON Path Docs

On 2023-10-20 15:49 +0200, David Wheeler wrote:
> On Oct 19, 2023, at 23:49, Erik Wienhold <ewie(at)ewie(dot)name> wrote:
>
> > I don't even know what that represents, probably not some fancy file
> > compression.

That's an AppleSingle file according to [1][2]. It only contains the
resource fork and file name but no data fork.

> Oh, weird. Trying from a webmail client instead.

Thanks.

> + Does JSON path return any item for the specified JSON value? Use only
> + SQL-standard JSON path expressions, not
> + <link linkend="boolean-predicate-path-expressions">predicate check
> + expressions.</link>

Any reason for calling it "predicate check expressions" (e.g. the link
text) and sometimes "predicate path expressions" (e.g. the linked
section title)? I think it should be named consistently to avoid
confusion and also to simplify searching.

> + Returns the result of a JSON path
> + <link linkend="boolean-predicate-path-expressions">predicate
> + check</link> for the specified JSON value. If the result is not Boolean,
> + then <literal>NULL</literal> is returned. Use only with
> + <link linkend="boolean-predicate-path-expressions">predicate check
> + expressions.</link>

Linking the same section twice in the same paragraph seems excessive.

> +<prompt>=&gt;</prompt> <userinput>select jsonb_path_query(:'json', '$.track.segments');</userinput>
> +select jsonb_path_query(:'json', '$.track.segments');

Please remove the second SELECT.

> +<prompt>=&gt;</prompt> <userinput>select jsonb_path_query(:'json', 'strict $.track.segments[0].location');</userinput>
> + jsonb_path_query
> +-------------------
> + [47.763, 13.4034]

Strict mode is unnecessary to get that result and I'd omit it because
the different modes are not introduced yet at this point.

> +<prompt>=&gt;</prompt> <userinput>select jsonb_path_query(:'json', 'strict $.track.segments.size()');</userinput>
> + jsonb_path_query
> +------------------
> + 2

Strict mode is unnecessary here as well.

> + using the lax mode. To avoid surprising results, we recommend using
> + the <literal>.**</literal> accessor only in the strict mode. The

Please change to "in strict mode" (without "the").

[1] https://www.rfc-editor.org/rfc/rfc1740.txt
[2] https://web.archive.org/web/20180311140826/http://kaiser-edv.de/documents/AppleSingle_AppleDouble.pdf

--
Erik