pg.ddx.io  pgsql-docs@postgresql.org mailing list archive  

help / color / mirror / Atom feed
From: Tom Lane <tgl@sss.pgh.pa.us>
To: Kirk Wolak <wolakk@gmail.com>
Cc: Laurenz Albe <laurenz.albe@cybertec.at>
Cc: David G. Johnston <david.g.johnston@gmail.com>
Cc: Bruce Momjian <bruce@momjian.us>
Cc: ailjushkin@gmail.com
Cc: pgsql-docs@lists.postgresql.org
Subject: Re: nextval parameter is not clear
Date: Mon, 28 Nov 2022 12:47:00 -0500
Message-ID: <635775.1669657620@sss.pgh.pa.us> (raw)
In-Reply-To: <CACLU5mTHue1aNhbSND+exLs3jHHO=UnAr3g6ZBaEhOhkK0et5w@mail.gmail.com>
References: <166608103231.2042183.13992576112735261253@wrigleys.postgresql.org>
	<Y30ekxQpiIaG9eSl@momjian.us>
	<CACLU5mQBVn+cyeAAbs7O6c8h14MBurhuxpp7z+TXWo2+vQcO+w@mail.gmail.com>
	<CAKFQuwau7CpY+TLufpU1RPPzyLzjS0mvrXnSLf+eGSUJS-_pRQ@mail.gmail.com>
	<CACLU5mQ1LTz9BnG-bbfCmwzytyUFwej90XBnFtQJKQkubS9Khw@mail.gmail.com>
	<CACLU5mTKsNgWfY9qcsn1fhMRXbfJ0M8bPEwgXbmanxVgdKPQ7A@mail.gmail.com>
	<CACLU5mS4b3xM-tuMpT2oP-pqwwnHJbSeLDBzZSs9Lq_ObgMu7Q@mail.gmail.com>
	<21e017222199f3ca397fa70549140d226236e4b6.camel@cybertec.at>
	<CACLU5mShHGjroH=Cp_k6i-T+357_Fhxahc5NqpNPoJnN56GyFg@mail.gmail.com>
	<CAKFQuwarCJs9bbgJ9_PtsCBJKmSM1UnLx80J5JUJm1eJyYzHXQ@mail.gmail.com>
	<CACLU5mRn-xHKP9irkBQvYCQYKNDCcud66zJHHaHNHoOMA4kmVQ@mail.gmail.com>
	<0c0eddb287571e72a2df1be8758fbbb0cb7cc378.camel@cybertec.at>
	<CAKFQuwYuu_FrZZ=TEdUPdB4c-hbsCHSKD+XSUdDFrGnaDMQ_=A@mail.gmail.com>
	<CACLU5mTmEieU-uTF6bNm9T5Y94gd1g_cgz_JDLz6Qw36RjcBHQ@mail.gmail.com>
	<f7a51be79a5146740954e0b9b70515529a1d944b.camel@cybertec.at>
	<45249! 3.1669614328@sss.pgh.pa.us>
	<CACLU5mTHue1aNhbSND+exLs3jHHO=UnAr3g6ZBaEhOhkK0et5w@mail.gmail.com>

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
with extensive examples doesn't seem like an improvement.  Admittedly,
we probably don't need long examples for many of the functions, so maybe
we wouldn't end up with quite that much bloat; but it still seems like
the wrong approach.  In my view, that chapter is more in the nature of
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





view thread (29+ messages)  latest in thread

Message-ID: <635775.1669657620@sss.pgh.pa.us>
Permalink:  ../635775.1669657620@sss.pgh.pa.us/
Also on:    postgresql.org/message-id/635775.1669657620@sss.pgh.pa.us

 · 

reply
Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: pgsql-docs@postgresql.org
  Cc: tgl@sss.pgh.pa.us, wolakk@gmail.com, laurenz.albe@cybertec.at, david.g.johnston@gmail.com, bruce@momjian.us, ailjushkin@gmail.com, pgsql-docs@lists.postgresql.org
  Subject: Re: nextval parameter is not clear
  In-Reply-To: <635775.1669657620@sss.pgh.pa.us>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox