Re: nextval parameter is not clear

On Mon, Nov 28, 2022 at 12:47 PM Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:

> Kirk Wolak <wolakk(at)gmail(dot)com> writes:
> > my goal is to get an "approach" accepted, this is the first.
> Ultimately, I
> > would love to see
> > the documentation of functions with examples like this everywhere.
>
> I'm not for that. func.sgml is already massive, and doubling its size

...
> reference material, so extended examples ought to go somewhere else.
>
> I could see adding a section about sequences and identity columns to
> chapter 3 in the tutorial.
>
> > Preferably where someone
> > can copy/paste the example and see the results.
>
> As far as that goes, there's already an idea that src/tutorial/
> should contain SQL scripts that you can step-execute to follow
> along with the tutorial docs. This hasn't been followed through
> on very well --- chapter 2 is covered, but chapter 3 mostly not.
> No time like the present to make it better, though. If your
> ambition is to make self-contained working examples, making sure
> that they execute as a script is good discipline.
>
> regards, tom lane
>

Two questions follow from the above:
1) For the novice who finds this page (funcs), how will they know to find
the tutorial?
2) Should each function link to that? or One link per page? [to the
appropriate example section]

I will gladly move my focus to adding to the tutorials... (but I want to
know how even I would know it was available if I hit here first)
And I still believe that each function in the documentation section should
have at least a one-line example usage???

After a quick review of the tutorial section, if you end up on any random
page in the tutorial,
the example code does not stand alone.
[I think this was your point]. I see 2 approaches:

A) Simply expand the current examples so that they include the code to make
them stand alone
or
B) Maybe if we had the ENTIRE Tutorial code in one place, runnable
(copy/paste).
Then the more detailed explanations that explain what the statements do,
like we have now.
We would get the best of both worlds?

Thanks, Kirk