Subject: Re: documentation structure

From: Corey Huinker <[email-masked]>
Date: Thu, 18 Apr 2024 13:51:10 -0400

>
> I havent dealt with variadic yet, since the two styles are visually
> different, not just markup (<optional>...</optional> renders as [...]).
>
> The two styles for variadic are the what I call caller-style:
>
>    concat ( val1 "any" [, val2 "any" [, ...] ] )
>    format(formatstr text [, formatarg "any" [, ...] ])
>

While this style is obviously clumsier for us to compose, it does avoid
relying on the user understanding what the word variadic means. Searching
through online documentation of the python *args parameter, the word
variadic never comes up, the closest they get is "variable length
argument". I realize that python is not SQL, but I think it's a good point
of reference for what concepts the average reader is likely to know.

Looking at the patch, I think it is good, though I'd consider doing some
indentation for the nested <optional>s to allow the author to do more
visual tag-matching. The ']'s were sufficiently visually distinct that we
didn't really need or want nesting, but <optional> is just another tag to
my eyes in a sea of tags.

---

From: Dagfinn Ilmari Mannsåker <[email-masked]>
Date: Thu, 18 Apr 2024 22:34:26 +0100

> of reference for what concepts the average reader is likely to know.

Yeah, we can't expect everyone wanting to call a built-in function to
know how they would define an equivalent one themselves. In that case I
propos marking it up like this:

    <function>format</function> (
    <parameter>formatstr</parameter> <type>text</type>
    <optional>, <parameter>formatarg</parameter> <type>"any"</type>
    <optional>, ...</optional> </optional> )
    <returnvalue>text</returnvalue>

> my eyes in a sea of tags.

The requisite nesting when there are multiple optional parameters makes
it annoying to wrap and indent it "properly" per XML convention, but how
about something like this, with each parameter on a line of its own, and
all the closing </optional> tags on one line?

    <function>regexp_substr</function> (
    <parameter>string</parameter> <type>text</type>,
    <parameter>pattern</parameter> <type>text</type>
    <optional>, <parameter>start</parameter> <type>integer</type>
    <optional>, <parameter>N</parameter> <type>integer</type>
    <optional>, <parameter>flags</parameter> <type>text</type>
    <optional>, <parameter>subexpr</parameter> <type>integer</type>
    </optional> </optional> </optional> </optional> )
    <returnvalue>text</returnvalue>

A lot of functions mostly follow this style, except they tend to put the
first parameter on the same line of the function namee, even when that
makes the line overly long. I propose going the other way, with each
parameter on a line of its own, even if the first one would fit after
the function name, except the whole parameter list fits after the
function name.

Also, when there's only one optional argument, or they're independently
optional, not nested, the </optional> tag should go on the same line as
the parameter.

    <function>substring</function> (
    <parameter>bits</parameter> <type>bit</type>
    <optional> <literal>FROM</literal> <parameter>start</parameter> <type>integer</type> </optional>
    <optional> <literal>FOR</literal> <parameter>count</parameter> <type>integer</type> </optional> )
    <returnvalue>bit</returnvalue>

I'm not quite sure what to with things like json_object which have even
more complex nexting of optional parameters, but I do think the current
200+ character lines are too long.

- ilmari

---

From: Corey Huinker <[email-masked]>
Date: Thu, 18 Apr 2024 20:57:17 -0400

>     <returnvalue>text</returnvalue>

Looks good, but I guess I have to ask: is there a parameter-list tag out
there instead of (, and should we be using that?

>     <returnvalue>text</returnvalue>

Yes, that has an easy count-the-vertical, count-the-horizontal,
do-they-match flow to it.

> the function name, except the whole parameter list fits after the

+1

>     <returnvalue>bit</returnvalue>

+1