Re: nextval parameter is not clear - Mailing list pgsql-docs
| From | David G. Johnston |
|---|---|
| Subject | Re: nextval parameter is not clear |
| Date | |
| Msg-id | CAKFQuwZq4=bjOjcS=Se-jviMWABSnuoh4BHfoze=Tf1MawerSw@mail.gmail.com Whole thread Raw |
| In response to | Re: nextval parameter is not clear (Kirk Wolak <wolakk@gmail.com>) |
| List | pgsql-docs |
On Mon, Nov 28, 2022 at 12:22 PM Kirk Wolak <wolakk@gmail.com> wrote:
On Mon, Nov 28, 2022 at 12:47 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:Kirk Wolak <wolakk@gmail.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 laneTwo 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]
You would add a sentence, as appropriate to the page, pointing the reader to the tutorial section for further examples. There isn't really a rule-of-thumb here; use existing examples and context to figure out what makes the most sense.
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???
There already is guaranteed one example - it is the function signature that begins each row.
On a related point, the word SELECT in table examples is unwanted noise (this page is not the best example to emulate). The example call expressions the supplement the function signature also need not be executable.
The string functions demonstrate good usage examples for the tables.
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.
If you'd like to start a discussion on this I suggest a new email thread, leaving this one to finishing the patch within the reality of the documentation as it exists today. That is to say, making decisions based upon existing prior work and sound arguments about the merits of the content presentation. This isn't the place to experiment and propose an example of some new grand design.
David J.
pgsql-docs by date: