Re: nextval parameter is not clear

On Tue, Nov 22, 2022 at 11:43 PM David G. Johnston <
david(dot)g(dot)johnston(at)gmail(dot)com> wrote:

> On Tue, Nov 22, 2022 at 8:42 PM Kirk Wolak <wolakk(at)gmail(dot)com> wrote:
>
>>
>>
>> On Tue, Nov 22, 2022 at 2:10 PM Bruce Momjian <bruce(at)momjian(dot)us> wrote:
>>
>>> On Tue, Oct 18, 2022 at 08:17:12AM +0000, PG Doc comments form wrote:
>>> > The following documentation comment has been logged on the website:
>>> >
>>> > Page: https://www.postgresql.org/docs/14/functions-sequence.html
>>> > Description:
>>> >
>>> > https://www.postgresql.org/docs/14/functions-sequence.html
>>> >
>>> > I don't see here any hints about how to use this function, and what the
>>> > Maybe add some links to other topics or clarify examples for nextval
>>> here.
>>>
>>> We've only fairly recently made incorporating useful and expansive
> examples into the reference part of the documentation generally doable. I
> agree that this particular one warrants such an example. If you are
> willing to do the harder work you describe below, submit a patch for this.
> It's specific, small, an improvement, and nothing Bruce said indicates it
> isn't wanted, he just focused on a different aspect of the complaint.
> ..
> The wiki is an excellent place to prototype and coordinate. Beyond that,
> this idea falls outside what should be discussed on this thread. Here,
> let's either patch the docs with some examples, or not.
>
> David J.
>

David, as requested. I took this page, and created examples in each row of
each function.
I took a little liberty to normalize the warning about the error message
between the last 2 functions (currval()/lastval()).
I also decorated the comments with -- prefix (because I HATE not being able
to quickly copy code and paste and use it).
Also, I added a CREATE SEQUENCE in each block, so that the resulting code
will work if you cut/paste it in.
[Who knows, eventually we could add CSS that adds the copy and maybe an
Open in PGFiddle someday]

Now I edited this as pure sgml. I have no idea how to make this into html
to view. Do you guys use specific tooling?

Have a look. Cut it to shreds. But I believe this is functional and
informative.

Regards Kirk